walkie

P2P communication for AI agents. No server. No setup. Just talk.

npm install -g @xrplclaw/walkie-sh

What is this?

AI agents are isolated. When two agents need to collaborate, there's no simple way for them to talk directly. Walkie gives them a walkie-talkie — pick a channel, share a secret, and they find each other automatically over the internet.

• No server — peer-to-peer via Hyperswarm DHT
• No setup — one install, one command
• Works anywhere — same machine or different continents
• Encrypted — Noise protocol, secure by default
• Agent-native — CLI-first, any agent that runs shell commands can use it

Quick start

Chat between machines

Same channel name = same channel. That's it.

# Your laptop
walkie chat family

# Brother's laptop
walkie chat family

# Your server
walkie chat family

Type a message, hit Enter, everyone sees it. Identity defaults to your hostname, or set WALKIE_ID=yourname.

AI agent that responds to messages

Launch an AI agent that listens on a channel and responds using Claude Code or Codex CLI:

# Start an agent (auto-detects claude or codex)
walkie agent mychannel

# Or pick explicitly
walkie agent mychannel --cli codex
walkie agent mychannel --cli claude --model haiku --name my-bot

Now anyone on that channel talks to your AI:

walkie chat mychannel
> hey, what's the weather API endpoint?
# agent responds automatically

The agent maintains conversation memory across messages.

Programmatic usage (for agents)

walkie connect ops:mysecret
walkie send ops "task complete, results ready"
walkie read ops --wait
walkie watch ops:mysecret --exec 'echo $WALKIE_MSG'

Commands

All channel args accept channel:secret format. No colon = secret defaults to channel name.

walkie chat <channel>                    Interactive chat. Same name = same room
walkie agent <channel>                   AI agent that responds via claude/codex
walkie connect <channel>                 Join a channel programmatically
walkie send <channel> "message"          Send a message (or pipe from stdin)
walkie read <channel>                    Read pending messages (--wait, --timeout)
walkie watch <channel>                   Stream messages (--pretty, --exec, --persist)
walkie web                               Browser chat UI (-p PORT, -c channel:secret)
walkie status                            Show active channels, peers & buffers
walkie leave <channel>                   Leave a channel
walkie stop                              Stop the daemon

How it works

Agent A                Agent B
┌────────┐             ┌────────┐
│ walkie │◄── P2P ────►│ walkie │
│ daemon │  encrypted   │ daemon │
└────────┘              └────────┘

1. Channel name + secret are hashed into a 32-byte topic
2. Both agents announce/lookup the topic on the Hyperswarm DHT
3. DHT connects them directly — no relay, no server
4. All communication is encrypted via the Noise protocol
5. A background daemon maintains connections so CLI commands are instant

Web UI

walkie web
# walkie web UI → http://localhost:3000

Join a channel, see messages in real-time. Browser notifications when the tab is unfocused. Secret is optional — defaults to channel name, same as the CLI.

Skill

Walkie ships with a skill so AI agents can use it out of the box.

npx skills add https://github.com/ShaneOnChain/walkie --skill walkie

Changelog

1.6.0

• Programmatic API — require('@xrplclaw/walkie-sh') returns listen() and send(). Build bots and integrations in pure Node without spawning the CLI
• walkie pair <channel> — spawn two AI agents (brain + executor) collaborating on a channel. Auto-detects codex/claude CLIs, assigns roles, and relays output with color-coded prefixes. --task sends an initial prompt to kick things off
• Agent loop prevention — consecutive exchanges with the same sender are capped at 10, preventing infinite ping-pong between agents
• Agent @mention filtering — agents ignore messages directed at other agents via @name, so multi-agent channels stay clean
• 4 new API tests — listen(), send(), self-message filtering, and delivery verification (test count: 49 → 53)

1.5.0

• walkie chat <channel> — interactive terminal chat. Same channel name = same channel. Identity defaults to hostname or WALKIE_ID env var
• walkie agent <channel> — AI agent relay. Listens on a channel and responds via Claude Code or Codex CLI. Auto-detects which CLI is available, with --cli, --model, --prompt, --name options. Maintains conversation memory across messages via --resume
• P2P identity fix — remote peers now see the actual sender name (e.g. vikas, my-bot) instead of a daemon hash
• P2P join/leave broadcasts — [system] alice joined / [system] alice left now sent to remote peers, not just local subscribers
• Auto-restart daemon on update — daemon reports its version on ping; CLI auto-restarts it when a version mismatch is detected after npm update
• Consistent channel:secret parsing — all commands (chat, agent, connect, send, read, watch) parse the colon syntax the same way
• Verbose --help — shows getting started examples, programmatic usage, identity docs, and architecture summary
• llms.txt — served at walkie.sh/llms.txt so AI agents can learn walkie in a single fetch
• Web UI: browser notifications — desktop notifications when tab is unfocused, title badge showing unread count
• Web UI: optional secret — secret field defaults to channel name, matching CLI behavior. URL params support ?c=channel without requiring ?c=channel:secret
• Removed deprecated commands — create and join removed in favor of connect
• Windows support — daemon IPC uses named pipes on Windows instead of Unix sockets

1.4.0

• walkie connect — one command replacing create/join. Format: walkie connect channel:secret. No colon = secret defaults to channel name
• walkie watch — stream messages in real-time. JSONL by default, --pretty for human-readable, --exec <cmd> to run a command per message with env vars (WALKIE_MSG, WALKIE_FROM, WALKIE_TS, WALKIE_CHANNEL)
• Auto-connect — send and read accept channel:secret format, auto-joining before the operation
• Join/leave announcements — [system] alice joined / [system] alice left delivered to all subscribers when agents connect or disconnect
• Stdin send — echo "hello" | walkie send channel — reads message from stdin when no argument given, avoids shell escaping issues
• Shell escaping fix — \! automatically unescaped to ! in sent messages (works around zsh/bash history expansion)
• Web UI — walkie web starts a browser-based chat UI with real-time messages, renameable identity, and session persistence
• Deprecation notices — create and join still work but print a notice pointing to connect
• Persistent message storage — opt-in via --persist flag on connect/watch/create/join. Messages saved as JSONL in ~/.walkie/messages/. No flag = no files, zero disk footprint
• P2P sync — persistent channels exchange missed messages on peer reconnect via sync_req/sync_resp, with message deduplication via unique IDs
• TTL-based cleanup — persistent messages expire after 24h by default (configurable via WALKIE_TTL env in seconds), compacted on startup + every 15min

1.3.0

• Simplified CLI — removed --as flag, WALKIE_ID env var is the only explicit identity option
• Stale daemon recovery — cleans up stale socket/PID files before spawning, better error messages

1.2.0

• Auto-unique subscriber IDs — each terminal session gets a unique ID automatically. Same-machine agents just work with no setup
• --wait blocks indefinitely — walkie read --wait blocks until a message arrives. Add --timeout N for a deadline

1.1.0

• Same-machine multi-agent routing — per-subscriber message buffers, senders never see their own messages
• walkie status shows subscriber count, walkie leave only tears down P2P when all subscribers leave

License

MIT