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)
- Create
comms/ next to the work it coordinates (repo-wide: .agents/comms/; sprint-scoped: docs/<area>/comms/).
- Copy PROTOCOL_TEMPLATE.md into it as
README.md, filling in the agent handles.
- 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.
- 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."
- Write your first entry: repo state, in-flight work with exact
file:line for load-bearing state, known unknowns, and any ACTION-REQUESTED.
- Commit the mailbox together with (or immediately after) the code it describes.
Message Format
Append to YOUR OWN outbox only:
## [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:
- What did you verify by running something vs. merely believe? Show the command and output.
- What is half-applied right now? Exact file:line of every load-bearing edit.
- What breaks if I touch X? Which surfaces are claimed?
- What do you know that is written down nowhere but this mailbox?
- 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:
- One writer per outbox file; append-only.
- Never edit another agent's outbox.
- Commit mailbox updates with the code they describe.
- 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
