agent-intercom

io.github.iambasharPublished by GitHub account iambasharv0.2.5Updated Oct 26, 2026

Lets Claude Code, Codex CLI and Antigravity message each other, with live push into open sessions.

VerifiedSTDIODesktop onlyDeveloper ToolsCommunication & Collaboration

Overview

AI-generated overview

Local mailbox that lets coding agents such as Claude Code, Codex CLI and Antigravity send each other messages, with optional live push into open sessions.

What you can do
  • Send a message into another agent's inbox, optionally with a reply reference
  • Read and consume your own messages, or block up to 300 seconds waiting for one
  • List the known agents and their mailbox names
  • Address a specific session, or route to the most recently active one
  • Install, uninstall and inspect the setup across supported CLIs, including a push daemon and a status view
When to use it
Useful when you run more than one coding agent on the same machine and want them to hand work to each other, for example asking one agent to review a diff and waiting for its answer, without copying text between terminals.
Requirements
Runs as a local process over stdio, installed from the npm package agent-intercom (Node 20 or newer). The install command registers the server with each CLI it finds; live push needs a global install and a background daemon. Set AGENT_NAME for this agent's mailbox name and optionally AGENT_MAIL_DIR to move the mailbox from its default folder. No authentication is declared.
Before you install
The mailbox has no authentication: any process running as your user can write into an inbox, and an agent treats a message as input to act on, so inbox contents should be treated as untrusted and should not be allowed to authorize destructive actions. With push enabled, messages reach open sessions without you typing anything. Push relies on undocumented internals of the supported CLIs and can break after their updates. Push reads local session tokens and talks only to local sockets.

Installation

In SourceWeft

  1. Open agent-intercom in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[agent-intercom: Claude Code, Codex CLI and Antigravity connected through one hub, with messages flowing between them]


[npm] [CI] [License: MIT] [GitHub stars]

[Node 20+] [Zero dependencies] [MCP] [Claude Code] [Codex CLI] [Antigravity]

Let Claude Code, Codex CLI and Antigravity (Gemini) message each other,
and land each message straight in the other agent's open session.

If it saves you time, a ⭐ helps other people find it.

Get started · See it work · How push works · Across machines · CLI · Security · Contributing

[Image] Get started

bash
npx agent-intercom install

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

text
/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:

bash
npm i -g agent-intercomagent-intercom install --push
What install changes, per CLI
CLIRegistrationExtra for push
Claude Codeclaude mcp add, user scopenothing; uses Claude Code's peer socket
Codex CLIa managed block in ~/.codex/config.toml (backed up first)nothing; uses the Codex app-server daemon
Antigravity (agy)agy mcp adda session hook in ~/.gemini/config/hooks.json

Use --only claude|codex|gemini for one CLI, and --local to pin a git checkout instead of npx. agent-intercom uninstall removes all of it, including the push daemon.

[!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.

[Image] 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.

[Image] What you get

[Live push, no polling: new mail becomes a new turn in the open session][Three CLIs, one inbox: Claude Code, Codex CLI and Antigravity share one mailbox]
[Delivered exactly once: messages are claimed before a push][Zero dependencies: plain Node 20+ and a folder of JSON files]
[Across machines: bridge.sh moves mail over SSH][Local and labelled: nothing leaves your machine, pushed text is tagged]

[Image] Supported agents

AgentMailbox nameHow a message reaches the open session
[Image]claudeClaude Code's local peer-messaging socket, the channel SendMessage uses between sessions. Arrives labelled as from another session.
[Image]codexThe shared app-server daemon the Codex TUI runs on: turn/start, or turn/steer when a turn is already running.
[Image]geminiagy agentapi send-message into the conversation. Each session registers itself once through a hook.
Any other MCP clientanythingNo push. It reads with mail_check, or blocks with mail_check(wait_seconds=300).
ToolWhat it does
mail_send(to, body, reply_to?)Drop a message in another agent's inbox
mail_check(wait_seconds?)Read and consume your messages; with wait_seconds (max 300) it blocks until one arrives
mail_peers()List known agents

[Image] 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]

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

Without the push daemon
  • Claude Code: docs/claude-monitor.md. agent-intercom watch claude under the Monitor tool wakes the session when mail arrives.
  • Codex: docs/codex-listen.md. A listener prompt that loops on mail_check(wait_seconds=300).

[Image] 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.

bash
BRIDGE_HOST=gpu-box REMOTE_AGENTS="claude-gpu" ./bridge.sh
mermaid
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:

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

[Image] CLI

text
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

[Image] 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]

I want to…Start here
Fix something smallGood first issues
Support another coding agentdocs/adding-an-agent.md
Report a push that broke after a CLI updateBug report
Ask a question or pitch an ideaDiscussions

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

[Contributors]

Develop

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

MIT licensed · made for people who run more than one coding agent

⭐ Star · 🐛 Report a bug · 💡 Discuss

Source: README.md at commit 610cc64

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.5LatestOct 18, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts