npm - aisnitch - Versions diffs - 0.2.3 → 0.2.4 - Mend

aisnitch 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md CHANGED Viewed

@@ -1,128 +1,129 @@
 # AISnitch
+**See what your AI agents are doing. All of them. In real time.**
 [![CI](https://github.com/vava-nessa/AISnitch/actions/workflows/ci.yml/badge.svg)](https://github.com/vava-nessa/AISnitch/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/aisnitch?logo=npm&label=aisnitch)](https://www.npmjs.com/package/aisnitch)
+[![npm](https://img.shields.io/npm/v/@aisnitch/client?logo=npm&label=@aisnitch/client)](https://www.npmjs.com/package/@aisnitch/client)
 [![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](./LICENSE)
-**AISnitch** is a local event bridge for AI coding tools. It captures real-time activity from Claude Code, OpenCode, Gemini CLI, Codex, Goose, Aider, Copilot CLI, OpenClaw (and any CLI via PTY fallback), normalizes everything into one CloudEvents stream, and exposes it over a WebSocket on `ws://127.0.0.1:4820`.
-You connect your own frontend, dashboard, companion app, notification system, or sound engine to that WebSocket, and you get live sentences like:
+AISnitch is a local daemon that captures activity from **every AI coding tool** running on your machine — Claude Code, OpenCode, Gemini CLI, Codex, Goose, Aider, Copilot CLI, OpenClaw, and any CLI via PTY fallback — normalizes everything into a single event stream, and broadcasts it over WebSocket.
-> *"Session #3 — Claude Code is thinking..."*
-> *"#2 ~/projects/myapp — Codex: Refactoring tables — tool call: Edit file"*
-> *"#5 Claude Code edited 4 JS files"*
+- **One stream, all tools** — no more switching between terminals to see what each agent is doing
+- **Zero storage** — pure memory transit, nothing persists to disk, ever
+- **Build anything on top** — dashboards, sound engines, animated companions, Slack bots, menu bar widgets
-No data is stored. No cloud. No logs on disk. Pure live memory-only transit.
+<!-- TODO: Add TUI demo GIF here -->
 ---
 ## Table of Contents
+- [Why AISnitch?](#why-aisnitch)
 - [Quick Start](#quick-start)
 - [Install](#install)
-- [Supported Tools](#supported-tools)
+- [Ecosystem](#ecosystem)
 - [How It Works](#how-it-works)
-- [Event Model Reference](#event-model-reference)
-- [Consumer Integration Guide](#consumer-integration-guide)
-  - [Connect from Node.js / TypeScript](#connect-from-nodejs--typescript)
-  - [Connect from a Browser (React, Vue, Vanilla JS)](#connect-from-a-browser-react-vue-vanilla-js)
-  - [Build Human-Readable Status Lines](#build-human-readable-status-lines)
-  - [Track Sessions](#track-sessions)
-  - [Filter by Tool or Event Type](#filter-by-tool-or-event-type)
-  - [Trigger Sounds or Notifications](#trigger-sounds-or-notifications)
-  - [Build an Animated Mascot / Companion](#build-an-animated-mascot--companion)
-  - [Health Check](#health-check)
+- [Architecture](#architecture)
+- [Supported Tools](#supported-tools)
+- [Event Model](#event-model)
+- [Build on Top of AISnitch](#build-on-top-of-aisnitch)
 - [CLI Reference](#cli-reference)
 - [TUI Keybinds](#tui-keybinds)
-- [Architecture](#architecture)
 - [Config Reference](#config-reference)
 - [Development](#development)
 - [License](#license)
 ---
-## Quick Start
+## Why AISnitch?
+You run Claude Code on your main project, Codex on the API, Aider reviewing a legacy repo. Three agents, three terminals, no shared visibility. You tab-switch constantly. You miss a permission prompt. You don't know which one is idle and which one is burning tokens.
+**AISnitch solves this in one line:**
 ```bash
-pnpm install && pnpm build
+aisnitch start
+```
-# Open the PM2-style dashboard
-node dist/cli/index.js start
+Now every tool's activity flows into one dashboard. You see who's thinking, who's coding, who needs input, and who's hit a rate limit — all at once, in real time.
-# Launch with simulated events (no real AI tool needed)
-node dist/cli/index.js start --mock all
+Want to build your own UI instead? The entire stream is available on `ws://127.0.0.1:4820` — connect with the [Client SDK](#ecosystem) and build dashboards, sound engines, animated companions, or anything else.
-# Exhaustive live logger, no TUI
-node dist/cli/index.js logger
-```
+---
-`start` now always opens the TUI dashboard. If the daemon is offline you still land in the UI, see `Daemon not active`, and can start or stop it from inside the TUI with `d`.
+## Quick Start
-`start --mock all` boots the dashboard, ensures the daemon is active, then streams realistic fake events from Claude Code, OpenCode, and Gemini CLI so you can see the product immediately.
+```bash
+# Install and run
+npm i -g aisnitch
+aisnitch start
+# Try it without any AI tool — simulated events
+aisnitch start --mock all
+```
-If you want the full live payload stream without Ink truncation, use `aisnitch logger`. It attaches to the running daemon and prints one structured field per line, including nested `data.raw.*` paths.
+That's it. The TUI dashboard opens, and you see live activity from every configured AI tool.
-To consume the stream from another terminal:
+To set up tools:
 ```bash
-# Quick test: print raw events
-node -e "
-  const WebSocket = require('ws');
-  const ws = new WebSocket('ws://127.0.0.1:4820');
-  ws.on('message', m => {
-    const e = JSON.parse(m.toString());
-    if (e.type !== 'welcome') console.log(e.type, e['aisnitch.tool'], e.data?.project);
-  });
-"
+aisnitch setup claude-code    # hooks into Claude Code
+aisnitch setup opencode       # hooks into OpenCode
+aisnitch adapters             # check what's enabled
 ```
 ---
 ## Install
-**From source (recommended for development):**
+**npm (recommended):**
 ```bash
-git clone https://github.com/vava-nessa/AISnitch.git
-cd AISnitch
-pnpm install
-pnpm build
-node dist/cli/index.js --help
+npm i -g aisnitch
 ```
-**Global npm install:**
+**Homebrew:**
 ```bash
-npm i -g aisnitch
-aisnitch --help
+brew install aisnitch
 ```
-Global installs now run a silent self-update check every time the dashboard opens. AISnitch auto-detects `npm`, `pnpm`, `bun`, or `brew` from the current install layout and upgrades itself in the background when a newer package version is available.
-**Homebrew:**
+**From source:**
 ```bash
-# Formula ships at Formula/aisnitch.rb — copy into your tap
-brew install aisnitch
+git clone https://github.com/vava-nessa/AISnitch.git
+cd AISnitch
+pnpm install && pnpm build
+node dist/cli/index.js start
 ```
 ---
-## Supported Tools
+## Ecosystem
-| Tool | Strategy | Setup |
-| --- | --- | --- |
-| **Claude Code** | HTTP hooks + JSONL transcript watching + process detection | `aisnitch setup claude-code` |
-| **OpenCode** | Local plugin + process detection | `aisnitch setup opencode` |
-| **Gemini CLI** | Command hooks + `logs.json` watching + process detection | `aisnitch setup gemini-cli` |
-| **Codex** | `codex-tui.log` parsing + process detection | `aisnitch setup codex` |
-| **Goose** | `goosed` API polling + SSE streams + SQLite fallback | `aisnitch setup goose` |
-| **Copilot CLI** | Repo hooks + session-state JSONL watching | `aisnitch setup copilot-cli` |
-| **Aider** | `.aider.chat.history.md` watching + notifications command | `aisnitch setup aider` |
-| **OpenClaw** | Managed hooks + command/memory/session watchers | `aisnitch setup openclaw` |
-| **Any other CLI** | PTY wrapper with output heuristics | `aisnitch wrap <command>` |
+AISnitch ships as two packages with distinct audiences:
+| Package | For | Install |
+|---|---|---|
+| [`aisnitch`](https://www.npmjs.com/package/aisnitch) | **Users** — the daemon, CLI, TUI dashboard, adapters | `npm i -g aisnitch` |
+| [`@aisnitch/client`](https://www.npmjs.com/package/@aisnitch/client) | **Developers** — TypeScript SDK to consume the event stream | `pnpm add @aisnitch/client zod` |
+**You're a user?** Install `aisnitch`, run `aisnitch start`, you're done.
+**You're building something on top?** Install `@aisnitch/client` and connect in 3 lines:
+```typescript
+import { createAISnitchClient, describeEvent } from '@aisnitch/client';
+import WebSocket from 'ws';
+const client = createAISnitchClient({ WebSocketClass: WebSocket as any });
+client.on('event', (e) => console.log(describeEvent(e)));
+// → "claude-code is editing code → src/index.ts [myproject]"
+```
-Adapters are disabled by default. Run `aisnitch setup <tool>` to arm them, then `aisnitch adapters` to verify.
+Auto-reconnect, Zod-validated parsing, session tracking, filters, mascot state mapping — all included. See the full **[Client SDK documentation](./packages/client/README.md)**.
 ---
@@ -155,611 +156,277 @@ Adapters are disabled by default. Run `aisnitch setup <tool>` to arm them, then
    (your consumers)    (built-in)
 ```
-Each adapter captures tool activity using the best available strategy (hooks > file watching > process detection). Events are validated, normalized into CloudEvents, enriched with context (terminal, working directory, PID, multi-instance tracking), then pushed to the EventBus. The WebSocket server broadcasts to all connected clients with per-client backpressure handling.
+Each adapter captures tool activity using the best available strategy — hooks for tools that support them (Claude Code, OpenCode, Gemini CLI), file watching for log-based tools (Codex, Aider), process detection as universal fallback. Events are validated against Zod schemas, normalized into CloudEvents, enriched with context (terminal, working directory, PID, multi-instance tracking), then pushed through an in-memory EventBus. The WebSocket server broadcasts to all connected clients with per-client ring buffers (1,000 events, oldest-first drop).
-**Nothing is stored on disk.** Events exist in memory during transit, then they're gone.
+**Nothing is stored on disk.** Events exist in memory during transit, then they're gone. Privacy-first by design.
 ---
-## Event Model Reference
+## Architecture
+```mermaid
+flowchart LR
+  subgraph Tools["External AI tools"]
+    CC["Claude Code"]
+    OC["OpenCode"]
+    GM["Gemini CLI"]
+    CX["Codex"]
+    GS["Goose"]
+    AD["Aider"]
+    OCL["OpenClaw"]
+    PTY["Generic PTY"]
+  end
+  subgraph AIS["AISnitch runtime"]
+    HTTP["HTTP hook receiver :4821"]
+    UDS["UDS ingest"]
+    REG["Adapter registry"]
+    BUS["Typed EventBus"]
+    WS["WebSocket server :4820"]
+    TUI["Ink TUI"]
+  end
+  subgraph SDK["Consumer ecosystem"]
+    CLIENT["@aisnitch/client SDK"]
+    DASH["Dashboards"]
+    SOUND["Sound engines"]
+    MASCOT["Companions"]
+    BOT["Bots"]
+  end
+  CC --> HTTP
+  OC --> HTTP
+  GM --> HTTP
+  OCL --> HTTP
+  CX --> REG
+  GS --> REG
+  AD --> REG
+  PTY --> UDS
+  HTTP --> BUS
+  UDS --> BUS
+  REG --> BUS
+  BUS --> WS
+  BUS --> TUI
+  WS --> CLIENT
+  CLIENT --> DASH
+  CLIENT --> SOUND
+  CLIENT --> MASCOT
+  CLIENT --> BOT
+```
+---
+## Supported Tools
+| Tool | Strategy | Setup |
+|---|---|---|
+| **Claude Code** | HTTP hooks + JSONL transcript watching + process detection | `aisnitch setup claude-code` |
+| **OpenCode** | Local plugin + process detection | `aisnitch setup opencode` |
+| **Gemini CLI** | Command hooks + `logs.json` watching + process detection | `aisnitch setup gemini-cli` |
+| **Codex** | `codex-tui.log` parsing + process detection | `aisnitch setup codex` |
+| **Goose** | `goosed` API polling + SSE streams + SQLite fallback | `aisnitch setup goose` |
+| **Copilot CLI** | Repo hooks + session-state JSONL watching | `aisnitch setup copilot-cli` |
+| **Aider** | `.aider.chat.history.md` watching + notifications command | `aisnitch setup aider` |
+| **OpenClaw** | Managed hooks + command/memory/session watchers | `aisnitch setup openclaw` |
+| **Any other CLI** | PTY wrapper with output heuristics | `aisnitch wrap <command>` |
+Run `aisnitch setup <tool>` to configure each tool, then `aisnitch adapters` to verify what's active.
+---
+## Event Model
 Every event is a [CloudEvents v1.0](https://cloudevents.io/) envelope with AISnitch extensions:
 ```jsonc
 {
-  // CloudEvents core
   "specversion": "1.0",
   "id": "019713a4-beef-7000-8000-deadbeef0042",  // UUIDv7
   "source": "aisnitch://claude-code/myproject",
-  "type": "agent.coding",                          // one of 12 types
+  "type": "agent.coding",                          // one of 12 types below
   "time": "2026-03-28T14:30:00.000Z",
-  // AISnitch extensions
-  "aisnitch.tool": "claude-code",       // which AI tool
-  "aisnitch.sessionid": "claude-code:myproject:p12345",  // session identity
-  "aisnitch.seqnum": 42,               // sequence number in this session
+  "aisnitch.tool": "claude-code",
+  "aisnitch.sessionid": "claude-code:myproject:p12345",
+  "aisnitch.seqnum": 42,
-  // Normalized payload
   "data": {
-    "state": "agent.coding",            // mirrors type
-    "project": "myproject",             // project name
+    "state": "agent.coding",
+    "project": "myproject",
     "projectPath": "/home/user/myproject",
-    "activeFile": "src/index.ts",       // file being edited (if relevant)
-    "toolName": "Edit",                 // tool being used (if relevant)
-    "toolInput": {                      // tool arguments (if relevant)
-      "filePath": "src/index.ts"
-    },
-    "model": "claude-sonnet-4-5-20250514",  // model in use (if known)
-    "tokensUsed": 1500,                // token count (if known)
-    "terminal": "iTerm2",              // detected terminal
-    "cwd": "/home/user/myproject",     // working directory
-    "pid": 12345,                      // process ID
-    "instanceIndex": 1,                // instance number (multi-instance)
-    "instanceTotal": 3,                // total instances running
-    // Error fields (only on agent.error)
-    "errorMessage": "Rate limit exceeded",
-    "errorType": "rate_limit",         // rate_limit | context_overflow | tool_failure | api_error
-    // Raw source payload (adapter-specific, for advanced consumers)
-    "raw": { /* original hook/log payload as-is */ }
+    "activeFile": "src/index.ts",
+    "toolName": "Edit",
+    "toolInput": { "filePath": "src/index.ts" },
+    "model": "claude-sonnet-4-5-20250514",
+    "tokensUsed": 1500,
+    "terminal": "iTerm2",
+    "cwd": "/home/user/myproject",
+    "pid": 12345,
+    "instanceIndex": 1,
+    "instanceTotal": 3,
+    "errorMessage": "Rate limit exceeded",       // only on agent.error
+    "errorType": "rate_limit",                    // only on agent.error
+    "raw": { /* original adapter payload */ }
   }
 }
 ```
 ### The 12 Event Types
-| Type | Meaning | When it fires |
-| --- | --- | --- |
-| `session.start` | A tool session began | Tool launched, first hook received |
-| `session.end` | Session closed | Tool exited, process disappeared |
-| `task.start` | User submitted a prompt/task | New user message, task created |
-| `task.complete` | Task finished | Response complete, stop signal |
-| `agent.thinking` | Model is reasoning | Thinking block, internal reflection |
-| `agent.streaming` | Model is generating output | Text streaming, response in progress |
-| `agent.coding` | Model edited files | Write, Edit, MultiEdit tool calls |
-| `agent.tool_call` | Model used a non-edit tool | Search, Bash, Grep, web search, etc. |
-| `agent.asking_user` | Waiting for human input | Permission request, confirmation prompt |
-| `agent.idle` | No activity (timeout) | 120s of silence (configurable) |
-| `agent.error` | Something went wrong | Rate limit, API error, tool failure |
-| `agent.compact` | Context compaction | Memory cleanup, history pruning |
-### Recognized Tool Names
-`claude-code`, `opencode`, `gemini-cli`, `codex`, `goose`, `copilot-cli`, `cursor`, `aider`, `amp`, `cline`, `continue`, `windsurf`, `qwen-code`, `openclaw`, `openhands`, `kilo`, `unknown`
+| Type | What it means |
+|---|---|
+| `session.start` | A tool session began |
+| `session.end` | Session closed |
+| `task.start` | User submitted a prompt |
+| `task.complete` | Task finished |
+| `agent.thinking` | Model is reasoning |
+| `agent.streaming` | Model is generating output |
+| `agent.coding` | Model is editing files |
+| `agent.tool_call` | Model is using a tool (Bash, Grep, etc.) |
+| `agent.asking_user` | Waiting for human input |
+| `agent.idle` | No activity (120s timeout, configurable) |
+| `agent.error` | Something went wrong (rate limit, API error, tool failure) |
+| `agent.compact` | Context compaction / memory cleanup |
 ---
-## Consumer Integration Guide
+## Build on Top of AISnitch
-This is the main purpose of AISnitch: you connect to the WebSocket and exploit the event stream however you want. Below are complete examples for every common use case.
+The whole point of AISnitch is to be a platform. Here are 5 things you can build with the [`@aisnitch/client`](./packages/client/README.md) SDK:
-### Connect from Node.js / TypeScript
+### Live Dashboard
-```ts
+```typescript
+import { createAISnitchClient, describeEvent } from '@aisnitch/client';
 import WebSocket from 'ws';
-// 📖 Default port is 4820, configurable via ~/.aisnitch/config.json
-const ws = new WebSocket('ws://127.0.0.1:4820');
-ws.on('open', () => {
-  console.log('Connected to AISnitch');
-});
-ws.on('message', (buffer) => {
-  const event = JSON.parse(buffer.toString('utf8'));
+const client = createAISnitchClient({ WebSocketClass: WebSocket as any });
-  // 📖 First message is always a welcome payload — skip it
-  if (event.type === 'welcome') {
-    console.log('AISnitch version:', event.version);
-    console.log('Active tools:', event.activeTools);
-    return;
-  }
-  // 📖 Every other message is a normalized AISnitch event
-  console.log({
-    type: event.type,                    // "agent.coding"
-    tool: event['aisnitch.tool'],        // "claude-code"
-    session: event['aisnitch.sessionid'],// "claude-code:myproject:p12345"
-    seq: event['aisnitch.seqnum'],       // 42
-    project: event.data?.project,        // "myproject"
-    file: event.data?.activeFile,        // "src/index.ts"
-    model: event.data?.model,            // "claude-sonnet-4-5-20250514"
-  });
+client.on('connected', (w) => {
+  console.log(`Connected to AISnitch v${w.version}`);
+  console.log(`Active tools: ${w.activeTools.join(', ')}`);
 });
-ws.on('close', () => {
-  console.log('Disconnected — AISnitch stopped or restarted');
-  // 📖 Implement reconnect logic here if needed
+client.on('event', (e) => {
+  const line = describeEvent(e);
+  console.log(`[${e['aisnitch.tool']}] ${line}`);
 });
-ws.on('error', (err) => {
-  console.error('WebSocket error:', err.message);
-});
+// Track all active sessions
+setInterval(() => {
+  const sessions = client.sessions?.getAll() ?? [];
+  console.log(`\n--- ${sessions.length} active session(s) ---`);
+  for (const s of sessions) {
+    console.log(`  ${s.tool} → ${s.lastActivity} (${s.eventCount} events)`);
+  }
+}, 5000);
 ```
-### Connect from a Browser (React, Vue, Vanilla JS)
-The WebSocket is plain `ws://` on localhost — browsers can connect directly with the native `WebSocket` API. No library needed.
+### Sound Notifications (PeonPing-style)
-**Vanilla JS:**
+```typescript
+import { createAISnitchClient, filters } from '@aisnitch/client';
-```js
-// 📖 Connect to AISnitch from any browser page on the same machine
-const ws = new WebSocket('ws://127.0.0.1:4820');
+const client = createAISnitchClient({ WebSocketClass: WebSocket as any });
-ws.onmessage = (msg) => {
-  const event = JSON.parse(msg.data);
-  if (event.type === 'welcome') return;
-  // Do anything: update DOM, play sound, trigger animation...
-  document.getElementById('status').textContent =
-    `${event['aisnitch.tool']} — ${event.type}`;
+const SOUNDS: Record<string, string> = {
+  'session.start':     'boot.mp3',
+  'task.complete':     'success.mp3',
+  'agent.asking_user': 'alert.mp3',
+  'agent.error':       'error.mp3',
+  'agent.coding':      'keyboard.mp3',
 };
-```
-**React hook:**
-```tsx
-import { useEffect, useState, useCallback, useRef } from 'react';
-interface AISnitchEvent {
-  type: string;
-  time: string;
-  'aisnitch.tool': string;
-  'aisnitch.sessionid': string;
-  'aisnitch.seqnum': number;
-  data: {
-    state: string;
-    project?: string;
-    activeFile?: string;
-    toolName?: string;
-    toolInput?: { filePath?: string; command?: string };
-    model?: string;
-    tokensUsed?: number;
-    errorMessage?: string;
-    errorType?: string;
-    terminal?: string;
-    cwd?: string;
-    pid?: number;
-    instanceIndex?: number;
-    instanceTotal?: number;
-  };
-}
-// 📖 Drop-in React hook — auto-reconnects every 3s if AISnitch restarts
-export function useAISnitch(url = 'ws://127.0.0.1:4820') {
-  const [events, setEvents] = useState<AISnitchEvent[]>([]);
-  const [connected, setConnected] = useState(false);
-  const [latestEvent, setLatestEvent] = useState<AISnitchEvent | null>(null);
-  const wsRef = useRef<WebSocket | null>(null);
-  const connect = useCallback(() => {
-    const ws = new WebSocket(url);
-    wsRef.current = ws;
-    ws.onopen = () => setConnected(true);
-    ws.onclose = () => {
-      setConnected(false);
-      setTimeout(connect, 3000); // 📖 Reconnect after 3s
-    };
-    ws.onmessage = (msg) => {
-      const event = JSON.parse(msg.data) as AISnitchEvent;
-      if (event.type === 'welcome') return;
-      setLatestEvent(event);
-      setEvents((prev) => [...prev.slice(-499), event]); // 📖 Keep last 500
-    };
-    ws.onerror = () => ws.close();
-  }, [url]);
-  useEffect(() => {
-    connect();
-    return () => wsRef.current?.close();
-  }, [connect]);
-  const clear = useCallback(() => {
-    setEvents([]);
-    setLatestEvent(null);
-  }, []);
-  return { events, latestEvent, connected, clear };
-}
+client.on('event', (e) => {
+  const sound = SOUNDS[e.type];
+  if (sound) playSound(`./sounds/${sound}`);
+});
 ```
-**Usage in a component:**
-```tsx
-function AIActivityPanel() {
-  const { events, latestEvent, connected } = useAISnitch();
-  return (
-    <div>
-      <span>{connected ? '🟢 Live' : '🔴 Disconnected'}</span>
-      {latestEvent && (
-        <p>
-          {latestEvent['aisnitch.tool']} — {latestEvent.type}
-          {latestEvent.data.project && ` on ${latestEvent.data.project}`}
-        </p>
-      )}
-      <ul>
-        {events.map((e, i) => (
-          <li key={i}>
-            [{e['aisnitch.tool']}] {e.type}
-            {e.data.activeFile && ` → ${e.data.activeFile}`}
-          </li>
-        ))}
-      </ul>
-    </div>
-  );
-}
-```
+### Animated Mascot / Companion
-**Vue 3 composable:**
-```ts
-import { ref, onMounted, onUnmounted } from 'vue';
-export function useAISnitch(url = 'ws://127.0.0.1:4820') {
-  const events = ref<any[]>([]);
-  const connected = ref(false);
-  const latestEvent = ref<any>(null);
-  let ws: WebSocket | null = null;
-  let reconnectTimer: ReturnType<typeof setTimeout>;
-  function connect() {
-    ws = new WebSocket(url);
-    ws.onopen = () => (connected.value = true);
-    ws.onclose = () => {
-      connected.value = false;
-      reconnectTimer = setTimeout(connect, 3000);
-    };
-    ws.onmessage = (msg) => {
-      const event = JSON.parse(msg.data);
-      if (event.type === 'welcome') return;
-      latestEvent.value = event;
-      events.value = [...events.value.slice(-499), event];
-    };
-    ws.onerror = () => ws?.close();
-  }
+```typescript
+import { createAISnitchClient, eventToMascotState } from '@aisnitch/client';
-  onMounted(connect);
-  onUnmounted(() => {
-    clearTimeout(reconnectTimer);
-    ws?.close();
-  });
+const client = createAISnitchClient();
-  return { events, latestEvent, connected };
-}
+client.on('event', (e) => {
+  const state = eventToMascotState(e);
+  // state.mood    → 'thinking' | 'working' | 'celebrating' | 'panicking' | ...
+  // state.animation → 'ponder' | 'type' | 'dance' | 'shake' | ...
+  // state.color   → '#a855f7' (hex)
+  // state.label   → 'Thinking...'
+  // state.detail  → 'src/index.ts' (optional)
+  updateMySprite(state);
+});
 ```
-### Build Human-Readable Status Lines
-This is the core use case: transform raw events into sentences like *"Claude Code is editing src/index.ts"*.
-```ts
-// 📖 Maps event type + data into a short human-readable description
-function describeEvent(event: AISnitchEvent): string {
-  const tool = event['aisnitch.tool'];
-  const d = event.data;
-  const file = d.activeFile ? ` → ${d.activeFile}` : '';
-  const project = d.project ? ` [${d.project}]` : '';
-  switch (event.type) {
-    case 'session.start':
-      return `${tool} started a new session${project}`;
-    case 'session.end':
-      return `${tool} session ended${project}`;
-    case 'task.start':
-      return `${tool} received a new prompt${project}`;
-    case 'task.complete':
-      return `${tool} finished the task${project}` +
-        (d.duration ? ` (${Math.round(d.duration / 1000)}s)` : '');
-    case 'agent.thinking':
-      return `${tool} is thinking...${project}`;
+### Slack / Discord Bot
-    case 'agent.streaming':
-      return `${tool} is generating a response${project}`;
-    case 'agent.coding':
-      return `${tool} is editing code${file}${project}`;
-    case 'agent.tool_call':
-      return `${tool} is using ${d.toolName ?? 'a tool'}` +
-        (d.toolInput?.command ? `: ${d.toolInput.command}` : file) +
-        project;
-    case 'agent.asking_user':
-      return `${tool} needs your input${project}`;
-    case 'agent.idle':
-      return `${tool} is idle${project}`;
-    case 'agent.error':
-      return `${tool} error: ${d.errorMessage ?? d.errorType ?? 'unknown'}${project}`;
+```typescript
+import { createAISnitchClient, filters, formatStatusLine } from '@aisnitch/client';
+import WebSocket from 'ws';
-    case 'agent.compact':
-      return `${tool} is compacting context${project}`;
+const client = createAISnitchClient({ WebSocketClass: WebSocket as any });
-    default:
-      return `${tool}: ${event.type}`;
+// Only notify on events that need attention
+client.on('event', (e) => {
+  if (filters.needsAttention(e)) {
+    postToSlack(`⚠️ ${formatStatusLine(e)}`);
   }
-}
-// Example output:
-// "claude-code started a new session [myproject]"
-// "claude-code is editing code → src/index.ts [myproject]"
-// "codex is using Bash: npm test [api-server]"
-// "gemini-cli needs your input"
-// "claude-code error: Rate limit exceeded [myproject]"
-```
-**Full status line with session number:**
-```ts
-// 📖 Tracks session indices and builds numbered status lines
-const sessionIndex = new Map<string, number>();
-let sessionCounter = 0;
-function getSessionNumber(sessionId: string): number {
-  if (!sessionIndex.has(sessionId)) {
-    sessionIndex.set(sessionId, ++sessionCounter);
+  if (e.type === 'task.complete') {
+    postToSlack(`✅ ${formatStatusLine(e)}`);
   }
-  return sessionIndex.get(sessionId)!;
-}
-function formatStatusLine(event: AISnitchEvent): string {
-  const num = getSessionNumber(event['aisnitch.sessionid']);
-  const desc = describeEvent(event);
-  const cwd = event.data.cwd ?? '';
-  return `#${num} ${cwd} — ${desc}`;
-}
-// Output:
-// "#1 /home/user/myproject — claude-code is thinking..."
-// "#2 /home/user/api — codex is editing code → src/db.ts"
-// "#1 /home/user/myproject — claude-code finished the task (12s)"
+});
 ```
-### Track Sessions
-Events carry `aisnitch.sessionid` for grouping. A session represents one tool instance working on one project.
-```ts
-interface SessionState {
-  tool: string;
-  sessionId: string;
-  project?: string;
-  cwd?: string;
-  lastEvent: AISnitchEvent;
-  lastActivity: string;  // human-readable
-  eventCount: number;
-  startedAt: string;
-}
+### Menu Bar Widget (Electron / Tauri)
-const sessions = new Map<string, SessionState>();
+```typescript
+import { createAISnitchClient, formatStatusLine } from '@aisnitch/client';
-function updateSession(event: AISnitchEvent): void {
-  const sid = event['aisnitch.sessionid'];
+const client = createAISnitchClient();
+let sessionCounter = 0;
+const sessionMap = new Map<string, number>();
-  if (event.type === 'session.end') {
-    sessions.delete(sid);
-    return;
+client.on('event', (e) => {
+  if (!sessionMap.has(e['aisnitch.sessionid'])) {
+    sessionMap.set(e['aisnitch.sessionid'], ++sessionCounter);
   }
+  const num = sessionMap.get(e['aisnitch.sessionid'])!;
-  const existing = sessions.get(sid);
-  sessions.set(sid, {
-    tool: event['aisnitch.tool'],
-    sessionId: sid,
-    project: event.data.project ?? existing?.project,
-    cwd: event.data.cwd ?? existing?.cwd,
-    lastEvent: event,
-    lastActivity: describeEvent(event),
-    eventCount: (existing?.eventCount ?? 0) + 1,
-    startedAt: existing?.startedAt ?? event.time,
-  });
-}
-// 📖 Call updateSession() on every event, then read sessions Map for current state
-// sessions.values() gives you all active sessions across all tools
-```
-### Filter by Tool or Event Type
-Filtering is client-side. The server broadcasts everything — you pick what you need.
-```ts
-// 📖 Filter examples — apply to your ws.onmessage handler
-// Only Claude Code events
-const isClaudeCode = (e: AISnitchEvent) => e['aisnitch.tool'] === 'claude-code';
-// Only coding activity (edits, tool calls)
-const isCodingActivity = (e: AISnitchEvent) =>
-  e.type === 'agent.coding' || e.type === 'agent.tool_call';
-// Only errors
-const isError = (e: AISnitchEvent) => e.type === 'agent.error';
-// Only rate limits specifically
-const isRateLimit = (e: AISnitchEvent) =>
-  e.type === 'agent.error' && e.data.errorType === 'rate_limit';
-// Only events for a specific project
-const isMyProject = (e: AISnitchEvent) => e.data.project === 'myproject';
-// Events that need user attention
-const needsAttention = (e: AISnitchEvent) =>
-  e.type === 'agent.asking_user' || e.type === 'agent.error';
-// Combine filters
-ws.onmessage = (msg) => {
-  const event = JSON.parse(msg.data);
-  if (event.type === 'welcome') return;
-  if (isClaudeCode(event) && isCodingActivity(event)) {
-    // Only Claude Code writing code
-    updateUI(event);
-  }
-};
+  // Update your menu bar / tray icon
+  tray.setTitle(formatStatusLine(e, num));
+  tray.setToolTip(`${client.sessions?.count ?? 0} active sessions`);
+});
 ```
-### Trigger Sounds or Notifications
-```ts
-// 📖 Map event types to sounds — perfect for a companion/pet app
-const SOUND_MAP: Record<string, string> = {
-  'session.start':    '/sounds/boot.mp3',
-  'session.end':      '/sounds/shutdown.mp3',
-  'task.start':       '/sounds/ping.mp3',
-  'task.complete':    '/sounds/success.mp3',
-  'agent.thinking':   '/sounds/thinking-loop.mp3',  // loop this one
-  'agent.coding':     '/sounds/keyboard.mp3',
-  'agent.tool_call':  '/sounds/tool.mp3',
-  'agent.asking_user':'/sounds/alert.mp3',
-  'agent.error':      '/sounds/error.mp3',
-  'agent.idle':       '/sounds/idle.mp3',
-};
-function playEventSound(event: AISnitchEvent): void {
-  const soundFile = SOUND_MAP[event.type];
-  if (!soundFile) return;
-  // Browser: use Web Audio API
-  const audio = new Audio(soundFile);
-  audio.play();
-}
+For complete API docs, React/Vue hooks, filters, TypeScript integration, and more examples, see the **[Client SDK README](./packages/client/README.md)**.
-// 📖 Desktop notification for important events
-function notifyIfNeeded(event: AISnitchEvent): void {
-  if (event.type === 'agent.asking_user') {
-    new Notification(`${event['aisnitch.tool']} needs input`, {
-      body: event.data.project
-        ? `Project: ${event.data.project}`
-        : 'Waiting for your response...',
-    });
-  }
+<details>
+<summary>Raw WebSocket (without SDK)</summary>
-  if (event.type === 'agent.error') {
-    new Notification(`${event['aisnitch.tool']} error`, {
-      body: event.data.errorMessage ?? 'Something went wrong',
-    });
-  }
+If you don't want the SDK, you can connect directly:
-  if (event.type === 'task.complete') {
-    new Notification(`${event['aisnitch.tool']} done!`, {
-      body: event.data.project
-        ? `Task completed on ${event.data.project}`
-        : 'Task completed',
-    });
-  }
-}
+```bash
+# One-liner to see raw events
+node -e "
+  const WebSocket = require('ws');
+  const ws = new WebSocket('ws://127.0.0.1:4820');
+  ws.on('message', m => {
+    const e = JSON.parse(m.toString());
+    if (e.type !== 'welcome') console.log(e.type, e['aisnitch.tool'], e.data?.project);
+  });
+"
 ```
-### Build an Animated Mascot / Companion
+The first message is always a `welcome` payload with version, active tools, and uptime. Every subsequent message is a CloudEvents event as described above.
-```ts
-// 📖 Map event states to mascot moods — for animated desktop pets,
-// menu bar companions, or overlay widgets
-interface MascotState {
-  mood: 'idle' | 'thinking' | 'working' | 'waiting' | 'celebrating' | 'panicking';
-  animation: string;
-  color: string;
-  label: string;
-  detail?: string;
-}
-function eventToMascotState(event: AISnitchEvent): MascotState {
-  const d = event.data;
-  switch (event.type) {
-    case 'agent.thinking':
-      return {
-        mood: 'thinking',
-        animation: 'orbit',
-        color: '#f59e0b',
-        label: 'Thinking...',
-        detail: d.model,
-      };
-    case 'agent.coding':
-      return {
-        mood: 'working',
-        animation: 'typing',
-        color: '#3b82f6',
-        label: 'Coding',
-        detail: d.activeFile,
-      };
-    case 'agent.tool_call':
-      return {
-        mood: 'working',
-        animation: 'inspect',
-        color: '#14b8a6',
-        label: `Using ${d.toolName ?? 'tool'}`,
-        detail: d.toolInput?.command ?? d.toolInput?.filePath,
-      };
-    case 'agent.streaming':
-      return {
-        mood: 'working',
-        animation: 'pulse',
-        color: '#8b5cf6',
-        label: 'Generating...',
-      };
-    case 'agent.asking_user':
-      return {
-        mood: 'waiting',
-        animation: 'wave',
-        color: '#ec4899',
-        label: 'Needs you!',
-      };
-    case 'agent.error':
-      return {
-        mood: 'panicking',
-        animation: 'shake',
-        color: '#ef4444',
-        label: d.errorType === 'rate_limit' ? 'Rate limited!' : 'Error!',
-        detail: d.errorMessage,
-      };
-    case 'task.complete':
-      return {
-        mood: 'celebrating',
-        animation: 'celebrate',
-        color: '#22c55e',
-        label: 'Done!',
-      };
-    default:
-      return {
-        mood: 'idle',
-        animation: 'breathe',
-        color: '#94a3b8',
-        label: 'Idle',
-      };
-  }
-}
-// 📖 Plug this into your rendering loop:
-// ws.onmessage → eventToMascotState(event) → update sprite/CSS/canvas
-```
+</details>
 ### Health Check
-AISnitch exposes a health endpoint on the HTTP port:
 ```bash
 curl http://127.0.0.1:4821/health
 ```
@@ -774,8 +441,6 @@ curl http://127.0.0.1:4821/health
 }
 ```
-Useful for monitoring if the bridge is alive before connecting your consumer.
 ---
 ## CLI Reference
@@ -790,9 +455,12 @@ aisnitch start --view full-data        # expanded JSON inspector
 # Background daemon
 aisnitch start --daemon
 aisnitch status                        # check if daemon is running
-aisnitch attach                        # open the same dashboard and attach if active
+aisnitch attach                        # open TUI attached to running daemon
 aisnitch stop                          # kill daemon
+# Raw event logger (no TUI, full payload)
+aisnitch logger
 # Tool setup (run once per tool)
 aisnitch setup claude-code
 aisnitch setup opencode
@@ -807,11 +475,11 @@ aisnitch setup claude-code --revert    # undo setup
 # Check enabled adapters
 aisnitch adapters
-# Demo mode
+# Demo mode (simulated events)
 aisnitch mock claude-code --speed 2 --duration 20
-aisnitch start --mock all --mock-duration 20
+aisnitch start --mock all
-# PTY wrapper fallback (any unsupported CLI)
+# PTY wrapper (any unsupported CLI)
 aisnitch wrap aider --model sonnet
 aisnitch wrap goose session
 ```
@@ -821,9 +489,9 @@ aisnitch wrap goose session
 ## TUI Keybinds
 | Key | Action |
-| --- | --- |
+|---|---|
 | `q` / `Ctrl+C` | Quit |
-| `d` | Start / stop the daemon from the dashboard |
+| `d` | Start / stop the daemon |
 | `r` | Refresh daemon status |
 | `v` | Toggle full-data JSON inspector |
 | `f` | Tool filter picker |
@@ -834,70 +502,25 @@ aisnitch wrap goose session
 | `c` | Clear event buffer |
 | `?` | Help overlay |
 | `Tab` | Switch panel focus |
-| `↑↓` / `jk` | Navigate rows / inspector |
+| `↑↓` / `jk` | Navigate rows |
 | `[` `]` | Page inspector up / down |
 ---
-## Architecture
-```mermaid
-flowchart LR
-  subgraph Tools["External AI tools"]
-    CC["Claude Code"]
-    OC["OpenCode"]
-    GM["Gemini CLI"]
-    CX["Codex"]
-    GS["Goose"]
-    AD["Aider"]
-    OCL["OpenClaw"]
-    PTY["Generic PTY"]
-  end
-  subgraph AIS["AISnitch runtime"]
-    HTTP["HTTP hook receiver :4821"]
-    UDS["UDS ingest"]
-    REG["Adapter registry"]
-    BUS["Typed EventBus"]
-    WS["WebSocket server :4820"]
-    TUI["Ink TUI"]
-  end
-  CC --> HTTP
-  OC --> HTTP
-  GM --> HTTP
-  OCL --> HTTP
-  CX --> REG
-  GS --> REG
-  AD --> REG
-  PTY --> UDS
-  HTTP --> BUS
-  UDS --> BUS
-  REG --> BUS
-  BUS --> WS
-  BUS --> TUI
-```
----
 ## Config Reference
-AISnitch state lives under `~/.aisnitch/` by default (override with `AISNITCH_HOME` env var).
+AISnitch state lives under `~/.aisnitch/` (override with `AISNITCH_HOME`).
 | Path | Purpose |
-| --- | --- |
-| `~/.aisnitch/config.json` | User configuration |
-| `~/.aisnitch/aisnitch.pid` | Daemon PID file |
-| `~/.aisnitch/daemon-state.json` | Daemon connection info |
-| `~/.aisnitch/daemon.log` | Daemon output log (5MB max) |
-| `~/.aisnitch/aisnitch.sock` | Unix domain socket (daemon IPC) |
-| `~/.aisnitch/auto-update.json` | Silent self-update state |
-| `~/.aisnitch/auto-update.log` | Last silent self-update worker log |
-The dashboard surfaces the active WebSocket URL directly in the header so it is easy to copy into another consumer.
+|---|---|
+| `config.json` | User configuration |
+| `aisnitch.pid` | Daemon PID file |
+| `daemon-state.json` | Daemon connection info |
+| `daemon.log` | Daemon output log (5 MB max) |
+| `aisnitch.sock` | Unix domain socket (IPC) |
 | Port | Purpose |
-| --- | --- |
+|---|---|
 | `4820` | WebSocket stream (consumers connect here) |
 | `4821` | HTTP hook receiver + `/health` endpoint |
@@ -907,20 +530,40 @@ The dashboard surfaces the active WebSocket URL directly in the header so it is
 ```bash
 pnpm install
-pnpm build        # ESM + CJS + .d.ts
-pnpm lint         # ESLint
-pnpm typecheck    # tsc --noEmit
-pnpm test         # Vitest (142 tests)
+pnpm build              # ESM + CJS + .d.ts (main + client SDK)
+pnpm lint               # ESLint
+pnpm typecheck          # tsc --noEmit
+pnpm test               # Vitest (156 tests)
 pnpm test:coverage
-pnpm test:e2e     # requires opencode installed
+pnpm test:e2e           # requires opencode installed
+# Client SDK only
+pnpm --filter @aisnitch/client build
+pnpm --filter @aisnitch/client test   # 48 tests
+```
+Project structure:
+```
+aisnitch/                  # main package — daemon, CLI, TUI, adapters
+├── src/
+│   ├── adapters/          # 13 adapter implementations
+│   ├── cli/               # commander commands
+│   ├── core/              # events, pipeline, config
+│   └── tui/               # Ink dashboard
+├── packages/
+│   └── client/            # @aisnitch/client SDK
+│       └── src/           # types, client, sessions, filters, helpers
+├── docs/                  # technical documentation
+└── tasks/                 # kanban task board
 ```
-Detailed docs: [`docs/index.md`](./docs/index.md) | [`tasks/tasks.md`](./tasks/tasks.md)
+Docs: [`docs/index.md`](./docs/index.md) | Tasks: [`tasks/tasks.md`](./tasks/tasks.md)
-Contributing: [`CONTRIBUTING.md`](./CONTRIBUTING.md) | [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) | [`AGENTS.md`](./AGENTS.md)
+Contributing: [`CONTRIBUTING.md`](./CONTRIBUTING.md) | [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)
 ---
 ## License
-Apache-2.0, © Vanessa Depraute / vava-nessa.
+Apache-2.0, © [Vanessa Depraute / vava-nessa](https://github.com/vava-nessa).