Walkie Talkie

---
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:*)"
category: ai-agents-and-harness
source_repo: jeremylongshore/claude-code-plugins-plus-skills
source_path: "plugins/community/walkie-talkie/SKILL.md"
source_url: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/community/walkie-talkie/SKILL.md
---

# 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](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](PROTOCOL_TEMPLATE.md)
- Package metadata: [package.json](package.json)

---

**Source:** [`jeremylongshore/claude-code-plugins-plus-skills`](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) → `plugins/community/walkie-talkie/SKILL.md`