This article follows the official documentation. We haven’t tested this tool for a hands-on review.
When a coding agent needs email context for a task, Notmuch searches a local mail archive from the command line. It builds a searchable index of messages and groups related messages into threads, so the agent can find and read discussions without using Notmuch to log in to a mailbox.
Notmuch is an email search tool. It does not receive or send email, and it has no network code. You need a local email archive that Notmuch has indexed. For a coding task, an agent can search that archive for a project discussion, inspect the matching messages, and use the relevant details while leaving the archive unchanged.
Set up a local mail archive
On Linux, the getting-started guide recommends installing Notmuch from your distribution’s package repository. The install command varies by operating system. Notmuch needs your mail stored one message per file, as in Maildir. It does not work with mbox files, where one file holds many messages. Then run:
notmuch setup
notmuch new
notmuch setup asks a few questions, including the path to your mail archive. It writes the answers to the file named in NOTMUCH_CONFIG, or to ~/.notmuch-config if that variable is not set. notmuch new scans that archive and builds or updates Notmuch’s local index. The setup documentation and notmuch new documentation describe these commands.
Notmuch does not fetch email or authenticate to a mail provider. If you need to sync your archive, the getting-started guide names separate tools such as offlineimap or mbsync. They handle the network connection and credentials, and you run notmuch new afterwards to index the new messages. Once messages are indexed, Notmuch searches the local archive; the search commands below do not contact a mail server.
Search a project discussion
To have the agent find a migration-plan message, replace the example sender and subject with values from your mail archive:
notmuch search 'from:[email protected] subject:"migration plan"'
The search expression checks for a sender and a phrase in the subject. Notmuch’s search documentation describes supported search terms and output options. By default, notmuch search prints one summary line per matching thread. Each line includes the thread ID and date, along with the matched and total message counts, authors, and subject. It does not print the full message body. If the agent should parse the result, add --format=json.
Use the thread ID from a matching line to inspect that conversation:
notmuch show 'thread:THREAD_ID'
Replace THREAD_ID with the ID Notmuch returned. notmuch show displays the messages in the selected thread; see the notmuch show documentation for its output formats. These commands read the local index and message files. They do not send, delete, or modify email.
A coding agent can use these commands to find a design decision, read the discussion, and apply the decision to a code change. For example, ask: “Search my indexed email for the discussion about the migration plan from the maintainer, read the matching thread, and summarize the decision and any constraints. Do not change files or send email.” The agent needs access to the configured local mail archive. Limit its access to the mail the task requires.
Know what Notmuch cannot find
Free text in a Notmuch query matches the subject and the body. It also matches the sender and recipient headers. For other parts of a message, you use a search prefix. The search terms page lists the built-in prefixes, like from: and subject:. A header without a prefix can’t be searched by name, so a query that depends on it can return no results even when a matching email exists. To search another header, define your own prefix with the index.header setting described in the configuration documentation.
Notmuch also does not replace a mail client. It can retrieve local messages, but another tool must handle tasks such as syncing mail or composing and sending replies. Keep provider credentials in the configuration used by the sync tool; the agent’s prompt should contain the search task, not passwords or tokens.
For more command-line tools that coding agents can use, see Awesome CLI.