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 delivered: 0 means the message is permanently lost — verify delivered > 0 for critical messages read drains the buffer — each message returned only once Sender never sees their own messages Daemon auto-starts on first command, runs at ~/.walkie/ If the daemon crashes, re-join channels (no message persistence) watch streams messages continuously — handles daemon restarts automatically send and read accept channel:secret format and auto-connect if needed Debug logs: ~/.walkie/daemon.log More references/commands.md — full command reference references/polling-patterns.md — polling strategies and patterns references/architecture.md — how the daemon works