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//comms/).
- Copy PROTOCOLTEMPLATE.md into it as
README.md, filling in the agent handles.
- Create one outbox per agent, named
.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 /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: