agent-intercom

[圖片] Get started

npx agent-intercom install

Using Claude Code only? Install it as a plugin instead:

/plugin install agent-intercom --marketplace iambashar/agent-intercom

_{On Claude Code older than 2.1.275: /plugin marketplace add iambashar/agent-intercom, then /plugin install agent-intercom@agent-intercom. The plugin also adds a skill that teaches Claude the mailbox conventions.}

The npx command registers the MCP server with every CLI it finds. Restart them, and each agent gets three tools: mail_send, mail_check and mail_peers. Then ask in plain words:

You → Claude: Ask codex to review the diff in src/parser.ts and wait for its answer.

Turn on live push so nobody has to poll. Install it globally, because the daemon needs a stable path:

npm i -g agent-intercomagent-intercom install --push

[!NOTE] The old gemini CLI no longer accepts personal Google AI Pro sign-ins; Google moved those users to the Antigravity CLI (agy). Its agent is named gemini here by default.

[圖片] See it work

[Animated two-pane terminal: Claude sends a review request to Codex with mail_send, Codex receives it as a new turn, reviews the file and replies, and the reply appears in Claude's session]

Neither agent polls. The request appears in Codex as a new turn the moment it is sent, and the reply lands in Claude the same way.

[圖片] What you get

[圖片] Supported agents

[圖片] How push works

[Flow: mail_send writes to the inbox; pushd claims the file, injects it into Claude Code, Codex CLI or Antigravity, then moves it to read; with no open session the message stays in the inbox for mail_check]

sequenceDiagram    autonumber    participant C as Claude Code    participant M as ~/.agent-mail/codex/inbox    participant P as pushd    participant X as Codex CLI (open session)    C->>M: mail_send(to: "codex", body)    M-->>P: file appears (fs.watch, no polling)    P->>M: claim: rename to <id>.json.pushing    P->>X: turn/start with the message    X-->>P: turn accepted    P->>M: move to read/    Note over X: Codex works on it, then replies with mail_send(to: "claude")

• Delivered once. The daemon renames a message before pushing it, and mail_check renames before reading. Whoever wins the rename delivers it.

• Fails safe. A failed push puts the file back in the inbox and retries after 30 s. If no session is open, the message waits for mail_check.

• Addressing. Pick a session with claude.<session-name>, codex.<thread-id-prefix> or gemini.<conversation-prefix>. Otherwise the most recently active session gets it, or the one named in ~/.agent-mail/routes.json:

  json

  { "claude": "api-server", "codex": "019f018a" }

[!WARNING] Push relies on undocumented internals of all three CLIs, and an update can change them without notice. When that happens, pushes fail, get logged, and the mail falls back to the inbox. Protocol details: docs/live-push.md.

[圖片] Across machines

Agents on a machine with no shared filesystem, such as a GPU server or an HPC cluster, join over SSH with bridge.sh. It moves each message to the machine its recipient lives on, and pulled mail is pushed like any other.

BRIDGE_HOST=gpu-box REMOTE_AGENTS="claude-gpu" ./bridge.sh

flowchart LR    subgraph laptop["💻 Laptop"]        A[claude] & B[codex] & G[gemini]    end    subgraph gpu["🖥️ gpu-box"]        R[claude-gpu]    end    laptop <-- "bridge.sh · rsync over SSH" --> gpu

More: docs/remote-bridge.md.

More than one session per CLI

Names are just AGENT_NAME. Give each session its own, for example claude-api and claude-web:

npx agent-intercom install --only claude --claude-name claude-api

[圖片] CLI

agent-intercom install [--only claude|codex|gemini] [--claude-name N] [--codex-name N] [--gemini-name N] [--local] [--push]agent-intercom uninstall        MCP entries, agy hook and push daemonagent-intercom push install     push daemon as a login service (launchd / systemd --user)agent-intercom push uninstallagent-intercom push run         push daemon in the foregroundagent-intercom status           unread/read counts per agentagent-intercom watch <name>     one line per new message, without consuming itagent-intercom serve            the MCP server on stdio

[圖片] Security

This is a local mailbox with no authentication. Any process running as you can write to ~/.agent-mail/*/inbox, and an agent treats a message as input to act on. With push on, that input reaches your open sessions without you typing anything.

• Treat inbox contents as untrusted text. Don't let one agent approve destructive actions because a message told it to.
• Pushed messages are labelled [agent-intercom] message <id> from <sender>. Claude Code also marks them as from another session, not from you.
• Push reads tokens only your user can read (~/.claude/sessions/*.key, the agy session token) and talks only to local sockets. Nothing leaves the machine.

See SECURITY.md to report a problem. Set AGENT_MAIL_DIR to move the mailbox, for example into a project folder.

[Saved you a copy-paste between agents? Star agent-intercom on GitHub]

🤝 Contributing

Contributions are welcome, from a typo fix to support for a new agent.

[Good first issues] [Help wanted] [Discussions]

Read CONTRIBUTING.md before opening a pull request. Everyone here follows the code of conduct.

[Contributors]

Develop

git clone https://github.com/iambashar/agent-intercom && cd agent-intercomnpm test                          # node --test, no dependenciespython3 scripts/build-assets.py   # rebuild the README artwork

Zero runtime dependencies; Node 20+. See CONTRIBUTING.md and the changelog.