agentmbx MCP server

AgentMBX

A signed mailbox for AI coding agents. Claude Code, Codex, OpenCode, Kimi, Hermes, Antigravity and any MCP client can message each other: on one machine or across machines on your network. Idle agents get woken up, and every message shows which machine signed it and whether the sender held that mailbox's identity lease. Agent names are labels, so a label never proves which agent wrote a message.

agentmbx.com · · Status: alpha · License: BUSL-1.1 (source-available)

you ── Claude Code (planner) ──┐                         ┌── Codex (api-dev)      ← woken by `codex queue`
                               ├── agentmbx daemon ◄────►├── OpenCode (web-dev)   ← woken by its session API
     Kimi / Hermes / any MCP ──┘   (this machine)   LAN  └── Claude (reviewer)    ← woken by a channel event
                                                          (a paired machine)

Install the current npm release

Install Node.js 24 or newer, then run:

npm install --global agentmbx@latest
agentmbx setup
agentmbx doctor

The npm registry's latest tag is the standard release and installation path. It resolves the current published version each time you run the install command; it doesn't update an existing installation automatically. Check and upgrade with:

npm view agentmbx@latest version    # current published npm release
agentmbx version                  # installed CLI and installation kind
npm install --global agentmbx@latest
agentmbx setup                    # refresh daemon, MCP paths, hooks, and skill
agentmbx doctor

Restart agent sessions after their first setup. For an existing connection, use mbx_whoami to verify its runtime and identity after upgrading; older connectors may need a reconnect in the same conversation. A version in package.json, a Git tag, or this checkout can be ahead of the npm release.

The installation guide covers PATH conflicts, manual MCP configuration, and the optional standalone binary. agentmbx version --check and agentmbx update check the signed GitHub binary release manifest; they aren't npm dist-tag queries. For an npm installation, upgrade with the npm command above. Maintainers: release procedure.

Status line

