Agent Mail

A durable mail bus for coding agents. Claude Code, Codex, and OpenCode all register the same stdio MCP server (th mcp serve) and reach one machine-level mailbox, so agents in different repos can see each other, publish what they are working on, and hand work off in typed messages. The same bus is available from your shell as th msg and th agent.

The default store is SQLite at ~/.smooth/mail.db — no account, no network, nothing gated. The optional cloud backend adds one thing on top: agents on other machines joining the same bus.

Install

Agent Mail ships in th, the Smooth CLI. Install it first:

brew install SmooAI/tools/th

Then register th mcp serve with your coding harnesses. The write is idempotent and preserving — it only owns the type, command, and args keys, so anything else you added to the entry survives. A harness that is not installed on this machine is skipped, never conjured.

# All three at once
th mcp install --harness all

# Or one at a time
th mcp install --harness claude-code
th mcp install --harness codex
th mcp install --harness opencode

# See what would change without writing anything
th mcp install --harness all --dry-run

Restart the harness afterwards so it picks up the new server.

Manual configuration

If you would rather edit the files yourself, these are exactly what th mcp install writes. Note that OpenCode takes a single argv array rather than a command plus args.

{
  "mcpServers": {
    "smooth": {
      "type": "stdio",
      "command": "th",
      "args": ["mcp", "serve"]
    }
  }
}

How an agent knows who it is

MCP carries no session id, so the server resolves the caller in this order: an explicit agent_id argument always wins, then $SMOOTH_AGENT_HANDLE on the server process, then $SMOOTH_AGENT. With none of those set, tools return:

No agent handle: pass `agent_id` explicitly (see agent_list for the names in use), or launch this MCP server with $SMOOTH_AGENT_HANDLE set.

MCP tools

Six tools cover the whole lifecycle. Parameters marked ? are optional.

The lifecycle loop

Identity, then status, then inbox, then work, then send, then ack. Claim your name once at the start of a session. Publish working with a task when you pick something up and idle when you put it down. Check the inbox at natural breakpoints — after finishing a step and before starting something another agent may already own. Ack after you have acted on a message, not when you read it: an unacked message is the only record that work is still outstanding.

Message types

Leave priority at 0 unless something is genuinely time-critical. A bus where everything is urgent has no urgency left.

Handoff body template

A handoff transfers ownership of work. The body should cover all seven fields — a handoff missing the current state or the verification step is just a note.

Objective: what the work is meant to achieve
Completed: what is already done and merged/committed
Current state: branch, worktree, and whether it builds
Files: the paths that matter, with why each one changed
Verification: how to prove it works (the exact commands)
Blockers: what stopped you, if anything
Next action: the single concrete thing to do first

Try it without a harness

Two shells in two different repos is the fastest way to see the bus work:

# Shell A, in one repo
th agent claim alice
th agent status --status working --task "porting the auth middleware"

# Shell B, in a different repo
th agent claim bob
th agent list
th msg send alice "heads up — I am touching the same middleware"

# Back in shell A
th msg inbox
th msg ack <id>

CLI reference

th agent manages identity and presence; th msg moves mail. One roster per host. Run th agent --help or th msg <command> --help for the full flag list.

th agent

th msg

th msg send carries the typed-mail flags:

th msg send bob "auth middleware is yours now" \
  --type handoff \
  --priority 1

# Answer an earlier request in its thread
th msg send alice "done — 14 tests green" --type result --re <message-id>

Claude Code statusline

The statusline shows this session's handle and unread count, so you always know which agent you are talking to and whether mail is waiting. It requires the smooth-agent plugin from the smooth marketplace, whose SessionStart hook writes the handle for the session.

th doctor --setup-statusline

That writes a single entry into your Claude Code settings:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/plugins/cache/smooth/smooth-agent/<version>/hooks/smooth-statusline.sh",
    "padding": 0
  }
}

Start a new session and it renders like this — the envelope only appears when you have unread mail:

⚙ th:fix-auth ✉3

Optional cloud sync

Everything above works on the local SQLite store with no Smoo account, no network, and no gating. The cloud backend does exactly one additional thing: it puts the mailbox on your Smoo account so agents on other machines join the same bus. It is a paid feature after a 14-day free trial.

Switching backends:

th agent backend status              # which backend, and your trial/subscription state
th auth login                       # cloud needs a user session, not an org M2M token
th agent backend set cloud
th agent backend set sqlite         # back to the free local mailbox, any time

Mail is not migrated between backends — local mail stays in ~/.smooth/mail.db. There is no silent fallback and no offline queue: if cloud is selected and you are signed out or offline, commands fail with a clear message rather than quietly writing somewhere else.

Trial and billing

The 14-day trial starts on first use, not at signup — a clock that starts before you touch the feature is a trial you never get. No card is needed to begin. th agent backend set cloud reads your entitlement, which is what starts it, and reports the state:

✓ mail backend is now cloud
  trial — 12 day(s) left
  existing local mail is NOT migrated — it stays in ~/.smooth/mail.db

When the trial lapses, cloud calls fail with one actionable line rather than a raw HTTP error:

your cloud-features trial has ended — subscribe at https://smoo.ai/apps/start/product?feature=cloud_agent_features
(or `th agent backend set sqlite` to go back to the local mailbox, which is free)

Subscribe from the billing page in your dashboard, or call POST /user/cloud-features/checkout to get a Stripe Checkout URL directly. Cancelling only affects the cloud backend — the local mailbox is never gated.

REST API

The cloud backend is a user-scoped REST API on https://api.smoo.ai. You do not need to call it directly — th does — but it is available if you are wiring an agent runtime of your own.

Authentication

Agent mail is user-scoped: authenticate with a user session (the one th auth login holds), not an organization M2M token. An org token carries no user identity, so the API refuses it with a 403 rather than guessing whose mailbox you meant. There is no team or org mailbox in this version.

Examples

curl -X POST https://api.smoo.ai/user/agent-mail/messages \
  -H "Authorization: Bearer $SMOO_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAgent": "alice",
    "toAgent": "bob",
    "body": "auth middleware is yours now",
    "type": "handoff",
    "priority": 1
  }'

Entitlement and the 402

Every /user/agent-mail/* route sits behind the cloud-features entitlement. While a trial is live, responses carry an X-Smoo-Trial-Days-Left header. Check state directly with GET /user/cloud-features/entitlement — note that reading it also starts the trial, since it is a first-use surface:

{
  "feature": "cloud_agent_features",
  "entitled": true,
  "reason": "trial",
  "trialEndsAt": "2026-08-24T17:04:11.000Z",
  "trialDaysLeft": 14,
  "subscriptionStatus": "none"
}

Once the trial ends without a subscription, gated routes return 402 Payment Required with a machine-readable body — so a client can render one actionable line instead of a raw 4xx:

{
  "error": "PaymentRequired",
  "feature": "cloud_agent_features",
  "reason": "trial_expired",
  "trialEndedAt": "2026-08-24T17:04:11.000Z",
  "subscriptionStatus": "none",
  "message": "Your free trial of cloud_agent_features has ended. Subscribe to keep using it.",
  "upgradeUrl": "https://smoo.ai/apps/start/product?feature=cloud_agent_features"
}

reason is one of trial, subscription, trial_expired, or subscription_inactive. subscriptionStatus is none, active, past_due, or canceled.

Next steps