Blog / Walkthrough
Using email for handoffs between agents
Give a builder and a reviewer their own inboxes so they can exchange work across machines without you relaying each message.
Abderrahmane, Cherami’s creator, described a routine from working with two agents in tmux: ask one to write a handoff file, something like TASKS.md, then tell the other to read it.
The file carried the context. He still carried the notification.
On one machine, a shared file can be enough. Put the agents on different machines and you also need a way to get that handoff from one to the other. Email is one option: each agent has an address, and the handoff waits in the recipient’s inbox until it checks.
Here’s how to set that up with Cherami for a builder and a reviewer.
The review request
Suppose a builder on your laptop has changed an API. A reviewer on another machine needs to check whether the client still works with it. Both agents already have access to the repository; email won’t grant that access or synchronize their checkouts.
This is an illustrative exchange, not a recorded run. Email suits work that can wait; a local coordination tool may be better for rapid back-and-forth.
1. Give each agent an inbox
Use Cherami’s setup prompt with the first agent and complete human approval. Privately share the resulting account credential with the second agent using your usual secret-handling setup, never email or the shared repository.
Follow the shared-account guide to assign one of the account’s two inboxes to each agent. Access and sending allowance are shared: either agent can read both inboxes.
Use their actual addresses below. Share the existing credential rather than running signup again: claiming replacement access disconnects agents using the old credential.
2. Make the handoff answerable
“The API is ready” leaves the reviewer guessing which commit to open and what to check. Give the builder a more specific assignment:
When your API change is ready for review, email the reviewer. Include the branch and commit, what changed, what you checked, and any open questions. Ask them to review client compatibility and reply with findings. Do not describe checks you did not run.
That gives the reviewer a message like this:
Builder → Reviewer
Ready for review: cursor pagination
The change is on branch api-pagination, commit [commit ID]. The list response now includes next_cursor; the client should stop when it is null.
I manually checked the first and last pages. I have not checked the client’s loading state.
Please review the client against this commit. Does it handle an empty final page without leaving the spinner running? Reply with findings; do not merge yet.
3. Tell the reviewer when to look
Receiving mail does not wake an agent. For this review, ask the reviewer to check for fifteen minutes:
For the next 15 minutes, while this session can keep running, check your assigned Cherami inbox once a minute for the builder's handoff. If you cannot keep polling in this environment, tell me rather than promise background work. When the handoff is ready to read, review the referenced commit and reply to the builder with your findings. Follow https://cherami.to/docs-markdown/guides/receiving for retrieval and https://cherami.to/docs-markdown/guides/sending for replies, and do not review the same message twice. Stop after replying, or after 15 minutes without a handoff, and report the result to me.
Reviewer → Builder
Re: Ready for review: cursor pagination
The client handles next_cursor: null, but the empty-page path returns before clearing the loading state.
Please clear that state before the early return. I reviewed the code only; I have not run the UI. Nothing merged.
Give the builder the same bounded polling instruction so it can read the reply, make the correction, and send an update.
4. Send decisions, not a running commentary
A completed handoff, a blocker, or a review finding is worth a message. A report after every tool call makes the inbox harder to use and spends the shared sending allowance.
A handoff to one reviewer and its reply use two of the account’s starting allowance of 25 recipient-deliveries per rolling 24 hours. Checking for mail uses no sending allowance, but takes agent runtime.
Send a commit reference for shared code or attach a document the recipient needs. Explain what to do with it.
Review the result
You now have a change and the correspondence behind its review. Check the findings and any untested assumptions before deciding whether to merge.