walkie: Instructions file for Claude Code

CLAUDE.md

Project

walkie — P2P communication CLI for AI agents. npm package: walkie-sh.

Architecture

• bin/walkie.js — CLI entry point (commander). Version is here AND in package.json (keep in sync)
• src/api.js — Programmatic API (require('walkie-sh')). Exports listen() and send(). Uses daemon IPC under the hood.
• src/daemon.js — background daemon managing Hyperswarm P2P + local subscriber routing
• src/client.js — IPC client, handles daemon auto-start and stale socket cleanup
• src/crypto.js — topic derivation (SHA-256 of channel+secret)
• src/cli-utils.js — identity resolution (WALKIE_ID > ~/.walkie/config.json > terminal session), channel arg parsing, message filters
• src/slack.js — Slack <-> walkie bridge over Socket Mode (walkie slack)
• src/web.js — HTTP + WebSocket server bridging browser clients to daemon
• src/web-ui.js — exports HTML string for web chat UI (minimal, terminal-style)

Programmatic API

package.json "main" points to src/api.js. Node apps can require('walkie-sh'):

const walkie = require('walkie-sh')

// Listen on a channel (EventEmitter — emits 'message' and 'error')
const ch = await walkie.listen('mychannel:secret', { id: 'mybot' })
ch.on('message', async (msg) => {
  // msg: { from: string, data: string, ts: number, id: string }
  await ch.send('response')
})
await ch.close()

// One-shot send (auto-joins if secret provided)
await walkie.send('mychannel:secret', 'hello', { id: 'sender' })

• listen() joins the channel, starts streaming via streamMessages(), filters own messages, returns a WalkieChannel (EventEmitter + send() + close())
• send() auto-joins and fires a single message — good for scripts/CI
• Both auto-start the daemon if not running

Testing

npm test — 120 automated tests using node:test (zero extra deps). Covers crypto, store, CLI utils, daemon IPC, web server, and programmatic API.

npm run test:p2p — manual P2P integration test (two daemons, Hyperswarm discovery, ~30s).