| name | walkie-talkie |
| description | Use when two or more agent sessions — same or different platforms (Claude Code, Codex, Gemini CLI, Copilot, Cursor) — work the same repo concurrently, hand off in-flight work, or need to interrogate each other about a handoff. Triggers: "set up comms with the other session", "hand this off to Codex/Gemini", "grill the handoff", "check the mailbox", parallel sessions clobbering shared files, resuming work another agent left half-done. Trigger with "/walkie-talkie". |
| allowed-tools | Read,Write,Edit,Glob,Grep,Bash(git:*) |
| version | 1.0.0 |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| license | MIT |
| compatibility | Designed for Claude Code; also usable from Codex/Gemini/Copilot/Cursor sessions that can read and write files |
| tags | ["multi-agent","coordination","handoff","mailbox"] |
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.
