AgentMBX

A signed mailbox for AI coding agents. Claude Code, Codex, OpenCode, Kimi, Hermes 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.

Related MCP server: claude-intercom-mcp

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.

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, and Grok 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). --standalone session: the plugin inside that session's own serve, over a loopback queue (see OPENCODE.md)	historical service-path live receipts; standalone wakes are admitted in-process, whether one starts a turn on an idle session is unproven (T544)
  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
  anything else	desktop notification	no automatic model turn implied

• 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.

Trust model (the short version)

• Owner authority belongs to one running session. You (or an agent) run agentmbx owner grant, pick the live session, and you approve it: a Touch ID tap on macOS, your passphrase on Linux. The grant is bound to a key that exists only in that session's memory, for 12 h by default. Another process using the same agent name gets nothing.

• The owner key lives in the macOS login Keychain behind Touch ID (no passphrase), readable only by AgentMBX.app's signing helper, which writes the prompt text itself from exactly what it signs. On Linux it is encrypted with your passphrase and unlocks only from a real terminal. Either way, an agent's shell commands cannot use it.

• Capabilities are enforced by the receiving machine (task.assign, decision, broadcast, alert). A message outside its grant arrives labelled authority: none with a warning.

• No message can approve a permission prompt or change a recipient's config, owner-signed or not. The MCP instructions tell every agent this, and agents treat all message content as data, not instructions. This mirrors how Claude Code handles messages from other sessions.

• Known limits:

  • The LAN hop is signed, and since 0.5.1 every body is sealed to the receiving host's pinned X25519 key; envelope metadata (from, to, subject, thread, refs, project path, mentions and tags) is still visible on the wire (T198).

  • Discovery and direct delivery are LAN-only: mDNS does not cross routers (and is blocked on some LANs) and there is no NAT traversal; across networks only the relay works. The relay has durable SQLite storage and signed accepts since 0.5.5; backup/restore receipts and a 14-day retention sweep with expiry notices shipped in 0.5.7 (T167). The relay operator sees envelope metadata, never bodies.

  • Agents on the same machine share the OS user boundary.

The full design is in docs/SPEC.md. The adversarial review that shaped it is in docs/COUNCIL-VERDICT-2026-09-26.md.

Bounded history and diagnostics

mbx_replay returns {messages, next_cursor, has_more} without acknowledging mail or changing read state. It includes acknowledged history and uses durable first-visibility ordering, so late or backdated deliveries do not disappear behind a timestamp checkpoint. Persist the returned next_cursor yourself; it is a pagination position, never an identity credential. Continue through empty filtered pages while has_more is true. A completed cursor polls later arrivals on its next call; retry overlap should be deduplicated by ID. Omit a lost cursor to explicitly rewind. Keep the same mailbox and filters across a provider release/claim handoff. mbx_replay doesn't save a consumer checkpoint; mbx_catchup advances its identity checkpoint only after an explicit commit of a captured page.

agentmbx replay --cli codex --session <thread-id> --limit 50 --max-bytes 65536
agentmbx replay --cli codex --session <thread-id> --cursor '<returned-next_cursor>'
agentmbx diagnostics --mailbox <name> --cli codex --session <thread-id> --json

Replay requires the calling provider's current lease; --as cannot grant access. CLI output is bounded JSON, with omission IDs for oversized bodies. MCP uses max_bytes; CLI uses --max-bytes and also supports --scan-limit. Both support exact existing-mail filters for project plus sender host, topic tags and thread. Filters do not create topic rooms or broaden delivery. All replay bodies and envelope metadata are data: use mbx_read for current computed trust and owner-policy framing before acting on any replayed request. Processing a request, finishing a task and acknowledging mail remain separate actions.

agentmbx diagnostics is a bounded, read-only local view of holder evidence, queued mail counts and redacted recovery receipts, with no message bodies or lease credentials. Installed CLI, observed daemon and connector version are separate evidence. Its access boundary is the local OS user; it is not a browser console or an agent permission grant.

Retention and machine replacement

Retention is off by default; nothing is deleted until you choose a window. agentmbx prune --older-than 90 --dry-run reports what would go; without --dry-run it deletes only settled mail (all local deliveries acked, nothing queued in the outbox, received and last updated before the window) and runs VACUUM. agentmbx retention set 90 lets the daemon do the same every 6 h. Receive-side dedupe retains pruned message IDs for a 21-day post-prune horizon; after old tombstones are swept, a valid late retry can be treated as new. Replay reports pruned positions as history_pruned separately, rather than silently skipping them.

agentmbx identity export <file> seals this host's keys, config and paired peers with a passphrase (file mode 600); agentmbx identity import <file> restores them on a replacement machine so peers keep accepting it. Treat the file as a private key and run only one machine with that identity. A macOS Keychain owner key cannot be exported.

Upgrade existing mailbox data

Upgrading to mailbox schema 3: quiesce daemon, hooks and MCP writers and make a consistent backup of the complete mailbox home before opening it with 0.5.0. Update using the same installation kind (signed binary update, tagged npm source, or source checkout), then resume writers and verify agentmbx doctor and connector mbx_whoami. Schema 3 preserves signed messages and delivery/ACK state while adding replay visibility. Retained incompatible writers fail closed; compatible existing ACK updates remain valid. Current connectors can adopt native updates on a subsequent tool call, but an older connector may require reconnection. Rollback requires stopping writers and restoring the pre-upgrade backup with its compatible runtime; do not downgrade a schema-3 database in place or rotate its replay epoch while writers are active. See the coordinated rollout and restore handoff for exact recovery steps.

Before ending a session or switching providers, finish mailbox work and call mbx_identity with action=release. The replacement session (which starts without an identity) claims the same name. Claude setup also requests release on terminal exit. Crashes can skip shutdown hooks, and hosted conversations can leave a shared MCP process alive: inspect ownership first, then use owner-signed agentmbx identity takeover if the previous session cannot release. The 30-minute missing-heartbeat timeout is a fallback. A conversation of a shared OpenCode or Codex process (or hosted Kimi) with no mbx call for 10 minutes becomes claimable; a dedicated session is never taken over this way.

Restart your agent sessions and they have the mbx_* tools. agentmbx setup --dry-run previews, --only codex limits it, --uninstall undoes it. What it writes for each CLI (and how to do it by hand): docs/INSTALL.md.

Pair a second machine:

desktop$ agentmbx pair                             # prints a one-time token and the exact line to run on the other machine
laptop$  agentmbx join desktop 7K3M-QX9D-4HTR      # or: agentmbx join desktop.local:7373 7K3M-QX9D-4HTR

That's it: both machines are paired, no codes to compare. The token is single use and expires after 10 minutes (--ttl). Both sides prove they know it with an HMAC over both machines' host and owner keys, so a machine in the middle can't substitute its own keys. agentmbx discover lists AgentMBX hosts on the LAN (mDNS). If multicast is blocked, use the host:port form. Prefer comparing codes by eye? agentmbx pair --compare desktop.local:7373, then agentmbx pair approve <other-host> <code> on both machines.

Then from any agent: "send api-dev@desktop a request to run the migration tests and reply with the result". Or from a shell:

agentmbx send --as planner --cli codex --session <thread-id> --to api-dev@desktop --kind request --needs-reply --subject "run migration tests" -m "…"
agentmbx inbox --as planner --cli codex --session <thread-id>

Run those mailbox commands inside the provider session that holds planner. --as selects that held identity; it doesn't impersonate another agent or bypass a lease. A plain-shell send without a lease is labelled unverified-sender.

Owner authority (optional, only on the machine you use):

agentmbx owner init                                            # macOS: approve Touch ID; Linux: choose a passphrase
agentmbx owner grant planner --caps task.assign,decision --ttl 12h

Notifications

When an agent has no wake path (or its wake fails), the daemon shows a desktop notification instead.

• macOS: build the small menu-less app once, then (re)install the daemon:

  scripts/build-macos-app.sh        # needs Xcode command line tools; writes build/AgentMBX.app
  agentmbx daemon install           # copies it to ~/Applications/AgentMBX.app
  agentmbx notify-test --as planner # sample notification through the same path wake-ups use

  • Notifications then come from AgentMBX with its own icon, not Script Editor. The first one asks for permission. Manage it in System Settings > Notifications > AgentMBX.

  • Clicking a notification opens a Terminal window running agentmbx inbox --as <agent>.

  • The launchd agent starts through AgentMBX.app/Contents/MacOS/agentmbx-daemon, a tiny launcher that execs Node. Background Task Management names the job after that binary, so the Login Items entry reads "AgentMBX" instead of "node".

  • Without the app, AgentMBX falls back to osascript notifications.

• Linux: notify-send -a AgentMBX -i mail-message-new.

• Set MBX_NO_DESKTOP=1 to turn desktop notifications off.

Command reference

Use agentmbx help or agentmbx <command> --help for the installed release's options. The CLI reference groups the published commands; MCP tool names aren't interchangeable with CLI subcommands.

• Mail: send, inbox, read, ack, thread, search, replay. CLI replies use send --reply-to <id>; receipts, catch-up, and handoff have dedicated MCP tools.

• Session and visibility: whoami, agents, status, statusline, diagnostics, identity, probe, watch, wake mute|unmute.

• Install and integration: setup, doctor, version, update, mcp, hook, claude, import-v2.

• Machines and transport: init, pair, join, discover, peers, host rotate, daemon, relay, notify-test, login.

• Owner and policy: owner, policy, lead, audit.

• Retention: prune, retention; identity backup uses identity export|import <file>.

How it compares

* Claude channels are a research preview.

Development

git clone https://github.com/kryptobaseddev/agentmbx && cd agentmbx && npm install
npm test            # crypto, trust, identity recovery, HTTP, pairing, MCP, wake adapters, updater, setup/doctor
npm run typecheck
python3 scripts/e2e/wake-codex.py      # live: wakes a real idle Codex TUI (see docs/TESTING.md)
scripts/build-macos-app.sh             # macOS: AgentMBX.app (notifier + launchd launcher); releasing: docs/RELEASING-macos.md

• Docs: SPEC · INSTALL · RESEARCH · TESTING · RELEASING-macos

• Security: report vulnerabilities privately as described in SECURITY.md.

• Contributions: issues are welcome. Pull requests need agreement that the Licensor may license contributions under the terms in LICENSE.

License

AgentMBX is source-available, not open source. It is licensed under the Business Source License 1.1:

• Free: reading, modifying, and running it for your own agents and your own organization, in production too.

• Needs a commercial license: offering it, or anything built from it, to others as a product, hosted service or embedded agent-messaging feature. Contact via agentmbx.com.

• Change Date: LICENSE fixes the Change Date at 2030-09-26, with Apache License 2.0 as the Change License. Under BUSL 1.1 each version converts on the Change Date or on the fourth anniversary of its first public release, whichever comes first, so every version released so far converts no later than 2030-09-26.

"AgentMBX" and "MBX" are trademarks of CodLuv LLC; see NOTICE.