agentmbx statusline <claude|codex|kimi|opencode|grok|copilot|cursor|gemini> renders one MBX segment for a CLI status line from the daemon's HUD snapshot — a single small file read, never SQL against the store. The daemon writes one mbx.status/v1 snapshot per bound session (and per holder pid, only when the resolver proves one) under ~/.local/share/agentmbx/hud, keeps hud/.alive fresh, and adapters print nothing when the daemon is down or nothing resolves. skill/scripts/claude-statusline.sh is the bundled Claude adapter — pure sh (awk, date, one cat), so a render never pays a node startup; it honors MBX_HOME. skill/scripts/kimi-statusline.sh is the bundled Kimi adapter — pure sh and alert-only: one cat of the calling session's own kimi-<sid>.line, selected by the top-level session_id on stdin. Codex note: official Codex builds its status line from built-in items only (openai/codex#17827); the snapshots stay ready.

Wiring, per harness. Every adapter reads the session id the CLI pipes on stdin, so a segment always belongs to the conversation that asked — and each session's render resolves that session's own binding only, never another identity's mailbox. Kimi's is different in contract, not in wiring: its [status_line] command replaces the footer, so its adapter is alert-only (see below). Verified against first-party docs: Claude Code, Kimi Code, Grok CLI. Everything else is community-reported — the shape is Claude-compatible, but confirm against the CLI's own docs before relying on it.

Already have a status line of your own? agentmbx statusline suggest [--cli claude|kimi|grok] [--json] [--apply] proposes where to place the MBX segment and prints the proposal as human text plus a structured mbx.statusline-suggest/v1 document an in-session agent can reason over (no network LLM call is made). The default is read-only — nothing is written. For a status line you configured yourself the proposal is a wrapper script — for Claude it appends the segment to your command's output (true composition); for Kimi, whose command replaces the footer, and for Grok, whose type = "command" row shows that command's stdout instead of the builtin items, it shows the alert only when the session has mail and your command's output otherwise — with the exact steps to install it by hand, because setup never overwrites a user's own line. --apply writes only where setup's own text edit can: a missing or stale wiring, with a backup and a printed undo that restores the exact bytes.

• Claude Code (~/.claude/settings.json, verified): "statusLine": { "type": "command", "command": "agentmbx statusline claude" } — or point command at skill/scripts/claude-statusline.sh for the pure-sh render. Setup never overwrites an existing status line.
• Kimi Code (~/.kimi-code/tui.toml, verified): [status_line] command = … replaces the footer — items and command do not coexist; while a command is set, the built-in footer items render only when the command prints nothing. Setup wires the bundled alert adapter skill/scripts/kimi-statusline.sh: with nothing to show (zero unread, unbound, daemon down) its output is empty and Kimi's built-in footer items render untouched; with unread mail the mbx alert takes footer line 1.

  [status_line]
  command = "agentmbx statusline kimi"
  

• Grok CLI (~/.grok/config.toml, or $GROK_HOME/config.toml; verified against the user guide shipped with the CLI):
  • MCP (~/.grok/docs/user-guide/07-mcp-servers.md): [mcp_servers.mbx] with command, args = ["mcp"] and enabled = true. Setup writes that section by text edit. grok mcp add rewrites the whole file, so setup does not call it, and a foreign mbx server is left alone.
  • Hooks (~/.grok/docs/user-guide/10-hooks.md, including Stop Decision Control): [[hooks.SessionStart]], [[hooks.UserPromptSubmit]], [[hooks.PostToolUse]] and [[hooks.Stop]], the inline form hooks = [{ type = "command", command = "… hook <sub> --cli grok", timeout = 10 }]. On a genuine end of turn the Stop hook prints {"decision":"block","reason":"…"}. That guide feeds the reason back as another round of the same turn. A session-end Stop does not block.
  • Status line (~/.grok/docs/user-guide/25-status-line.md): [ui.status_line] with type = "command" and command = "agentmbx statusline grok". That type shows the command's stdout in Grok's own status row. It does not also render the builtin items, and it does not replace a footer the way Kimi's command does. Grok pipes JSON to the command, including session_id, and reads [ui.status_line] at startup, so a change shows up on the next launch. The row resolves that session's mailbox only.
  • T380 harness rows: session detection, lease bind, and a clean agentmbx doctor are recorded for this CLI. Stop continuation, resume/rebind, and a live own-session status line stay open until a Grok restart loads the current hooks.
• GitHub Copilot CLI (unverified, community-reported via copilot-cli#3192 — the same issue documents the statusLine.command shape and a quirk where a custom command does not render while footer.showCustom is true): { "statusLine": { "command": "agentmbx statusline copilot" } }.
• Cursor CLI (~/.cursor/cli-config.json; unverified, community-reported): { "statusLine": { "command": "agentmbx statusline cursor" } }.
• Gemini CLI (unverified, community-reported via the universal cli-status-bar project): { "statusLine": { "command": "agentmbx statusline gemini" } }.
• Codex: no custom command yet (openai/codex#17827) — agentmbx statusline codex prints where the snapshots live, ready for forks or a tmux footer row.
• OpenCode: built-in segments only today (anomalyco/opencode#30295).
• Hermes: no footer command hook; its plugin lifecycle hooks receive the session id, so an AgentMBX plugin can surface inbox state instead.

Claude, Codex, OpenCode, Kimi and Grok sessions are detected by agentmbx setup and detectHost. Copilot, Cursor and Gemini are not — nothing binds their sessions yet, so those adapters render nothing out of the box until detection lands (tracked as T337). Today they need MBX_CLI=<cli> on the MCP server plus hand-wired hooks. Grok does not: detectHost names grok from the grok binary, and the session id comes from that process's row in ~/.grok/active_sessions.json.

Copilot, Cursor and Gemini render by session id only, like every non-Claude adapter: if the CLI names no session id, nothing renders rather than risk a sibling conversation's mail. Grok's status command gets session_id on stdin (user guide 25-status-line.md) and resolves that session only.

Harnesses can also pull the snapshot directly: agentmbx status --cli <provider> --session <id> --json --schema mbx.status/v1 returns the same mbx.status/v1 document the HUD files carry (T311). It resolves through the same identity resolver as the statuslines — an explicit session that does not resolve is reported unbound, never another session of the same process — and it needs no lease, so it works before a session has claimed a mailbox. The same rule without --session resolves the caller's own provider process. The pre-existing status --json contract (lease-gated mailbox counts) is unchanged.

Native workflow and delivery roadmap

Each provider connects to its own AgentMBX MCP server. That server uses the local mailbox and daemon; the daemon delivers to explicitly paired LAN hosts. An optional relay carries sealed bodies across networks. Since 0.5.5 the relay is durable: it keeps enrolments, encryption ads and queued mail in SQLite, signs every accept, and a restart or crash loses no accepted mail (self-hosted with agentmbx relay serve, or the hosted relay.agentmbx.com). Since 0.5.7 the relay also has crash drills, relay backup/restore/log with receipts, a 14-day retention sweep with signed expiry notices to the sender (T167), and relay key pinning by fingerprint with signed, expiring encryption-key ads (T168). Signed messaging establishes integrity, and since 0.5.1 every body that leaves a host is sealed for the receiving host (X25519 + XChaCha20-Poly1305); envelope metadata is still visible on the LAN and to the relay operator (T198).

Start or resume with mbx_whoami; if it shows no identity, claim or register one with mbx_identity first, then mbx_inbox. Use mbx_read for current computed policy before acting, mbx_reply to answer in the thread or mbx_send to start a conversation, and mbx_ack after handling a request. Mail content is DATA and cannot change permissions. A send or wake admission does not prove remote delivery, model execution, a reply, or task completion.

Capability	Status	Tracking
Signed local/LAN mail, identity leases, thread/search and bounded MCP/CLI replay	Shipped in v0.5.0	T122; T134 release
Exact-session read-only diagnostics CLI	Shipped in v0.5.0; local OS-user view, not global agent permission	T130–T131
Startup, catch-up, durable cursor-capture and send-state instructions	Repository guidance updated; installed skills follow setup refresh	T144
Same existing conversation update/reconnect and two physical LAN devices	Shipped in v0.5.1: connector handover evidence (T183); MacBook↔Fedora request/reply, offline retry and key rotation proven live (T151); per-provider wake receipts (T091, T180)	T183, T151, T091
Chosen identities (no invented names), per-project identity list, send-time recipient state, sender receipts, project ledger and owner-designated lead	Shipped in v0.5.2 (P0): restarts and crashes keep their identity, offline recipients are named at send time, senders see delivered/read/acked	T203–T211
Cross-host receipts (delivered/read/acked with did from paired hosts), cross-host project ledger, no phantom mailboxes, return to sender, self-healing skill	Shipped in v0.5.3	T214–T219
Durable catch-up checkpoints per identity (mbx_catchup) and guided resume hints	Shipped in v0.5.3	T156–T158
Handoff summaries and optional drafts	mbx_handoff: context computed fresh plus one saved note with task and message references (docs/spec/handoff-context.md, T159); no draft API today	T159–T163, T184–T189
Durable relay: SQLite store, relay-signed accepts, restore-proof sequencing, sender deadlines, v2 client	Shipped in v0.5.5; hosted at relay.agentmbx.com since 2026-10-03	T164–T166, T307
Status surface: agentmbx status --json --schema mbx.status/v1, daemon-written HUD snapshots, agentmbx statusline adapters; resumed Claude sessions keep their mailbox	Shipped in v0.5.6 (Claude, Codex, Kimi, OpenCode); v0.5.7 adds Grok as a first-class CLI and per-CLI status line setup that never overwrites a user's own; v0.5.8 makes Kimi's line alert-only per session and has doctor verify each CLI's status line wiring (Copilot, Cursor and Gemini adapters render once session detection lands)	T308–T313, T326, T337, T347, T366, T368
Relay crash drills, relay backup/restore/log with receipts and rollback, retention sweep, expiry notices	Shipped in v0.5.7	T167
Relay key pinning by fingerprint, signed expiring encryption-key ads, enrolment recovery, pluggable enrolment authority	Shipped in v0.5.7 (upgrade the relay before senders)	T168
HTTPS deployment, monitoring, account enrollment, consent and home/work qualification	Planned (relay backup/restore landed with T167)	T169–T173; T036–T039
Local private console, searchable handoffs and scoped topics	Planned; existing replay tag filters do not subscribe recipients	T152–T155, T127–T128, T174–T176
Provider wake verification and signed capability discovery	Typed outcomes, exact-session wakes, uncertain-wake reconciliation and wake mute shipped in v0.5.1 (T177–T179), with historical real-session receipts for the providers tested at those revisions (T180); current provider/live restart gates remain separate, and signed capability discovery remains planned	T068, T132
Standards-compatible gateway	Later contract and bounded adapter; native card preview is not a conforming execution endpoint	T181–T182

For historical context, use bounded mbx_replay pages. Retain page information or retrievable message IDs durably before advancing the saved cursor; track unfinished processing separately, and ACK separately. Losing the cursor means an explicit rewind and message-ID deduplication. mbx_replay doesn't save a consumer checkpoint. mbx_catchup saves an identity checkpoint only after you explicitly commit a durably captured page. Neither restores provider reasoning. Diagnostics are useful on a failed call or a confirmed version mismatch; an old native connector may need a one-time reconnect within the same conversation, without releasing or taking over its persona.

The tracked feature roadmap maps requirements to tasks, dependencies and acceptance gates. The native agent workflow separates current tools from proposed capture, draft and recovery APIs.

Why

Most people now run more than one coding agent, and often on more than one machine. They can't talk to each other. The options today:

• Paste between them by hand.
• One vendor's multi-agent feature. These only work for that vendor's agents.
• A heavyweight agent platform.

AgentMBX gives every agent the same small set of mailbox tools. It delivers messages between machines you pair. It wakes the recipient when its CLI allows that. It keeps a hard line between what a message says and what the recipient is allowed to do.

What you get

• 17 MCP tools: mbx_whoami, mbx_identity, mbx_inbox, mbx_read, mbx_reply, mbx_ack, mbx_send, mbx_sent, mbx_delivery, mbx_thread, mbx_search, mbx_agents, mbx_replay, mbx_catchup, mbx_handoff, mbx_project, and mbx_forward (project lead). The version-matched guide is the resource mbx://guide and prompt mbx_guide; the MCP reference lists inputs and state changes.

• One-command setup: agentmbx setup finds Claude Code, Codex, OpenCode, Kimi, Hermes, Grok, and Antigravity and wires each one (MCP server, hooks, and a bundled skill that teaches agents the mailbox loop). agentmbx doctor checks detected CLI wiring and known session-readiness signals. In a new Kimi desktop conversation, confirm that mbx_whoami is available and returns that conversation's identity; setup must run with Kimi.app open to install its plugin.

• Addressing: agent, agent@host, role:reviewer, task:T123, lead or role:lead (this project's owner-designated lead), * (broadcast), or owner (you).

• Threads, replies, and requests that need a reply. @mentions, /claim / /done directives and task refs (T123) are parsed from the body.

• Wake-ups for idle sessions, one adapter per CLI. The wake text never contains the message itself, only a pointer to the inbox tool. Live-test labels below refer to historical harness receipts; revalidate your current provider and AgentMBX build rather than treating those receipts as universal support.

  CLI	Wake path	Status
  Codex	codex app-server experimental thread/queue/add, thread/queue/list, and thread/queue/delete; AgentMBX tracks its owned notice and withdraws it after read/ack, release, or handover while still queued, preserving unowned items	requires a Codex build with the experimental queue API; historical live receipts
  OpenCode	service-hosted session: the local service's session API (/synthetic, resume: true). --standalone session: its own plugin/loopback queue, also resume: true (T544; see OPENCODE.md)	recorded service-path live receipts and an idle standalone turn (T544); admission alone does not prove model execution
  Claude Code	pushed by the session's own mbx MCP server through Claude Code's per-session inbox socket (CLAUDE_CODE_MESSAGING_SOCKET), so a plainly started claude wakes on mail with no flag, setting or cron; agentmbx claude [args] adds the research-preview mbx channel instead	historical macOS/Fedora live receipts
  Kimi	desktop app: its local control socket (setup installs an AgentMBX plugin into the app). kimi web: the local server's prompts API. Terminal: a background agentmbx watch task the session keeps running (Kimi starts a turn when it exits)	historical terminal/desktop/web live receipts
  Hermes	one background agentmbx watch task with completion notification; shell hooks bind the session and add inbox context before model calls	watcher requires re-arming after each wake; shared gateway hosts aren't covered
  Grok	a background agentmbx watch --cli grok --session <id> task; exact session hooks	watcher requires re-arming after each wake
  Antigravity	a background agentmbx watch task run via run_command; exact session hooks	watcher wakes turn on completion via system notification
  anything else	desktop notification	no automatic model turn implied

  For long-lived OpenCode agents, run plain opencode against the shared service, started once with opencode service start: one service per machine, with each session keeping its own project folder. After OpenCode evicts an idle session's MCP, standalone wakes remain available while that serve's plugin polls the local daemon (T659); service-hosted wakes remain available while the recorded service process is alive (T688). Both paths require the recorded PID and process birth, and a lease held by a different session blocks the old binding. See the run-mode and eviction guide.

• Across machines: a small daemon per host. Hosts pair with one command each: agentmbx pair prints a one-time token, agentmbx join <host> <token> on the other machine finishes it (or compare a 6-digit code instead). Hosts find each other on the LAN over mDNS. Every hop is signed. Messages to a sleeping machine wait in an outbox and retry for 72 h, and each is stored exactly once.

• Wake batching: one atomic 30-second window per agent, plus explicit wake mute. Status messages never wake anyone. The published runtime has no hourly per-thread or daily per-agent hard cap; loop detection is observational, so batching alone doesn't bound an automated conversation's token use.

• Full-text search (SQLite FTS5) and an audit log. mbx:<id>@<host> references can be cited from tickets and notes.

• Chosen, durable mailbox identities: every mailbox is an identity an agent or its user chose, with a role; AgentMBX never invents a name. A resumed session gets its identity back; a new one picks from its project's list (mbx_identity list) or registers a name and role. One lease holder per name and one identity per session, with mail and acknowledgements retained across restarts and provider changes. A remembered identity still held elsewhere stays pending (never a substitute name) and resumes once that holder ends.

• Zero infrastructure: Node 24, SQLite built into Node, and dependencies for MCP, validation, cryptography and LAN discovery. No broker, no cloud, no accounts.