Walkie-Talkie

Overview

An append-only file mailbox, committed to the repo, that lets agent sessions communicate across platforms, machines, and time. Any agent that can read and write files can participate — no shared harness, API, or memory required. Git is the transport; the human audits both channels.

Core invariant: one writer per file, append-only. Each agent owns exactly one outbox file. Nobody ever edits another agent's outbox, and nobody ever rewrites a past entry. This designs merge conflicts and clobbering out of existence.

Why a fixed protocol matters: unaided agents invent good but incompatible mailbox formats. The value of this skill is convergence — every session that loads it speaks the same format, so channels compose across sessions that have never met.

When to Use

• Heterogeneous agents (Claude + Codex + Gemini…) sharing one repo
• Handoff of in-flight work to a session that starts later
• Parallel sessions on the same repo needing to coordinate shared surfaces
• Cross-machine coordination (git push/pull moves the mailbox)

When NOT to use: Claude Code sessions in the same harness on the same machine — use Agent Teams / SendMessage instead (push notifications beat polling). One-shot handoff with no return channel and nothing contested — a plain HANDOFF.md is enough, though the Grill (below) still applies on receipt.

Setup (first agent creates the channel)

1. Create comms/ next to the work it coordinates (repo-wide: .agents/comms/; sprint-scoped: docs/<area>/comms/).
2. Copy PROTOCOL_TEMPLATE.md into it as README.md, filling in the agent handles.
3. Create one outbox per agent, named <HANDLE>.md (e.g. FABLE.md, CODEX.md). Initialize peers' outboxes with a one-line pointer to the README so their first read routes them in.
4. Add a discovery shim to every bootstrap file the participating platforms auto-read — CLAUDE.md, AGENTS.md, GEMINI.md: "In-repo agent mailbox at `<path>/comms/` — read its README.md and your inbox before changing anything. MANDATORY."
5. Write your first entry: repo state, in-flight work with exact file:line for load-bearing state, known unknowns, and any ACTION-REQUESTED.
6. Commit the mailbox together with (or immediately after) the code it describes.

Message Format

Append to YOUR OWN outbox only:

markdown
## [2026-07-03 14:05] STATUS: eval-surface rotation half-applied
Re: —

The 7-match gate is now the ONLY confirmation surface (src/ranker.py:4).
build_cache() sort order is stale vs the bounce rule — main outstanding fix.

Header: ## [YYYY-MM-DD HH:MM] TYPE: subject. Re: names the entry being answered (by timestamp+subject), or —.

| Type | Meaning | |---|---| | STATUS | What I did / left half-done / decided. The workhorse. | | ACTION-REQUESTED | Peer must act or explicitly decline. Highest priority. | | QUESTION / ANSWER | Async request/response. ANSWER always sets Re:. | | GRILL | Handoff interrogation — evidence required (see below). | | EVIDENCE | Reply to a GRILL. Command output, SHAs, file:line — not assurances. | | CLAIM / RELEASE | Advisory lock on a named surface (exact paths). | | ACK | Received and understood; nothing further. |

Checkpoint Discipline

Read every peer outbox at: session start, before starting a new slice of work, after completing one. Answer open ACTION-REQUESTED and GRILL items addressed to you before starting new work. Write whenever you have verdicts, needs, or plans affecting shared surfaces, caches, or artifacts — not just at session end.

The Grill

On receiving a handoff, do not ACK politely — interrogate. Post a GRILL entry with pointed questions; the handing-off agent (this session or its next incarnation) must answer each with EVIDENCE, not assurances. Minimum grill set:

1. What did you verify by running something vs. merely believe? Show the command and output.
2. What is half-applied right now? Exact file:line of every load-bearing edit.
3. What breaks if I touch X? Which surfaces are claimed?
4. What do you know that is written down nowhere but this mailbox?
5. What would you check first if this were broken tomorrow?

Any grill question that cannot be answered with evidence is recorded as a RISK in the answering entry — never silently dropped. Unanswered grills block RELEASE of the affected surface.

Rules

• Append-only. Never edit or delete a past entry (corrections are new entries with Re:).
• Never write to another agent's outbox.
• Concise and factual — exact paths, function names, constants. Write for an agent with zero shared context.
• The human audits both channels; write nothing you wouldn't want audited.
• Git history is the tiebreaker for what happened; the mailbox for what was intended.

Common Mistakes

| Mistake | Fix | |---|---| | Single shared LOG.md both agents write | One outbox per agent — sole-writer files can't conflict | | Editing an old entry to "update" it | New entry with Re: — audit trail must be immutable | | Polite ACK of a handoff | GRILL it — untested handoff claims are where bugs hide | | Mailbox only written at session end | Checkpoint cadence: start, before each slice, after each slice | | Protocol described only in chat | README.md in the comms dir + shims in CLAUDE.md/AGENTS.md/GEMINI.md | | Committing code without its mailbox entry | Commit them together — a pull must never show unexplained code |

Prerequisites

• A shared git repo both sessions can pull/push
• Write access to create comms/ (or an agreed path) and one outbox file per agent handle
• Participating platforms that auto-read at least one bootstrap file (CLAUDE.md, AGENTS.md, GEMINI.md, …)

Instructions

Follow the Setup / Message Format / Grill sections above. Non-negotiables:

1. One writer per outbox file; append-only.
2. Never edit another agent's outbox.
3. Commit mailbox updates with the code they describe.
4. On handoff receipt, run the Grill before trusting claims.

Output

• A comms/ (or agreed) mailbox directory with README.md (protocol) and <HANDLE>.md outboxes
• Appended status / handoff / ACTION-REQUESTED entries with timestamps
• Optional Grill notes on the receiving agent's outbox after interrogation

Examples

Two Claude sessions hand off mid-feature

Session A: /walkie-talkie set up comms at .agents/comms/
Session A: writes STATUS + handoff with file:line load-bearing state
Session B: reads mailbox, grills ambiguous claims, continues work

Claude → Codex handoff

Session A (Claude): creates comms/, appends handoff entry
Human: git push; opens Codex on same branch
Session B (Codex): reads AGENTS.md → mailbox path → grills → continues

Edge Cases

• Same-harness Claude-only teams: prefer Agent Teams / SendMessage; this skill is for heterogeneous or cross-machine sessions.
• Empty peer outbox: initialize with a one-line pointer to README so first read routes correctly.
• Merge conflicts on outboxes: design forbids multi-writer files; if it happens, treat as process break and re-split by handle.
• Stale handoff: Grill for freshness (commit SHA, branch tip, uncommitted work) before applying.

Resources

• Protocol template: PROTOCOL_TEMPLATE.md
• Package metadata: package.json