Skip to content
OpenSmartRoute
Skillv1.0.0

clawmail

Canonical joelclaw mail coordination protocol for all agents. Use when announcing work, checking inboxes, reserving files, releasing locks, handling task handoffs, triaging stale reservations, or audi

by joelhooks(0) 0 installs
Free
Sign in to install

Free account. Installing gives you the manifest plus copy-paste snippets.

See reviews

About

Imported from joelhooks/joelclaw (skills/clawmail/SKILL.md). Install upstream with npx skills add joelhooks/joelclaw --skill clawmail. Copyright stays with the author.

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:

Tool CLI equivalent
mail_send joelclaw mail send
mail_inbox joelclaw mail inbox
mail_read joelclaw mail read
mail_reserve joelclaw mail reserve
mail_release joelclaw mail release
mail_status joelclaw mail status

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

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml
targets:
  - https://api.opensmartroute.ai/api/v1/registry/joelhooks-joelclaw-clawmail/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

joelhooks-joelclaw-clawmail.ocm.jsonjson
{
  "ocm": "1",
  "id": "joelhooks-joelclaw-clawmail",
  "kind": "skill",
  "name": "clawmail",
  "description": "Canonical joelclaw mail coordination protocol for all agents. Use when announcing work, checking inboxes, reserving files, releasing locks, handling task handoffs, triaging stale reservations, or auditing coordination quality. Triggers on: 'clawmail', 'agent mail', 'joelclaw mail', 'reserve files', 'release locks', 'handoff', 'agent coordination', 'mail status', or any multi-agent collaboration workflow.",
  "publisher": "joelhooks",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "coordination",
      "multi-agent",
      "protocol",
      "cli",
      "reliability",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Canonical joelclaw mail coordination protocol for all agents. Use when announcing work, checking inboxes, reserving files, releasing locks, handling task handoffs, triaging stale reservations, or auditing coordination quality. Triggers on: 'clawmail', 'agent mail', 'joelclaw mail', 'reserve files', 'release locks', 'handoff', 'agent coordination', 'mail status', or any multi-agent collaboration workflow."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/joelhooks/joelclaw",
      "path": "skills/clawmail/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/joelhooks/joelclaw/blob/HEAD/skills/clawmail/SKILL.md",
      "key": "joelhooks/joelclaw/skills/clawmail/SKILL.md"
    }
  },
  "instructions": "# Clawmail\n\nCanonical agent coordination contract for joelclaw.\n\n`joelclaw mail` is the **only** supported mail access surface for pi agents.\nDo not call `mcp_agent_mail` HTTP endpoints directly from agent prompts or role instructions.\n\n## Topology\n\nAgent-mail is a **Central service**, not a mailbox per machine:\n\n- **Flagg** hosts the authoritative daemon on `127.0.0.1:8765`.\n- **Blaine and Panda** run `com.joelclaw.agent-mail-tunnel`, forwarding their local `127.0.0.1:8765` to Flagg over SSH.\n- Satellite/Relay clients keep using the default local URL. The tunnel preserves the CLI contract wit",
  "cost": {
    "context_tokens": 1584
  }
}

Fetch it by URL: GET /api/v1/registry/joelhooks-joelclaw-clawmail/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.