earshot

Coding agents in different terminals message each other by name.

earshot is an MCP server that lets Claude Code, Codex and any other MCP-capable CLI on your machine talk in both directions. Each agent keeps its own terminal, and you keep all of them: tell Claude to hand a job to Codex, then switch to Codex's terminal to watch it work, or correct it mid-task.

Why

Agents are good at different things. One generates images, another searches the web better, another already knows the codebase you are in. Reaching those strengths by running one CLI inside another (Claude calling codex exec, for example) tends to go wrong: the inner agent works without its context and fails, the outer one loses track, and you can no longer talk to the inner agent because another process owns it.

earshot keeps every agent a peer in its own terminal. They find each other by name and by what they say they are good at, send work back and forth, and queue messages while busy, the same way your own messages queue while an agent is working. You can step into any terminal at any time.

sequenceDiagram
    actor You
    participant C as Claude Code (terminal 1)
    participant E as earshot (~/.earshot)
    participant X as Codex (terminal 2)
    You->>C: when you finish the refactor, ask codex for a logo
    C->>E: send(to: "codex")
    Note over C: keeps working, no waiting
    E-->>X: codex queue: the message starts a turn
    You->>X: wait, they want the dark version
    X->>E: send(to: "claude", logo path)
    E-->>C: channel push: lands in the session
    C->>You: codex finished the logo

Related MCP server: AgentMesh

Install

Node.js 20 or newer.

npm install -g @hec-ovi/earshot-mcp

This adds the earshot-mcp command. Register it with each CLI you use. To skip the global install, register npx -y @hec-ovi/earshot-mcp in its place in the commands below.

Claude Code

claude mcp add --scope user earshot -- earshot-mcp --channel
claude --dangerously-load-development-channels server:earshot

At launch, pick "I am using this for local development". Messages from other agents then appear in the session on their own, between tool calls or as a new turn when Claude is idle. This uses Claude Code channels (research preview, Claude Code 2.1.80+, signed in with claude.ai or a Console key; Team and Enterprise organizations enable it in settings).

Launch Claude Code with that flag every time, for example with alias claude-e='claude --dangerously-load-development-channels server:earshot'. Claude Code does not tell MCP servers whether channels are on, so a session started without the flag drops the messages earshot pushes to it. To use plain claude, register earshot without --channel; messages then arrive with tool results (see Delivery).

Codex

codex mcp add earshot -- earshot-mcp

Nothing else to set. Codex sends its session id with every tool call, and earshot uses it to put messages into that session's queue with codex queue (Codex CLI 0.157+). An idle Codex starts working on the message; a busy one picks it up when its current turn ends.

Grok, Gemini, OpenCode and other CLIs

Register earshot-mcp as a stdio MCP server the way that CLI does it. Sending works right away. Messages arrive with the agent's next earshot tool result, or ask it to "listen for messages" and it keeps checking.

Docker

docker build -t earshot-mcp https://github.com/hec-ovi/earshot-mcp.git

Use docker run -i --rm -v /home/you/.earshot:/bus --user 1000:1000 earshot-mcp as the server command, with your own home path and id -u:id -g. Agents in containers and on the host share the bus through that folder and see each other.

Use it

In each terminal, ask the agent to join and say what it is good at:

join earshot as codex, you're good at image generation and shell work

Then talk the way you would to a teammate:

when you finish the refactor, ask codex to make a logo for the README

ask who is online and get the best one at web search to check the latest Node LTS

tell everyone on earshot the API moved to /v2

If an agent drifts, go to its terminal and correct it. Its next message carries the corrected work.

Delivery

A message that cannot be delivered right away waits in the agent's queue, in order, and is delivered once. A message stays on disk until it is delivered, so queues survive restarts, and a terminal that crashes or is killed mid-delivery loses nothing: the next join under that name gets the message.

An agent that is away (terminal closed or suspended, MCP server restarting) still gets its messages. send queues them and lists that agent under offline, and they arrive when it joins again under the same name. Only names that never joined are refused, and * reaches the agents online now.

Tools

Health

earshot-mcp --check

earshot 0.3.1
bus      /home/you/.earshot  writable
online   2
  claude           last beat 1.2 s ago  code, refactors
  codex            last beat 3.8 s ago  image generation, shell work
queued   none

It exits 1 when the shared folder cannot be used. Agents get the same report from the health tool.

Settings

How it works

There is no server to start. Each CLI launches its own earshot-mcp when it starts, like any stdio MCP server, and those processes meet in one shared folder. No CLI hosts the others: close a terminal and the rest keep talking, open another and it joins.

flowchart LR
    A[Claude Code] -->|starts| EA[earshot-mcp]
    B[Codex] -->|starts| EB[earshot-mcp]
    C[Any MCP CLI] -->|starts| EC[earshot-mcp]
    EA <--> F[(~/.earshot)]
    EB <--> F
    EC <--> F

In that folder, agents/<name>.json holds who is online (refreshed every 5 seconds, so it works across containers), and messages/<name>/ holds one file per message. Files are written whole and renamed into place, so a reader never sees half a message. A message being delivered moves to messages/<name>/.inflight/ and is deleted once it arrives.

Both MCP protocol versions are served: 2025-11-25 (initialize) and 2026-07-28 (stateless). The module contracts are in bus/CONTRACT.md and server/CONTRACT.md.

Development

git clone https://github.com/hec-ovi/earshot-mcp.git
cd earshot-mcp
npm install
npm test

The end-to-end tests drive real server processes over stdio, including channel push and the Codex doorbell.

License

MIT, by Hector Oviedo.