agent-intercom

<div align="center">

<a href="https://github.com/iambashar/agent-intercom"><img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/hero.svg" alt="agent-intercom: Claude Code, Codex CLI and Antigravity connected through one hub, with messages flowing between them" width="100%"></a>

<br>

[![npm](https://img.shields.io/npm/v/agent-intercom?style=for-the-badge&logo=npm&color=cb3837&label=npx%20agent-intercom)](https://www.npmjs.com/package/agent-intercom)
[![CI](https://img.shields.io/github/actions/workflow/status/iambashar/agent-intercom/ci.yml?style=for-the-badge&logo=githubactions&logoColor=white&label=tests)](https://github.com/iambashar/agent-intercom/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-F5C451?style=for-the-badge)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/iambashar/agent-intercom?style=for-the-badge&logo=github&color=F0A93B&label=%E2%AD%90%20stars&cacheSeconds=3600)](https://github.com/iambashar/agent-intercom/stargazers)

[![Node 20+](https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)
[![Zero dependencies](https://img.shields.io/badge/dependencies-0-19C37D?style=flat-square)](package.json)
[![MCP](https://img.shields.io/badge/MCP-stdio%20server-7B8CFF?style=flat-square)](https://modelcontextprotocol.io)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-supported-E07A55?style=flat-square)](#supported-agents)
[![Codex CLI](https://img.shields.io/badge/Codex%20CLI-supported-19C37D?style=flat-square)](#supported-agents)
[![Antigravity](https://img.shields.io/badge/Antigravity%20(agy)-supported-7B8CFF?style=flat-square)](#supported-agents)

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

<sub>If it saves you time, a ⭐ helps other people find it.</sub>

[Get started](#get-started) · [See it work](#see-it-work) · [How push works](#how-push-works) · [Across machines](#across-machines) · [CLI](#cli) · [Security](#security) · [Contributing](#contributing)

</div>

---

<a id="get-started"></a>

## <img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/icon-terminal.svg" width="30" height="30" alt=""> 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
```

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

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-intercom
agent-intercom install --push
```

<details>
<summary><b>What <code>install</code> changes, per CLI</b></summary>

| CLI | Registration | Extra for push |
| --- | --- | --- |
| **Claude Code** | `claude mcp add`, user scope | nothing; uses Claude Code's peer socket |
| **Codex CLI** | a managed block in `~/.codex/config.toml` (backed up first) | nothing; uses the Codex app-server daemon |
| **Antigravity (`agy`)** | `agy mcp add` | a 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.

</details>

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

<a id="see-it-work"></a>

## <img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/icon-bolt.svg" width="30" height="30" alt=""> See it work

<p align="center"><img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/demo.svg" alt="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" width="100%"></p>

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.

<a id="what-you-get"></a>

## <img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/icon-check.svg" width="30" height="30" alt=""> What you get

<table>
<tr>
<td width="50%"><img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/card-push.svg" width="100%" alt="Live push, no polling: new mail becomes a new turn in the open session"></td>
<td width="50%"><img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/card-agents.svg" width="100%" alt="Three CLIs, one inbox: Claude Code, Codex CLI and Antigravity share one mailbox"></td>
</tr>
<tr>
<td width="50%"><img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/card-once.svg" width="100%" alt="Delivered exactly once: messages are claimed before a push"></td>
<td width="50%"><img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/card-zero.svg" width="100%" alt="Zero dependencies: plain Node 20+ and a folder of JSON files"></td>
</tr>
<tr>
<td width="50%"><a href="#-across-machines"><img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/card-bridge.svg" width="100%" alt="Across machines: bridge.sh moves mail over SSH"></a></td>
<td width="50%"><a href="#-security"><img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/card-safe.svg" width="100%" alt="Local and labelled: nothing leaves your machine, pushed text is tagged"></a></td>
</tr>
</table>

<a id="supported-agents"></a>

## <img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/icon-plug.svg" width="30" height="30" alt=""> Supported agents

| Agent | Mailbox name | How a message reaches the open session |
| --- | --- | --- |
| <img src="https://img.shields.io/badge/-Claude%20Code-E07A55?style=flat-square" alt=""> | `claude` | Claude Code's local peer-messaging socket, the channel `SendMessage` uses between sessions. Arrives labelled as from another session. |
| <img src="https://img.shields.io/badge/-Codex%20CLI-19C37D?style=flat-square" alt=""> | `codex` | The shared app-server daemon the Codex TUI runs on: `turn/start`, or `turn/steer` when a turn is already running. |
| <img src="https://img.shields.io/badge/-Antigravity%20(agy)-7B8CFF?style=flat-square" alt=""> | `gemini` | `agy agentapi send-message` into the conversation. Each session registers itself once through a hook. |
| Any other MCP client | anything | No push. It reads with `mail_check`, or blocks with `mail_check(wait_seconds=300)`. |

| Tool | What 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 |

<a id="how-push-works"></a>

## <img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/icon-gear.svg" width="30" height="30" alt=""> How push works

<p align="center"><img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/how-push-works.svg" alt="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" width="100%"></p>

```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](docs/live-push.md).

<details>
<summary><b>Without the push daemon</b></summary>

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

</details>

<a id="across-machines"></a>

## <img src="https://raw.githubusercontent.com/iambashar/agent-intercom/main/docs/assets/icon-network.svg" width="30" height="30" alt=""> Across machines

Agents on a