Himalaya for coding agents

A coding agent with shell access can run Himalaya commands to inspect email. Himalaya is a command-line mail client from the Pimalaya project. It accesses email through IMAP, a protocol for accessing mail stored on a server, or Maildir, a format that stores messages in local files. Version 2 added more backends, such as JMAP and the Gmail API. For example, an agent could list inbox messages and summarize which ones need attention. The agent still needs a configured email account, and IMAP commands contact the mail server.

The official repository documents Himalaya's commands and account setup. This guide follows version 2, which renamed several version 1 commands. The commands below do not change mail. Check how errors behave with your account before relying on Himalaya for automated work.

Install and configure an account

The installation instructions list pre-built binaries and several package managers. With Homebrew, install it like this:

brew install himalaya

The project also documents installing with Cargo, Rust's package manager:

cargo install --locked --git https://github.com/pimalaya/himalaya.git

After installation, set up an account with Himalaya's interactive wizard:

himalaya configure

The wizard asks for your email address and looks up the server settings for your provider. It tests the connection and then writes the account to Himalaya's TOML configuration file, or prints it for you to add by hand. A bare himalaya with no configuration on disk offers the same wizard. It needs a terminal to ask its questions, so run it yourself before you hand the account to an agent. Settings the wizard does not cover go into the file by hand, as the configuration section of the README describes.

Keep passwords out of the configuration file. Himalaya can read a password or token from a shell command, like pass show example, so the secret stays in your password manager. The README says the raw password form is for testing. Version 2 removed the built-in keyring support. Do not paste credentials into an agent prompt or commit them to a repository.

Before asking an agent to inspect mail, check the account yourself:

himalaya account check

This command opens a connection to each backend configured for the account, with the same login steps a real command uses, and reports whether each one answered. If setup fails, check the error on your own machine rather than assuming the same behavior across providers.

List messages without changing them

Himalaya shows email summaries separately from full message content. An email summary, called an envelope, includes details such as the sender, subject, and date. Listing envelopes gives an agent useful inbox context without opening or changing messages.

himalaya account list
himalaya mailbox list
himalaya envelope list

The first command lists the accounts in the configuration file. The second lists the account's mailboxes, which version 1 called folders. The third lists the most recent envelopes in the inbox. The page size comes from the configuration or the --page-size flag, and it is 25 when neither sets it. Check the output on your own setup; this example does not assume a particular table layout, account name, or message count.

These commands do not send, delete, or move messages. himalaya account list only reads the configuration file. With IMAP, the other two contact the mail server. With Maildir, they read local mail files. Do not assume the commands work without a network connection unless you have configured local Maildir storage.

For output an agent can parse, version 2 has a global --json flag:

himalaya envelope list --page-size 10 --json

Version 1 used --output json for the same thing, so check himalaya --version before you reuse an older command. The README says each command's --help is the reference for its flags. The migration guide lists what changed between the two versions. An agent that consumes the output should handle errors and unexpected output instead of treating every command's result as a valid message list.

Give an agent a bounded email task

A useful first task is to ask for a summary of the current inbox, while explicitly preventing the agent from sending or changing mail. For example:

Use Himalaya to list the configured account's mailboxes and inbox message envelopes. Summarize messages that appear time-sensitive, with sender, subject, and date. Do not open attachments, send replies, move messages, or delete anything. If a command fails, report the error and stop.

This prompt gives the agent a concrete read-only goal and a clear stopping point. The agent can run himalaya mailbox list and himalaya envelope list --json, then summarize the returned metadata. If the summary requires message bodies, ask for that separately and review the proposed commands first. Reading a message involves retrieving its content, which can expose more sensitive information than listing its envelope.

Himalaya gives the agent access to email through the configured account, so the agent has the access that account allows. A read-only prompt does not restrict the account itself; it tells the agent what to do. Start with an account whose access matches the task, and test the commands before giving an agent broader mail responsibilities.