letterbox-setup

letterbox-setup is a skill for Claude Code, Codex from dovahkiin-v/letterbox. It costs 78 tokens per session (1,802 once invoked), scanned B, original, MIT.

A setup guide for connecting terminal AI agents through Letterbox, a local file-based messaging channel. It covers registering the messaging service with each supported terminal tool and starting a peer connection.

In plain words
What is it for?
Use it when enabling Letterbox for Claude Code, Gemini CLI, or Antigravity, or when bringing another agent onto a shared channel.
Why use it?
It handles the one-time wiring needed before two agents can communicate, including harness registration and folder trust.

Skill for Claude CodeCodex

Written for no agent in particular: nothing here depends on one. Also seen: mentions Claude Code; mentions Gemini CLI.

Good fit Use it when enabling Letterbox for Claude Code, Gemini CLI, or Antigravity, or when bringing another agent onto a shared channel.

Compare 6 skills from other repositories ↓
Install with agentmods
npx agentmods add skills/dovahkiin-v/letterbox/letterbox-setup
Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent
npx skills add dovahkiin-v/letterbox --skill letterbox-setup
Clone the repo
git clone --depth 1 https://github.com/dovahkiin-v/letterbox

Made for: Claude Code, Codex.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

agentmods badge for letterbox-setup

README.md
[![agentmods](https://agentmods.dev/badge/skills/dovahkiin-v/letterbox/letterbox-setup/github.svg)](https://agentmods.dev/skills/dovahkiin-v/letterbox/letterbox-setup)
Your own site
<a href="https://agentmods.dev/skills/dovahkiin-v/letterbox/letterbox-setup"><img src="https://agentmods.dev/badge/skills/dovahkiin-v/letterbox/letterbox-setup/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

agentmods 80×15 button for letterbox-setup

Your own site · 80×15
<a href="https://agentmods.dev/skills/dovahkiin-v/letterbox/letterbox-setup"><img src="https://agentmods.dev/badge/skills/dovahkiin-v/letterbox/letterbox-setup.svg" alt="Reviewed on agentmods" width="80" height="20"></a>
Per session 78 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 1,802 The whole file, excluding the scripts and references it only reads on demand.
Security scan B 1 finding. A grade says what 26 rules found in the file — not that it is safe.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5.1 $0.00078 $0.01802
Opus 5 $0.00039 $0.00901
Sonnet 5 $0.00016 $0.00360
Haiku 4.5 $0.00008 $0.00180

Measured 9d ago against content hash 2b05e71b6ea4, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-10, from the pricing page.

Security

Grade B, and why

letterbox-setup scanned grade B with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 9d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Reads agent configuration directoriesmediumAgent snooping

.claude/, .codex/, .gemini/ hold keys, settings and other credentials a mod has no legitimate need for.

1. Ensure `~/.gemini/settings.json` contains a `letterbox` MCP server under
skills/letterbox-setup/SKILL.md · 161 lines

How it starts

The opening of the file, as written. The whole thing — 161 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Letterbox — setup & wiring guide

Letterbox lets two terminal coding agents hold a real-time conversation by passing JSON message files through a shared directory (~/.letterbox/channels/<channel>/). This skill covers the one-time wiring to make a harness letterbox-capable. For using a live bridge (sending, reading, directed messages), see the separate letterbox skill.

The shape of a bridge

A bridge is two launches — one per side, same channel:

letterbox <harness> --channel <name> --as <label>

letterbox <harness> spawns the harness, watches the channel, and injects 📬 notifications. The one prerequisite is that the target harness has the letterbox MCP server registered so its agent gets the tools. Registration is one-time per harness and differs by harness (below).

You cannot add MCP tools to your own already-running session. Registration takes effect on the next launch of that harness. To bring up a peer: ensure the wiring below exists for its harness, then spawn letterbox <harness> --channel <name> --as <peer-label>.

Two values you'll reuse:

  • the absolute path to the letterbox binary (readlink -f "$(command -v letterbox)"),
  • the launch directory must be trusted by Gemini/Antigravity (they otherwise pop a blocking "trust this folder?" prompt that stalls automation).

Identity: one label, one participant per channel

Each --as <label> must be unique on its channel. Launching a second session under a label already running on that channel is refused:

'claude' is already running on channel 'demo' (pid 12345).
Use a different name to run a second instance, e.g.:
  letterbox claude --channel demo --as claude-2

This is deliberate — it makes the label the atomic unit of identity, which is what lets directed addressing (send_message(to="…")) be unambiguous. For multiple agents of the same kind in one room, give them distinct labels: claude-review / claude-commit, gemini-1 / gemini-2. The same label on a different channel is fine (different conversation, no collision).

Read the full file on GitHub · 161 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 9d ago First seen · 161 lines · 78 tokens per session scan B 2b05e71b6ea4

Subscribe to this mod's changes

letterbox-setup is a skill published in the GitHub repository dovahkiin-v/letterbox (0 stars, last pushed 16d ago), licensed MIT. It adds 78 tokens to every session and 1,802 once invoked, about $0.0004 per session on Opus 5. A static security scan graded it B with 1 finding (reads agent configuration directories). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.