letterbox

# Letterbox
<!-- mcp-name: io.github.dovahkiin-v/letterbox -->
<!-- ^ MCP Registry ownership proof (ADR-071). The registry reads this from the
     PyPI long_description, so it must survive into the published package and must
     byte-match `name` in server.json. tests/test_registry_meta.py locks the pair. -->


![Status: Reference Implementation](https://img.shields.io/badge/status-reference%20implementation-blue) ![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue) ![License: MIT](https://img.shields.io/badge/license-MIT-green) ![POSIX only](https://img.shields.io/badge/platform-POSIX-lightgrey)

> 📌 **Built for internal production use.** Architecture proven across months of daily AI development. Open-sourced as a reference implementation.

**In plain terms:** If you use AI coding assistants in the terminal, you normally work with one at a time — and getting two of them to collaborate means copy-pasting messages between windows yourself. Letterbox lets two assistants (say, Claude and Gemini, or Gemini and Mistral's Vibe) talk *directly* to each other and work a task together, hands-free.

**The result:** one agent can plan while another reviews, or the two can split the work between them — collaborating on their own while you watch, instead of relaying every message by hand.

*A small file-based comms protocol that lets two AI agents in separate terminals talk to each other in real time.*

**Letterbox** lets two terminal coding agents — Claude Code, Gemini CLI, Antigravity, or Mistral's Vibe — hold a real-time conversation by passing message files through a shared directory. When one agent speaks, a `📬` notification is injected into the other's terminal and wakes it to read and reply. No network, no server, no shared memory: just JSON files in a folder and the OS's atomic-rename. It's the messaging layer that was built for an internal planning loop, extracted into a standalone, versioned tool in 2026. If you've ever wanted two CLI agents to collaborate on a task without you copy-pasting between windows, this is for you. It gets the occasional update at the author's whim (the launcher tells you when a newer one is out) — but it's unsupported: no roadmap, no feature requests, not a community project.

The bridge is genuinely cross-harness: **Claude on one side, Gemini on the other**, talking through the same channel, has been verified live. The one wrinkle is setup — Claude wires itself automatically, while Gemini and Antigravity load letterbox from their own settings. The [Setup](#setup-per-harness) section walks through both.

## Why it exists

I work with two AI collaborators every day — Claude and Gemini — each living in whatever terminal harness it runs in (Claude Code, Gemini CLI, Antigravity CLI, and now Mistral's Vibe). Letterbox is how I get them talking to *each other* instead of through me.

That happens in two modes. Sometimes it's **manual**: we're brainstorming and I want to loop the other model into the conversation. Sometimes it's **automated** — in the planning loop, Claude drafts a plan and each plan is routed to Gemini for review as a built-in stage. Letterbox carries both the same way.

It's harness-agnostic by design — **Claude Code ↔ Gemini CLI ↔ Antigravity CLI ↔ Vibe** in any combination — and same-model pairs work just as well: two Claude tabs, or two Gemini tabs, talking over one channel.

## What it is

Each `letterbox <harness>` launch runs **two coordinated processes** inside one terminal:

```
  letterbox claude --channel demo --as alice
        │
        ├─ PTY-Parent  (the foreground letterbox process)
        │    • spawns the harness CLI as a PTY child
        │    • watches the channel directory for peer writes
        │    • injects 📬 notifications into the PTY on arrival
        │
        └─ the harness spawns:
             └─ letterbox mcp  (stdio MCP server, agent-spawned)
                  • send_message / check_messages / acknowledge
                  • check_latest_message / channel_info / list_channels

  Both sides coordinate ONLY through the filesystem:

        ~/.letterbox/channels/demo/
          msg-*.json           ← one file per message
          .read/alice.json     ← per-agent read markers
          .read/bob.json
```

There is no daemon, no IPC, no background service. The filesystem *is* the coordination medium — the PTY-Parent's watcher sees a new `msg-*.json` appear and renders a notification; the channel directory is durable, inspectable, and `cat`-able. Crash recovery is trivial because nothing valuable lives in memory.

**How the agent gets the letterbox tools differs per harness**, and it's the one thing you configure once:

- **Claude Code** takes a launch flag, so letterbox wires it *automatically* — it generates a temporary MCP config and passes `--mcp-config` to `claude`. Nothing for you to set up.
- **Gemini CLI and Antigravity** don't take that flag; they load MCP servers from their own settings file. You add a one-line, channel-agnostic `letterbox` entry there once, and the launcher hands each session its channel and identity through environment variables at launch — so you never edit settings per channel.
- **Vibe** loads MCP servers from `~/.vibe/config.toml`. Its MCP subprocess inherits only a trimmed environment, so a one-time bridge script is needed to relay `LETTERBOX_CHANNEL` / `LETTERBOX_SENDER` from Vibe's own process env. Once that's in place, any channel works exactly like Gemini. See the [Vibe setup](#vibe-mistral) section.

## Who it's for

- People running terminal coding agents who want **autonomous AI↔AI dialogue** on one machine, without babysitting copy-paste between windows.
- People who value **files as the source of truth** — auditable, greppable, no opaque protocol, no magic.

## Who it's NOT for

- Anyone wanting a **hosted or networked** chat service — the message protocol is filesystem-local and never touches the network. (The launcher makes one optional, best-effort version check at startup; disable it with `LETTERBOX_NO_UPDATE_CHECK=1`.)
- Anyone wanting a **multi-user platform** — it's a point-to-point bridge between agents on one machine, not a many-user hub (see [Built for two](#built-for-two)).
- **Windows-native** users — v1 is POSIX-only (see [What we don't support](#what-we-dont-support)).
- Anyone wanting a **supported product** — letterbox is versioned and gets the occasional update at the author's whim (the launcher tells you when a newer one is out), but there's no roadmap, no SLA, and no commitment to take feature requests or keep maintaining it. Use it as-is; pull a newer version if it helps.

## Built for two

Letterbox is a **two-way bridge at heart** — one peer talking to one peer is what it's designed and tuned for. Three or more agents *can* share a channel: directed addressing (`send_message(to="<label>")`) and the `participants` list make it workable, and same-channel broadcasts reach everyone. But a shared channel is a **broadcast bus** — every message wakes every participant. Without orchestration (turn-taking, a designated coordinator, or rules about who speaks when), an N-way room becomes a notification storm that can chew through a model's message/usage limits surprisingly fast. If you want three or more, bring your own conductor. The substrate is honest about who's in the room; the etiquette is on you.

## Install

Letterbox is installed from source (a wheel is buildable; it is not currently published to PyPI). From the repo root:

```bash
pip install -e .          # or: pip install -e ".[dev]" for the test extras
```

This puts the `letterbox` command on your `PATH`. The command must resolve by name — each agent spawns `letterbox mcp` itself — so this is load-bearing. Confirm it:

```bash
which letterbox           # note this absolute path; Gemini/Antigravity setup needs it
```

You also need the harness you're launching (`claude`, `gemini`, `antigravity`, or `vibe`) installed, on your `PATH`, and logged in. Letterbox launches it for you.

### Updating

Letterbox is versioned (`letterbox.__version__`, the single source of truth); since there's no PyPI release, the git `main` HEAD *is* the release. On a human-facing launch the CLI makes one best-effort check (at most once a day, cached under `~/.cache/letterbox/`) and prints a one-line notice if a newer version exists. To update:

```bash
pip install --upgrade "git+https://github.com/dovahkiin-v/letterbox"
```

This is the **only** network call letterbox ever makes — the messaging protocol stays fully local. It runs with a tight timeout and is fully fail-silent: if it can't reach GitHub it simply prints nothing and never delays your launch. It is never run for `letterbox mcp` (the agent's stdio server). Disable it entirely with `LETTERBOX_NO_UPDATE_CHECK=1`.

## Setup per harness

You only do this once per harness. Skip the harnesses you won't use.

### Claude Code — nothing to do

Letterbox wires Claude automatically: at launch it writes a temporary MCP config (mode `0600`) and passes `--mcp-config <path>` to `claude`. The letterbox tools appear in that session and nowhere else. There is no settings file to edit.

### Gemini CLI — two one-time steps

**1. Register the MCP server** in `~/.gemini/settings.json` (create the file if it doesn't exist). Use the **absolute path** to your installed `letterbox` (from `which letterbox` above), and pass only `["mcp"]` — no channel, no identity:

```json
{
  "mcpServers": {
    "letterbox": {
      "command": "/absolute/path/to/letterbox",
      "args": ["mcp"]
    }
  }
}
```

This entry is **channel-agnostic on purpose.** The launcher exports `LETTERBOX_CHANNEL`, `LETTERBOX_SENDER`, and `LETTERBOX_INSTANCE_ID` into Gemini's environment at launch, and the MCP server reads them — so the same single entry serves every channel and you never edit it again. (This mirrors how the Forge orchestrators pass a channel via an env var.)

**2. Trust the folder you launch from.** Gemini refuses to ru