Clawmail

Canonical agent coordination contract for joelclaw.

joelclaw mail is the only supported mail access surface for pi agents. Do not call mcp_agent_mail HTTP endpoints directly from agent prompts or role instructions.

Topology

Agent-mail is a Central service, not a mailbox per machine:

• Flagg hosts the authoritative daemon on 127.0.0.1:8765.
• Blaine and Panda run com.joelclaw.agent-mail-tunnel, forwarding their local 127.0.0.1:8765 to Flagg over SSH.
• Satellite/Relay clients keep using the default local URL. The tunnel preserves the CLI contract without exposing the unauthenticated service on the tailnet.
• Do not start an independent agent-mail daemon on a satellite. A healthy client must report the same mailbox/project counts as Flagg.

Tracked connector assets:

• infra/agent-mail-tunnel.sh
• infra/launchd/com.joelclaw.agent-mail-tunnel.plist

Interfaces

Canonical interface

• joelclaw mail ... (CLI)

Pi wrapper tools (allowed, but still CLI-backed)

These wrappers shell to joelclaw mail under the hood:

Required Protocol (default for shared work)

1. Check inbox before touching files
   • joelclaw mail inbox --agent <AgentName> --unread
2. Announce active scope
   • joelclaw mail send --from <AgentName> --to <AgentName|team> --subject "Starting: <work>" "intent + paths + expected output"
3. Reserve file paths before edits
   • joelclaw mail reserve --agent <AgentName> --paths "path/a.ts,path/b.ts" [--ttl-seconds 900]
4. If work runs long, renew reservation lease
   • joelclaw mail renew --agent <AgentName> --paths "path/a.ts" [--extend-seconds 900]
5. Send status/handoff updates during work
   • joelclaw mail send --subject "Status: ..." ...
6. Release reservations after commit/handoff
   • joelclaw mail release --agent <AgentName> --paths "..."
   • or --all when done with all reserved paths

Subject Taxonomy (for searchability + steering)

Use these prefixes consistently:

• Starting: — work start / intent announcement
• Task: — handoff or assignment
• Status: — progress update
• Blocked: — dependency/incident requiring intervention
• Done: — completion with artifact/commit IDs

Daily steering uses these signals to detect protocol drift.

Command Quick Reference

# server + inbox health
joelclaw mail status

# register / refresh identity metadata
joelclaw mail register --agent MaroonReef --program pi --model gpt-5.4 --task "interactive"

# send a coordination message
joelclaw mail send --from MaroonReef --to BlueFox --subject "Task: update prompt docs" "Please edit SYSTEM.md and roles/*.md"

# inbox / read
joelclaw mail inbox --agent MaroonReef --unread
joelclaw mail read --agent MaroonReef --id 12

# reservations
joelclaw mail reserve --agent MaroonReef --paths "SYSTEM.md,roles/interactive.md" --ttl-seconds 900
joelclaw mail renew --agent MaroonReef --paths "SYSTEM.md" --extend-seconds 900
joelclaw mail release --agent MaroonReef --paths "SYSTEM.md,roles/interactive.md"
joelclaw mail release --agent MaroonReef --all

# audit/search
joelclaw mail locks
joelclaw mail search --query "Starting:"

Reliability Checks

Verify protocol health quickly

joelclaw mail status
joelclaw mail locks
joelclaw mail search --query "Starting:"
joelclaw mail search --query "Status:"

joelclaw mail locks should reflect active advisory file reservations from the local git-mailbox file_reservations/ artifacts when that repo is available. This matters because the raw /mail/api/locks endpoint can under-report file reservations while still showing mailbox-internal archive/commit locks.

If search is degraded (DB/tool errors)

• Treat signal counts as unreliable.
• Continue using protocol anyway (announce/reserve/release).
• Escalate to mail backend health repair and log findings.

If CLI flags are rejected unexpectedly

• Your compiled ~/.bun/bin/joelclaw may be stale relative to source.
• Rebuild CLI from packages/cli/src/cli.ts and retry.

If wrapper output says ok: true but the nested result contains an error

• Treat the operation as failed. Some CLI paths can return a successful envelope while result.result or result.raw contains backend errors such as Too many open files, Agent not found, or stale project metadata.
• Verify reservations/register/inbox calls by reading the nested result, not only the top-level ok flag.
• Retry once if the backend says it freed cached repos; if it still fails, continue only for low-risk edits and report the coordination failure in the final summary.
• For repeated Too many open files. Freed 0 cached repos, inspect lsof -p $(pgrep -f 'mcp_agent_mail.*serve-http') | rg '\.(archive|commit)\.lock'. The durable fix is in joelhooks/mcp_agent_mail: close orphaned lock FDs, avoid treating metadata-missing locks as immediately stale, and run com.joelclaw.agent-mail with NumberOfFiles=8192 via infra/agent-mail-daemon.sh + infra/launchd/com.joelclaw.agent-mail.plist.

Prompt Authoring Checklist (shore up prompts)

Any prompt/role/system contract that mentions coordination should:

1. Reference clawmail as canonical protocol skill.
2. State that mail access is via joelclaw mail (wrappers allowed, direct MCP not allowed).
3. Include at minimum: inbox check, announce, reserve, release.
4. Require path context in coordination messages.
5. Encourage subject prefixes (Starting:, Task:, Status:, Blocked:, Done:).
6. Avoid filler about mail when no shared edits/coordination are involved.

Steering Loop Integration

pi/extensions/session-lifecycle runs a daily monitor+steer review and emits:

• agent-mail/steering.reviewed

Snapshot path:

• ~/.joelclaw/workspace/agent-mail-steering/YYYY-MM-DD.json

Use steering hints to tighten protocol compliance when drift is detected.

Related

• skills/agent-mail/SKILL.md (compatibility alias)
• joelclaw mail --help
• ADR-0172: Agent Mail via MCP Agent Mail