walkie-sh 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vikasprogrammer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# walkie
+
+P2P communication for AI agents. No server. No setup. Just talk.
+
+```
+npm install -g 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, two commands, agents are talking
+- **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
+
+**Agent A** (on any machine):
+```bash
+walkie create ops-room --secret mysecret
+walkie send ops-room "task complete, results ready"
+```
+
+**Agent B** (on any other machine):
+```bash
+walkie join ops-room --secret mysecret
+walkie read ops-room
+# [14:30:05] a1b2c3d4: task complete, results ready
+```
+
+## Commands
+
+```
+walkie create <channel> -s <secret>   Create a channel
+walkie join <channel> -s <secret>     Join a channel
+walkie send <channel> "message"       Send a message
+walkie read <channel>                 Read pending messages
+walkie read <channel> --wait          Block until a message arrives
+walkie status                         Show active channels & peers
+walkie leave <channel>                Leave a channel
+walkie stop                           Stop the daemon
+```
+
+## How it works
+
+```
+Agent A                              Agent B
+┌─────────────┐                      ┌─────────────┐
+│  walkie CLI  │                      │  walkie CLI  │
+│      ↕       │                      │      ↕       │
+│   daemon     │◄──── P2P ──────────►│   daemon     │
+│ (hyperswarm) │  encrypted via DHT   │ (hyperswarm) │
+└─────────────┘                       └─────────────┘
+```
+
+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
+
+## Use cases
+
+- **Multi-agent collaboration** — agents coordinate tasks in real-time
+- **Agent delegation** — one agent sends work to another and waits for results
+- **Agent monitoring** — watch what your agents are doing from another terminal
+- **Cross-machine pipelines** — chain agents across different servers
+
+## License
+
+MIT

package/bin/walkie.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+
+const { program } = require('commander')
+const { request } = require('../src/client')
+
+program
+  .name('walkie')
+  .description('P2P communication CLI for AI agents')
+  .version('0.1.0')
+
+program
+  .command('create <channel>')
+  .description('Create a channel and wait for peers')
+  .requiredOption('-s, --secret <secret>', 'Shared secret')
+  .action(async (channel, opts) => {
+    try {
+      const resp = await request({ action: 'join', channel, secret: opts.secret })
+      if (resp.ok) {
+        console.log(`Channel "${channel}" created. Listening for peers...`)
+      } else {
+        console.error(`Error: ${resp.error}`)
+        process.exit(1)
+      }
+    } catch (e) {
+      console.error(`Error: ${e.message}`)
+      process.exit(1)
+    }
+  })
+
+program
+  .command('join <channel>')
+  .description('Join an existing channel')
+  .requiredOption('-s, --secret <secret>', 'Shared secret')
+  .action(async (channel, opts) => {
+    try {
+      const resp = await request({ action: 'join', channel, secret: opts.secret })
+      if (resp.ok) {
+        console.log(`Joined channel "${channel}"`)
+      } else {
+        console.error(`Error: ${resp.error}`)
+        process.exit(1)
+      }
+    } catch (e) {
+      console.error(`Error: ${e.message}`)
+      process.exit(1)
+    }
+  })
+
+program
+  .command('send <channel> <message>')
+  .description('Send a message to a channel')
+  .action(async (channel, message) => {
+    try {
+      const resp = await request({ action: 'send', channel, message })
+      if (resp.ok) {
+        console.log(`Sent (delivered to ${resp.delivered} peer${resp.delivered !== 1 ? 's' : ''})`)
+      } else {
+        console.error(`Error: ${resp.error}`)
+        process.exit(1)
+      }
+    } catch (e) {
+      console.error(`Error: ${e.message}`)
+      process.exit(1)
+    }
+  })
+
+program
+  .command('read <channel>')
+  .description('Read pending messages from a channel')
+  .option('-w, --wait', 'Block until a message arrives')
+  .option('-t, --timeout <seconds>', 'Timeout for --wait in seconds', '30')
+  .action(async (channel, opts) => {
+    try {
+      const cmd = { action: 'read', channel }
+      if (opts.wait) {
+        cmd.wait = true
+        cmd.timeout = parseInt(opts.timeout, 10)
+      }
+      const timeout = opts.wait ? (parseInt(opts.timeout, 10) + 5) * 1000 : 10000
+      const resp = await request(cmd, timeout)
+      if (resp.ok) {
+        if (resp.messages.length === 0) {
+          console.log('No new messages')
+        } else {
+          for (const msg of resp.messages) {
+            const time = new Date(msg.ts).toLocaleTimeString()
+            console.log(`[${time}] ${msg.from}: ${msg.data}`)
+          }
+        }
+      } else {
+        console.error(`Error: ${resp.error}`)
+        process.exit(1)
+      }
+    } catch (e) {
+      console.error(`Error: ${e.message}`)
+      process.exit(1)
+    }
+  })
+
+program
+  .command('leave <channel>')
+  .description('Leave a channel')
+  .action(async (channel) => {
+    try {
+      const resp = await request({ action: 'leave', channel })
+      if (resp.ok) {
+        console.log(`Left channel "${channel}"`)
+      } else {
+        console.error(`Error: ${resp.error}`)
+        process.exit(1)
+      }
+    } catch (e) {
+      console.error(`Error: ${e.message}`)
+      process.exit(1)
+    }
+  })
+
+program
+  .command('status')
+  .description('Show active channels and peers')
+  .action(async () => {
+    try {
+      const resp = await request({ action: 'status' })
+      if (resp.ok) {
+        console.log(`Daemon ID: ${resp.daemonId}`)
+        const entries = Object.entries(resp.channels)
+        if (entries.length === 0) {
+          console.log('No active channels')
+        } else {
+          for (const [name, info] of entries) {
+            console.log(`  #${name} — ${info.peers} peer(s), ${info.buffered} buffered`)
+          }
+        }
+      } else {
+        console.error(`Error: ${resp.error}`)
+        process.exit(1)
+      }
+    } catch (e) {
+      console.error(`Error: ${e.message}`)
+      process.exit(1)
+    }
+  })
+
+program
+  .command('stop')
+  .description('Stop the walkie daemon')
+  .action(async () => {
+    try {
+      await request({ action: 'stop' })
+      console.log('Daemon stopped')
+    } catch {
+      console.log('Daemon is not running')
+    }
+  })
+
+program.parse()

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "walkie-sh",
+  "version": "0.1.0",
+  "description": "P2P communication CLI for AI agents. No server. No setup. Just talk.",
+  "homepage": "https://walkie.sh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vikasprogrammer/walkie.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vikasprogrammer/walkie/issues"
+  },
+  "license": "MIT",
+  "author": "vikasprogrammer",
+  "keywords": [
+    "p2p",
+    "agent",
+    "ai",
+    "communication",
+    "walkie-talkie",
+    "hyperswarm",
+    "cli",
+    "llm",
+    "multi-agent"
+  ],
+  "bin": {
+    "walkie": "./bin/walkie.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "hyperswarm": "^4.0.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,84 @@
+const net = require('net')
+const path = require('path')
+const { spawn } = require('child_process')
+const fs = require('fs')
+
+const WALKIE_DIR = process.env.WALKIE_DIR || path.join(process.env.HOME, '.walkie')
+const SOCKET_PATH = path.join(WALKIE_DIR, 'daemon.sock')
+
+function connect() {
+  return new Promise((resolve, reject) => {
+    const sock = net.connect(SOCKET_PATH)
+    sock.on('connect', () => resolve(sock))
+    sock.on('error', reject)
+  })
+}
+
+function sendCommand(sock, cmd, timeout = 60000) {
+  return new Promise((resolve, reject) => {
+    let buf = ''
+    const timer = setTimeout(() => {
+      sock.removeListener('data', onData)
+      reject(new Error('Command timed out'))
+    }, timeout)
+
+    const onData = (data) => {
+      buf += data.toString()
+      const idx = buf.indexOf('\n')
+      if (idx !== -1) {
+        clearTimeout(timer)
+        sock.removeListener('data', onData)
+        try {
+          resolve(JSON.parse(buf.slice(0, idx)))
+        } catch (e) {
+          reject(e)
+        }
+      }
+    }
+    sock.on('data', onData)
+    sock.write(JSON.stringify(cmd) + '\n')
+  })
+}
+
+async function ensureDaemon() {
+  // Try connecting to existing daemon
+  try {
+    const sock = await connect()
+    const resp = await sendCommand(sock, { action: 'ping' })
+    sock.destroy()
+    if (resp.ok) return
+  } catch {}
+
+  // Spawn daemon
+  fs.mkdirSync(WALKIE_DIR, { recursive: true })
+
+  const daemonScript = path.join(__dirname, 'daemon.js')
+  const child = spawn(process.execPath, [daemonScript], {
+    detached: true,
+    stdio: 'ignore'
+  })
+  child.unref()
+
+  // Poll until ready
+  for (let i = 0; i < 50; i++) {
+    await new Promise(r => setTimeout(r, 200))
+    try {
+      const sock = await connect()
+      const resp = await sendCommand(sock, { action: 'ping' })
+      sock.destroy()
+      if (resp.ok) return
+    } catch {}
+  }
+
+  throw new Error('Failed to start walkie daemon')
+}
+
+async function request(cmd, timeout) {
+  await ensureDaemon()
+  const sock = await connect()
+  const resp = await sendCommand(sock, cmd, timeout)
+  sock.destroy()
+  return resp
+}
+
+module.exports = { request }

package/src/crypto.js

@@ -0,0 +1,14 @@
+const crypto = require('crypto')
+
+function deriveTopic(channel, secret) {
+  return crypto.createHash('sha256')
+    .update(`walkie:${channel}:${secret}`)
+    .digest()
+}
+
+function agentId() {
+  // Generate a short random ID for this daemon instance
+  return crypto.randomBytes(4).toString('hex')
+}
+
+module.exports = { deriveTopic, agentId }

package/src/daemon.js

@@ -0,0 +1,299 @@
+const Hyperswarm = require('hyperswarm')
+const net = require('net')
+const fs = require('fs')
+const path = require('path')
+const { deriveTopic, agentId } = require('./crypto')
+
+const WALKIE_DIR = process.env.WALKIE_DIR || path.join(process.env.HOME, '.walkie')
+const SOCKET_PATH = path.join(WALKIE_DIR, 'daemon.sock')
+const PID_FILE = path.join(WALKIE_DIR, 'daemon.pid')
+const LOG_FILE = path.join(WALKIE_DIR, 'daemon.log')
+
+function log(...args) {
+  const line = `[${new Date().toISOString()}] ${args.join(' ')}\n`
+  try { fs.appendFileSync(LOG_FILE, line) } catch {}
+}
+
+class WalkieDaemon {
+  constructor() {
+    this.id = agentId()
+    this.swarm = new Hyperswarm()
+    this.channels = new Map()  // name -> { topicHex, discovery, peers: Set, messages: [], waiters: [] }
+    this.peers = new Map()     // remoteKey hex -> { conn, channels: Set }
+  }
+
+  async start() {
+    fs.mkdirSync(WALKIE_DIR, { recursive: true })
+    fs.writeFileSync(PID_FILE, process.pid.toString())
+
+    // Clean stale socket
+    try { fs.unlinkSync(SOCKET_PATH) } catch {}
+
+    // IPC server for CLI commands
+    const server = net.createServer(sock => this._onIPC(sock))
+    server.listen(SOCKET_PATH)
+
+    // P2P connections
+    this.swarm.on('connection', (conn, info) => this._onPeer(conn, info))
+
+    process.on('SIGTERM', () => this.shutdown())
+    process.on('SIGINT', () => this.shutdown())
+
+    log(`Daemon started id=${this.id} pid=${process.pid}`)
+  }
+
+  // ── IPC (CLI <-> Daemon) ──────────────────────────────────────────
+
+  _onIPC(socket) {
+    let buf = ''
+    socket.on('data', data => {
+      buf += data.toString()
+      let idx
+      while ((idx = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, idx)
+        buf = buf.slice(idx + 1)
+        if (line.trim()) {
+          try {
+            this._exec(JSON.parse(line), socket)
+          } catch (e) {
+            socket.write(JSON.stringify({ ok: false, error: e.message }) + '\n')
+          }
+        }
+      }
+    })
+    socket.on('error', () => {})
+  }
+
+  async _exec(cmd, socket) {
+    const reply = d => socket.write(JSON.stringify(d) + '\n')
+
+    try {
+      switch (cmd.action) {
+        case 'join': {
+          await this._joinChannel(cmd.channel, cmd.secret)
+          reply({ ok: true, channel: cmd.channel })
+          break
+        }
+        case 'send': {
+          const count = this._send(cmd.channel, cmd.message)
+          reply({ ok: true, delivered: count })
+          break
+        }
+        case 'read': {
+          const ch = this.channels.get(cmd.channel)
+          if (!ch) { reply({ ok: false, error: `Not in channel: ${cmd.channel}` }); return }
+
+          // If messages available or no wait requested, return immediately
+          if (ch.messages.length > 0 || !cmd.wait) {
+            reply({ ok: true, messages: ch.messages.splice(0) })
+            return
+          }
+
+          // Wait mode: hold connection until a message arrives or timeout
+          const timeout = (cmd.timeout || 30) * 1000
+          const timer = setTimeout(() => {
+            ch.waiters = ch.waiters.filter(w => w !== waiter)
+            reply({ ok: true, messages: [] })
+          }, timeout)
+
+          const waiter = (msgs) => {
+            clearTimeout(timer)
+            reply({ ok: true, messages: msgs })
+          }
+          ch.waiters.push(waiter)
+          break
+        }
+        case 'leave': {
+          await this._leaveChannel(cmd.channel)
+          reply({ ok: true })
+          break
+        }
+        case 'status': {
+          const channels = {}
+          for (const [name, ch] of this.channels) {
+            channels[name] = { peers: ch.peers.size, buffered: ch.messages.length }
+          }
+          reply({ ok: true, channels, daemonId: this.id })
+          break
+        }
+        case 'ping': {
+          reply({ ok: true })
+          break
+        }
+        case 'stop': {
+          reply({ ok: true })
+          await this.shutdown()
+          break
+        }
+        default:
+          reply({ ok: false, error: `Unknown action: ${cmd.action}` })
+      }
+    } catch (e) {
+      reply({ ok: false, error: e.message })
+    }
+  }
+
+  // ── Channel management ────────────────────────────────────────────
+
+  async _joinChannel(name, secret) {
+    if (this.channels.has(name)) return
+
+    const topic = deriveTopic(name, secret)
+    const topicHex = topic.toString('hex')
+    log(`Joining channel "${name}" topic=${topicHex.slice(0, 16)}...`)
+    const discovery = this.swarm.join(topic, { server: true, client: true })
+    await discovery.flushed()
+    log(`Channel "${name}" flushed, discoverable`)
+
+    this.channels.set(name, {
+      topicHex,
+      discovery,
+      peers: new Set(),
+      messages: [],
+      waiters: []
+    })
+
+    // Re-announce topics to already-connected peers (fixes race condition
+    // where peer connects before channel is registered)
+    this._reannounce()
+  }
+
+  _reannounce() {
+    const topics = Array.from(this.channels.values()).map(ch => ch.topicHex)
+    const hello = JSON.stringify({ t: 'hello', topics, id: this.id }) + '\n'
+    for (const [remoteKey, peer] of this.peers) {
+      if (peer.conn?.writable) {
+        log(`Re-announcing ${topics.length} topic(s) to ${remoteKey.slice(0, 12)}`)
+        peer.conn.write(hello)
+      }
+      // Also match this peer against our newly added channels
+      // (handles case where we received their hello before our channel was ready)
+      if (peer.knownTopics) {
+        for (const [name, ch] of this.channels) {
+          if (peer.knownTopics.has(ch.topicHex) && !ch.peers.has(remoteKey)) {
+            ch.peers.add(remoteKey)
+            peer.channels.add(name)
+            log(`Late-matched channel "${name}" with peer ${remoteKey.slice(0, 12)}`)
+          }
+        }
+      }
+    }
+  }
+
+  async _leaveChannel(name) {
+    const ch = this.channels.get(name)
+    if (!ch) return
+    await ch.discovery.destroy()
+    this.channels.delete(name)
+  }
+
+  // ── P2P peer handling ─────────────────────────────────────────────
+
+  _onPeer(conn, info) {
+    const remoteKey = conn.remotePublicKey.toString('hex')
+    log(`Peer connected: ${remoteKey.slice(0, 12)}...`)
+
+    const peer = { conn, channels: new Set(), buf: '' }
+    this.peers.set(remoteKey, peer)
+
+    // Send handshake: our active topic list
+    const topics = Array.from(this.channels.values()).map(ch => ch.topicHex)
+    log(`Sending hello with ${topics.length} topic(s)`)
+    conn.write(JSON.stringify({ t: 'hello', topics, id: this.id }) + '\n')
+
+    conn.on('data', data => {
+      peer.buf += data.toString()
+      let idx
+      while ((idx = peer.buf.indexOf('\n')) !== -1) {
+        const line = peer.buf.slice(0, idx)
+        peer.buf = peer.buf.slice(idx + 1)
+        if (line.trim()) {
+          try { this._onPeerMsg(remoteKey, JSON.parse(line)) } catch {}
+        }
+      }
+    })
+
+    conn.on('close', () => {
+      for (const [, ch] of this.channels) ch.peers.delete(remoteKey)
+      this.peers.delete(remoteKey)
+    })
+
+    conn.on('error', () => conn.destroy())
+  }
+
+  _onPeerMsg(remoteKey, msg) {
+    const peer = this.peers.get(remoteKey)
+    if (!peer) return
+
+    if (msg.t === 'hello') {
+      const theirTopics = new Set(msg.topics || [])
+      peer.knownTopics = theirTopics  // Store for late-matching
+      log(`Got hello from ${remoteKey.slice(0, 12)} with ${theirTopics.size} topic(s)`)
+      for (const [name, ch] of this.channels) {
+        if (theirTopics.has(ch.topicHex) && !ch.peers.has(remoteKey)) {
+          ch.peers.add(remoteKey)
+          peer.channels.add(name)
+          log(`Matched channel "${name}" with peer ${remoteKey.slice(0, 12)}`)
+        }
+      }
+      return
+    }
+
+    if (msg.t === 'msg') {
+      for (const [name, ch] of this.channels) {
+        if (ch.topicHex === msg.topic) {
+          const entry = { from: msg.id || remoteKey.slice(0, 8), data: msg.data, ts: msg.ts }
+
+          // If someone is waiting, deliver directly
+          if (ch.waiters.length > 0) {
+            const waiter = ch.waiters.shift()
+            waiter([entry])
+          } else {
+            ch.messages.push(entry)
+          }
+          break
+        }
+      }
+    }
+  }
+
+  // ── Send ──────────────────────────────────────────────────────────
+
+  _send(channelName, message) {
+    const ch = this.channels.get(channelName)
+    if (!ch) throw new Error(`Not in channel: ${channelName}`)
+
+    const payload = JSON.stringify({
+      t: 'msg',
+      topic: ch.topicHex,
+      data: message,
+      id: this.id,
+      ts: Date.now()
+    }) + '\n'
+
+    let count = 0
+    for (const remoteKey of ch.peers) {
+      const peer = this.peers.get(remoteKey)
+      if (peer?.conn?.writable) {
+        peer.conn.write(payload)
+        count++
+      }
+    }
+    return count
+  }
+
+  // ── Shutdown ──────────────────────────────────────────────────────
+
+  async shutdown() {
+    try { fs.unlinkSync(SOCKET_PATH) } catch {}
+    try { fs.unlinkSync(PID_FILE) } catch {}
+    await this.swarm.destroy()
+    process.exit(0)
+  }
+}
+
+const daemon = new WalkieDaemon()
+daemon.start().catch(e => {
+  console.error('Failed to start daemon:', e.message)
+  process.exit(1)
+})