walkie

name	walkie
description	P2P communication between AI agents using walkie-sh CLI. Use when the user asks to set up agent-to-agent communication, create a walkie channel, send/receive messages between agents, or enable real-time coordination between multiple AI agents. Triggers on "walkie", "agent communication", "talk to another agent", "set up a channel", "inter-agent messaging", "collaborate with", "coordinate with".
allowed-tools	Bash(walkie:*)

Walkie — Agent-to-Agent Communication

Each terminal session automatically gets a unique subscriber ID. Two agents in different terminals can communicate immediately — no setup beyond connecting to a channel.

How to use walkie

Step 1. Connect to a channel:

walkie connect <channel>:<secret>

Step 2. Send and read messages:

walkie send <channel> "your message"
walkie read <channel>                      # non-blocking, returns buffered messages
walkie read <channel> --wait               # blocks until a message arrives
walkie read <channel> --wait --timeout 60  # optional: give up after N seconds

Step 3. Stream messages (alternative to polling):

walkie watch <channel>:<secret>            # JSONL output, auto-connects
walkie watch <channel>:<secret> --pretty   # human-readable format
walkie watch <channel>:<secret> --exec 'handle_msg.sh'  # run command per message

Step 4. Clean up when done:

walkie leave <channel>

Listening for messages (recommended for AI agents)

AI agents like Claude Code can't run a blocking watch process and do work at the same time. Instead, use background read --wait:

# 1. Connect to the channel
walkie connect <channel>:<secret>

# 2. Start a background read that waits for the next message
walkie read <channel> --wait          # run this in background (run_in_background=true)

# 3. When notified of completion, read the output — that's the message
# 4. Act on it, then start another background read --wait

This works because read --wait blocks until a message arrives, then returns. Claude Code's background task system automatically notifies you when it completes. No polling, no separate terminal.

For non-AI-agent use cases (scripts, cron jobs), use walkie watch with --exec instead.

Example

# Terminal 1 (Alice)
walkie connect room:secret
walkie send room "hello from alice"

# Terminal 2 (Bob)
walkie connect room:secret
walkie read room
# [14:30:05] alice: hello from alice

Behavior to know

• When an agent connects, all existing subscribers see [system] X joined
• When an agent leaves, remaining subscribers see [system] X left
• send reads from stdin if no message argument given — use echo "msg" | walkie send channel to avoid shell escaping
• A successful send means "queued at a peer daemon or local subscriber", not "an agent read it". A peer whose agent has died still counts. Never treat a send as proof anyone saw the message
• If nothing is queued anywhere, the message is permanently lost — there is no buffering for offline peers
• read drains the buffer — each message returned only once
• Sender never sees their own messages as long as its identity is stable. The daemon excludes the sending subscriber by name, so if your identity changes between sending and reading (see below) your own messages come back to you
• Set a stable identity before anything else: walkie whoami --set <name>. WALKIE_ID alone is unreliable for agents — it is an environment variable, and ~/.bashrc returns early for non-interactive shells, which is how agents run
• Use walkie read <ch> --wait --from-others --no-system as the blocking primitive. Plain --wait returns on any traffic including [system] X joined, which wastes a wake-up
• Correlate replies with walkie send --reply-to <id> and walkie read --ids
• Use walkie read <ch> --json for anything programmatic. data is one JSON string (multi-line bodies need no boundary parsing), self tells you if you sent it, and type separates real messages from system notices. The human format is locale-dependent and must not be parsed
• Never say "I'll start unless you object" for anything touching a shared resource — delivery is fast but not synchronous, so that races the round trip. Use walkie send "may I start?" --await-reply 120 and act only on the reply
• walkie log <ch> reads persisted history without draining; read --peek inspects the live buffer without consuming it
• Assume every read may be incomplete. --drain collects a burst whose gaps are under --settle (200ms default); anything arriving later is missed by definition. A on stderr means you are behind — but its absence does not mean you are caught up. Re-read before acting on anything important

More

• references/commands.md — full command reference
• references/polling-patterns.md — polling strategies and patterns
• references/architecture.md — how the daemon works