livetap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 livetap contributors
+
+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,223 @@
+# livetap
+
+> Push live data streams into your AI coding agent.
+
+Connect MQTT brokers, WebSocket feeds, or tail log files. Your agent samples, watches, and acts on real-time data through natural language.
+
+<!-- TODO: Add demo GIF here after recording -->
+<!-- ![livetap demo](demo.gif) -->
+
+## Quick start
+
+**Requirements:** [Bun](https://bun.sh), [Redis](https://redis.io/) (`brew install redis`), Claude Code v2.1.80+
+
+```bash
+bun add livetap
+```
+
+Start the daemon and Claude Code:
+
+```bash
+livetap start
+claude --dangerously-load-development-channels server:livetap
+```
+
+Then ask your agent:
+
+> "Connect to the IoT demo at mqtt://broker.emqx.io on topic justinx/demo/# and watch for temperature above 23 degrees"
+
+## What it does
+
+livetap runs a background daemon that connects to live data sources, buffers messages in embedded Redis, and pushes alerts into your Claude Code session via the [Channels API](https://code.claude.com/docs/en/channels). Your agent sees the data in real-time and can create expression-based watchers that fire when conditions match.
+
+```
+Source (MQTT/WS/File) ──> Subscriber ──> Redis Stream ──> Watcher Engine
+                                              |                 |
+                                              v                 v (on match)
+                                         read_stream        Channel Alert
+                                         (agent samples)    ──> Claude Code
+                                                            ──> agent acts
+```
+
+## Examples
+
+### IoT sensor monitoring
+
+```
+You: "Connect to mqtt://broker.emqx.io:1883/justinx/demo/# and watch for temperature above 25°C"
+
+Agent: Creates connection, samples the data to learn the payload structure,
+       sets up watcher on sensors.environmental.temperature.value > 25.
+       When it fires, summarizes: "sensor-zone-c hit 25.4°C at 10:05:08Z"
+```
+
+### Crypto price alerts
+
+```
+You: "Tap the Binance BTC/USDT trade stream and alert me if price drops below 60000"
+
+Agent: Connects to wss://stream.binance.com:9443/ws/btcusdt@trade,
+       samples to see the price field is "p" (string),
+       sets up watcher with regex: p matches "^[1-5]" (prices starting with 1-5 = below 60k)
+```
+
+### Log file monitoring
+
+```
+You: "Watch my nginx error log for 5xx errors and summarize each one"
+
+Agent: Taps file:///var/log/nginx/error.log,
+       creates watcher: payload matches "5[0-9]{2}",
+       when an error appears, analyzes it:
+       "503 Service Unavailable on /api/data — upstream auth-service not responding"
+```
+
+### WiFi disconnect detection
+
+```
+You: "Monitor /var/log/wifi.log and alert me when WiFi drops"
+
+Agent: Taps the file, samples to see log format, creates regex watcher
+       for power state changes. When you toggle WiFi:
+       "Wi-Fi powered OFF at 17:51:45, back ON at 17:51:47 (2s outage)"
+```
+
+## CLI
+
+```bash
+# Daemon
+livetap start                                    # Start (embedded Redis + API)
+livetap stop                                     # Stop
+livetap status                                   # Dashboard
+
+# Tap into data sources
+livetap tap mqtt://broker.emqx.io:1883/sensors/# # MQTT broker
+livetap tap wss://stream.binance.com:9443/ws/btcusdt@trade  # WebSocket
+livetap tap file:///var/log/nginx/error.log       # Log file
+livetap taps                                      # List active taps
+livetap untap <connectionId>                      # Remove
+
+# Sample data
+livetap sip <connectionId>                        # Pretty JSON output
+livetap sip <connectionId> --raw                  # Raw JSON
+
+# Watchers
+livetap watch <connId> "temperature > 50"                    # Numeric
+livetap watch <connId> "payload matches 'ERROR|FATAL'"       # Regex
+livetap watch <connId> "temp > 50 AND humidity > 90"         # AND
+livetap watch <connId> "price > 70000" --cooldown 300        # Custom cooldown
+livetap watchers                                             # List all
+livetap watchers --logs <watcherId>                          # View logs
+livetap unwatch <watcherId>                                  # Remove
+```
+
+## Supported sources
+
+| Protocol | Example | Use case |
+|----------|---------|----------|
+| **MQTT** | `livetap tap mqtt://broker.emqx.io:1883/sensors/#` | IoT sensors, home automation |
+| **WebSocket** | `livetap tap wss://stream.binance.com:9443/ws/btcusdt@trade` | Finance, real-time APIs |
+| **File tailing** | `livetap tap file:///var/log/nginx/error.log` | Log monitoring, DevOps |
+| Webhooks | Planned v0.1 | CI/CD, external services |
+| Kafka | Planned v0.2 | Event sourcing, analytics |
+
+## MCP tools
+
+livetap exposes 12 MCP tools that your agent uses automatically:
+
+| Tool | What it does |
+|------|-------------|
+| `create_connection` | Connect to MQTT, WebSocket, or file |
+| `list_connections` | List active connections |
+| `get_connection` | Connection details and stats |
+| `destroy_connection` | Remove a connection |
+| `read_stream` | Sample recent entries from a stream |
+| `create_watcher` | Set up expression-based alerts |
+| `list_watchers` | List watchers |
+| `get_watcher` | Watcher details |
+| `get_watcher_logs` | View MATCH/SUPPRESSED logs |
+| `update_watcher` | Change conditions or cooldown |
+| `delete_watcher` | Remove a watcher |
+| `restart_watcher` | Restart a stopped watcher |
+
+## Expression watchers
+
+Watchers use structured conditions — not arbitrary code:
+
+```json
+{
+  "conditions": [
+    { "field": "sensors.temperature.value", "op": ">", "value": 50 },
+    { "field": "sensors.humidity.value", "op": ">", "value": 90 }
+  ],
+  "match": "all",
+  "cooldown": 60
+}
+```
+
+**Operators:** `>`, `<`, `>=`, `<=`, `==`, `!=`, `contains`, `matches` (regex)
+
+**Cooldown:** Seconds between repeated alerts. `0` for every match, `60` default.
+
+When a watcher fires, the alert arrives as a `<channel>` tag in your Claude Code session. The agent reads it and acts — writing to a file, calling an API, or whatever you asked.
+
+## How the agent uses livetap
+
+The MCP instructions teach the agent this workflow:
+
+1. **CONNECT** — `create_connection` to tap a source
+2. **SAMPLE** — `read_stream` to see the data shape (always before creating watchers)
+3. **WATCH** — `create_watcher` with the correct field paths
+4. **ACT** — when `<channel>` alerts arrive, do what the user asked
+
+The agent knows field paths differ by source:
+- **MQTT/WebSocket:** JSON payload parsed — use dot-paths like `sensors.temperature.value`
+- **File (text):** raw line in `payload` field — use `payload contains "ERROR"` or `payload matches "5[0-9]{2}"`
+- **File (JSON lines):** parsed — use dot-paths like `level`, `msg`
+
+## Configuration
+
+**Daemon port:** Default `:8788`. Override with `--port` or `LIVETAP_PORT` env var.
+
+**State directory:** `~/.livetap/` stores daemon PID, logs, and watcher evaluation logs.
+
+**MCP config:** `.mcp.json` in your project root:
+```json
+{
+  "mcpServers": {
+    "livetap": {
+      "command": "bun",
+      "args": ["path/to/src/mcp/channel.ts"]
+    }
+  }
+}
+```
+
+**Machine-readable help:** `livetap --llm-help` outputs structured JSON for AI agents.
+
+## Development
+
+```bash
+git clone https://github.com/livetap/livetap.git
+cd livetap && git checkout v0
+bun install
+bun test                         # 103 tests
+bun test tests/phase1/           # Specific phase
+SKIP_LIVE_MQTT=1 bun test        # Skip tests needing broker.emqx.io
+```
+
+See [docs/PLAN.md](docs/PLAN.md) for the full build plan with phased architecture.
+
+## Contributing
+
+1. Fork and clone
+2. `bun install && bun test`
+3. Make changes, add tests
+4. `bun test` must pass
+5. PR to `v0` branch
+
+See [docs/PLAN.md](docs/PLAN.md) for architecture and module layout.
+
+## License
+
+MIT

package/bin/livetap.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+/**
+ * livetap CLI entry point.
+ */
+
+const [cmd, ...args] = Bun.argv.slice(2)
+
+const commands: Record<string, () => Promise<void>> = {
+  start:    () => import('../src/cli/start.js').then((m) => m.run(args)),
+  stop:     () => import('../src/cli/stop.js').then((m) => m.run(args)),
+  status:   () => import('../src/cli/status.js').then((m) => m.run(args)),
+  tap:      () => import('../src/cli/tap.js').then((m) => m.run(args)),
+  untap:    () => import('../src/cli/untap.js').then((m) => m.run(args)),
+  taps:     () => import('../src/cli/taps.js').then((m) => m.run(args)),
+  sip:      () => import('../src/cli/sip.js').then((m) => m.run(args)),
+  watch:    () => import('../src/cli/watch.js').then((m) => m.run(args)),
+  unwatch:  () => import('../src/cli/unwatch.js').then((m) => m.run(args)),
+  watchers: () => import('../src/cli/watchers.js').then((m) => m.run(args)),
+  mcp:      () => import('../src/mcp/channel.js'),
+  help:     () => import('../src/cli/help.js').then((m) => m.run(args)),
+}
+
+if (!cmd || cmd === '--help' || cmd === '-h') {
+  await commands.help()
+} else if (cmd === '--llm-help') {
+  const { generateLlmHelp } = await import('../src/shared/catalog-generators.js')
+  console.log(JSON.stringify(generateLlmHelp(), null, 2))
+} else if (commands[cmd]) {
+  await commands[cmd]()
+} else {
+  console.error(`Unknown command: ${cmd}. Run 'livetap help' for usage.`)
+  process.exit(1)
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "livetap",
+  "version": "0.1.0",
+  "description": "Push live data streams into your AI coding agent. Connect MQTT, WebSocket, or webhooks.",
+  "type": "module",
+  "bin": {
+    "livetap": "./bin/livetap.ts"
+  },
+  "scripts": {
+    "postinstall": "bun ./scripts/postinstall.ts",
+    "test": "bun test"
+  },
+  "keywords": [
+    "mqtt", "kafka", "websocket", "webhook", "streaming",
+    "real-time", "monitoring", "alerts", "mcp", "claude-code",
+    "ai-agent", "iot", "observability", "data-pipeline"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/livetap/livetap"
+  },
+  "homepage": "https://github.com/livetap/livetap",
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/postinstall.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "ioredis": "^5.10.1",
+    "mqtt": "^5.15.1",
+    "redis-server": "^1.2.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/scripts/postinstall.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env bun
+/**
+ * Postinstall script — auto-configures .mcp.json for Claude Code.
+ * Runs after `bun add livetap` or `npm install livetap`.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { resolve } from 'path'
+
+const MCP_ENTRY = {
+  livetap: {
+    command: 'bun',
+    args: [resolve(import.meta.dir, '..', 'src', 'mcp', 'channel.ts')],
+  },
+}
+
+function findProjectRoot(): string {
+  // If we're inside node_modules, walk up past it to find the project root
+  const scriptDir = resolve(import.meta.dir)
+  const nmIdx = scriptDir.lastIndexOf('node_modules')
+  if (nmIdx !== -1) {
+    const root = scriptDir.slice(0, nmIdx).replace(/\/$/, '')
+    if (existsSync(resolve(root, 'package.json'))) return root
+  }
+  // Fallback to cwd (e.g. when running postinstall directly for testing)
+  return process.cwd()
+}
+
+function run() {
+  // Skip in CI or when explicitly disabled
+  if (process.env.CI || process.env.LIVETAP_SKIP_POSTINSTALL) return
+
+  const root = findProjectRoot()
+  const mcpPath = resolve(root, '.mcp.json')
+
+  let config: any = {}
+  if (existsSync(mcpPath)) {
+    try {
+      config = JSON.parse(readFileSync(mcpPath, 'utf-8'))
+    } catch {
+      console.warn('\n  ⚠ .mcp.json exists but is malformed. Skipping auto-config.')
+      console.warn('    Add the livetap entry manually (see below).\n')
+      printManualInstructions()
+      return
+    }
+  }
+
+  // Don't overwrite if livetap entry already exists
+  if (config.mcpServers?.livetap) {
+    console.log('\n  ✓ livetap already configured in .mcp.json\n')
+    printRestartInstructions()
+    return
+  }
+
+  // Add livetap entry
+  if (!config.mcpServers) config.mcpServers = {}
+  config.mcpServers.livetap = MCP_ENTRY.livetap
+  writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n')
+
+  console.log('\n  ✓ livetap added to .mcp.json\n')
+  printRestartInstructions()
+}
+
+function printRestartInstructions() {
+  console.log('  To enable live data streaming in Claude Code, restart with:\n')
+  console.log('    claude --dangerously-load-development-channels server:livetap\n')
+  console.log('  Then ask Claude: "Connect to mqtt://broker.emqx.io:1883/sensors/#"\n')
+}
+
+function printManualInstructions() {
+  console.log('  Add to .mcp.json:\n')
+  console.log('    ' + JSON.stringify({ mcpServers: MCP_ENTRY }, null, 2).split('\n').join('\n    ') + '\n')
+}
+
+run()

package/src/cli/daemon-client.ts

@@ -0,0 +1,43 @@
+/**
+ * HTTP client for talking to the livetap daemon.
+ */
+
+import { resolve } from 'path'
+import { homedir } from 'os'
+import { existsSync, readFileSync } from 'fs'
+
+const STATE_PATH = resolve(homedir(), '.livetap', 'state.json')
+
+export function getDaemonUrl(): string {
+  const port = process.env.LIVETAP_PORT || '8788'
+  return `http://127.0.0.1:${port}`
+}
+
+export async function isDaemonRunning(): Promise<boolean> {
+  try {
+    const res = await fetch(`${getDaemonUrl()}/status`)
+    return res.ok
+  } catch {
+    return false
+  }
+}
+
+export function requireDaemon() {
+  // Called at start of commands that need the daemon
+  // Actual check is async, so this just prints the message format
+}
+
+export async function daemonFetch(path: string, opts?: RequestInit): Promise<Response> {
+  const url = `${getDaemonUrl()}${path}`
+  try {
+    return await fetch(url, opts)
+  } catch (err) {
+    console.error('Error: livetap daemon is not running. Use "livetap start" first.')
+    process.exit(1)
+  }
+}
+
+export async function daemonJson(path: string, opts?: RequestInit): Promise<any> {
+  const res = await daemonFetch(path, opts)
+  return res.json()
+}

package/src/cli/help.ts

@@ -0,0 +1,9 @@
+/**
+ * livetap help — generated from command catalog.
+ */
+
+import { generateHelpText } from '../shared/catalog-generators.js'
+
+export async function run(_args: string[]) {
+  console.log(generateHelpText())
+}

package/src/cli/sip.ts

@@ -0,0 +1,63 @@
+/**
+ * livetap sip <connectionId> — Sample recent stream entries.
+ */
+
+import { daemonFetch } from './daemon-client.js'
+
+export async function run(args: string[]) {
+  const id = args[0]
+  if (!id) {
+    console.error('Usage: livetap sip <connectionId>')
+    process.exit(1)
+  }
+
+  const rawMode = args.includes('--raw')
+  const maxIdx = args.indexOf('--max')
+  const maxEntries = maxIdx !== -1 ? parseInt(args[maxIdx + 1]) : 10
+  const backIdx = args.indexOf('--back')
+  const backfillSeconds = backIdx !== -1 ? parseInt(args[backIdx + 1]) : 60
+
+  const params = new URLSearchParams({
+    backfillSeconds: String(backfillSeconds),
+    maxEntries: String(maxEntries),
+  })
+
+  const res = await daemonFetch(`/connections/${id}/stream?${params}`)
+  const data = await res.json()
+
+  if (!res.ok) {
+    console.error(`Error: ${data.error}`)
+    process.exit(1)
+  }
+
+  if (rawMode) {
+    console.log(JSON.stringify(data, null, 2))
+    return
+  }
+
+  const entries = data.entries || []
+  if (entries.length === 0) {
+    console.log('No entries yet. Data may still be flowing in — try again in a few seconds.')
+    return
+  }
+
+  console.log(`${entries.length} entries:\n`)
+  for (const entry of entries) {
+    const time = new Date(entry.ts).toISOString().slice(11, 19)
+    const topic = entry.fields.topic || ''
+    const payload = entry.fields.payload || ''
+
+    console.log(`[${time}]${topic ? ` topic=${topic}` : ''}`)
+
+    // Pretty-print JSON payload with indentation
+    try {
+      const parsed = JSON.parse(payload)
+      const pretty = JSON.stringify(parsed, null, 2)
+      const indented = pretty.split('\n').map((l) => `         ${l}`).join('\n')
+      console.log(indented)
+    } catch {
+      console.log(`         ${payload}`)
+    }
+    console.log()
+  }
+}

package/src/cli/start.ts

@@ -0,0 +1,75 @@
+/**
+ * livetap start — Start the daemon in background or foreground.
+ */
+
+import { resolve } from 'path'
+import { homedir } from 'os'
+import { mkdirSync, writeFileSync, existsSync } from 'fs'
+import { isDaemonRunning, getDaemonUrl } from './daemon-client.js'
+
+const STATE_DIR = resolve(homedir(), '.livetap')
+const LOG_DIR = resolve(STATE_DIR, 'logs')
+const STATE_PATH = resolve(STATE_DIR, 'state.json')
+
+export async function run(args: string[]) {
+  const foreground = args.includes('--foreground') || args.includes('-f')
+  const portFlag = args.indexOf('--port')
+  if (portFlag !== -1 && args[portFlag + 1]) {
+    process.env.LIVETAP_PORT = args[portFlag + 1]
+  }
+
+  if (await isDaemonRunning()) {
+    const res = await fetch(`${getDaemonUrl()}/status`)
+    const status = await res.json()
+    console.log(`livetap is already running on :${status.port} (${status.connections.length} connections)`)
+    return
+  }
+
+  mkdirSync(LOG_DIR, { recursive: true })
+
+  if (foreground) {
+    console.log('Starting livetap in foreground...')
+    // Import and run directly
+    await import('../server/index.js')
+    return
+  }
+
+  // Background: spawn detached
+  const port = process.env.LIVETAP_PORT || '8788'
+  const logFile = Bun.file(resolve(LOG_DIR, 'daemon.log'))
+  const logFd = logFile.writer()
+
+  const proc = Bun.spawn(['bun', resolve(import.meta.dir, '../server/index.ts')], {
+    env: { ...process.env, LIVETAP_PORT: port },
+    stdout: 'ignore',
+    stderr: 'ignore',
+  })
+
+  // Wait for it to be ready
+  const deadline = Date.now() + 15_000
+  let ready = false
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/status`)
+      if (res.ok) {
+        const data = await res.json()
+        writeFileSync(STATE_PATH, JSON.stringify({
+          pid: proc.pid,
+          port: parseInt(port),
+          redisPort: data.redisPort,
+          startedAt: new Date().toISOString(),
+        }, null, 2))
+        ready = true
+        break
+      }
+    } catch { /* not ready */ }
+    await new Promise((r) => setTimeout(r, 500))
+  }
+
+  if (ready) {
+    console.log(`livetap daemon started on :${port} (pid ${proc.pid})`)
+  } else {
+    console.error('Error: daemon failed to start within 15s. Check ~/.livetap/logs/daemon.log')
+    process.exit(1)
+  }
+}

package/src/cli/status.ts

@@ -0,0 +1,45 @@
+/**
+ * livetap status — Show daemon, connections, and watchers.
+ */
+
+import { isDaemonRunning, daemonJson } from './daemon-client.js'
+
+export async function run(args: string[]) {
+  if (!(await isDaemonRunning())) {
+    console.log('livetap is not running. Use "livetap start" to begin.')
+    return
+  }
+
+  const jsonMode = args.includes('--json')
+  const data = await daemonJson('/status')
+
+  if (jsonMode) {
+    console.log(JSON.stringify(data, null, 2))
+    return
+  }
+
+  const uptime = formatUptime(data.uptime)
+  console.log(`livetap daemon running on :${data.port} (uptime ${uptime})`)
+  console.log(`Redis: localhost:${data.redisPort}\n`)
+
+  const conns = data.connections || []
+  if (conns.length === 0) {
+    console.log('No active connections. Use "livetap tap <uri>" to connect.\n')
+  } else {
+    console.log(`Connections (${conns.length}):`)
+    for (const c of conns) {
+      const rate = `${c.msgPerSec} msg/s`
+      const buf = `${c.bufferedCount} buffered`
+      console.log(`  ${c.connectionId}  ${c.type.padEnd(9)} ${c.summary.slice(0, 40).padEnd(42)} ${rate.padStart(10)}  ${buf}`)
+    }
+    console.log()
+  }
+}
+
+function formatUptime(seconds: number): string {
+  if (seconds < 60) return `${Math.round(seconds)}s`
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m`
+  const h = Math.floor(seconds / 3600)
+  const m = Math.round((seconds % 3600) / 60)
+  return `${h}h ${m}m`
+}