aisnitch 0.2.21 โ†’ 0.2.23

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
  1. package/README.md +434 -398
  2. package/dist/cli/index.cjs +1004 -50
  3. package/dist/cli/index.cjs.map +1 -1
  4. package/dist/cli/index.js +988 -29
  5. package/dist/cli/index.js.map +1 -1
  6. package/dist/index.cjs +104 -10
  7. package/dist/index.cjs.map +1 -1
  8. package/dist/index.d.cts +9 -0
  9. package/dist/index.d.ts +9 -0
  10. package/dist/index.js +104 -10
  11. package/dist/index.js.map +1 -1
  12. package/package.json +3 -2
package/README.md CHANGED
@@ -1,300 +1,253 @@
1
- # AISnitch
1
+ # ๐Ÿค– AISnitch
2
2
 
3
- **See what your AI agents are doing. All of them. In real time.**
3
+ > **See everything your AI coding tools are doing โ€” in one place, in real time.**
4
4
 
5
- [![CI](https://github.com/vava-nessa/AISnitch/actions/workflows/ci.yml/badge.svg)](https://github.com/vava-nessa/AISnitch/actions/workflows/ci.yml)
6
- [![npm](https://img.shields.io/npm/v/aisnitch?logo=npm&label=aisnitch)](https://www.npmjs.com/package/aisnitch)
7
- [![npm](https://img.shields.io/npm/v/@aisnitch/client?logo=npm&label=@aisnitch/client)](https://www.npmjs.com/package/@aisnitch/client)
8
- [![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
9
- [![License: Apache-2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](./LICENSE)
10
-
11
- 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.
12
-
13
- - **One stream, all tools** โ€” no more switching between terminals to see what each agent is doing
14
- - **Zero storage** โ€” pure memory transit, nothing persists to disk, ever
15
- - **Build anything on top** โ€” dashboards, sound engines, animated companions, Slack bots, menu bar widgets
5
+ ```
6
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
7
+ โ”‚ โ”‚
8
+ โ”‚ Claude Code OpenCode Gemini CLI Aider Codex โ”‚
9
+ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚
10
+ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚
11
+ โ”‚ โ”‚ โ”‚
12
+ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚
13
+ โ”‚ โ”‚ AISnitch โ”‚ โ”‚
14
+ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚
15
+ โ”‚ โ”‚ โ”‚ TUI โ”‚ โ”‚ โ† Dashboard (real-time) โ”‚
16
+ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚
17
+ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚
18
+ โ”‚ โ”‚ โ”‚ Webhook โ”‚ โ”‚ โ† Build anything โ”‚
19
+ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚
20
+ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚
21
+ โ”‚ โ”‚
22
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
23
+ ```
16
24
 
17
- <!-- TODO: Add TUI demo GIF here -->
25
+ **One command. Every agent. Every project. Live.**
18
26
 
19
27
  ---
20
28
 
21
- ## Table of Contents
22
-
23
- - [Why AISnitch?](#why-aisnitch)
24
- - [Quick Start](#quick-start)
25
- - [Install](#install)
26
- - [Ecosystem](#ecosystem)
27
- - [How It Works](#how-it-works)
28
- - [Architecture](#architecture)
29
- - [Supported Tools](#supported-tools)
30
- - [Event Model](#event-model)
31
- - [Build on Top of AISnitch](#build-on-top-of-aisnitch)
32
- - [CLI Reference](#cli-reference)
33
- - [TUI Keybinds](#tui-keybinds)
34
- - [Config Reference](#config-reference)
35
- - [Development](#development)
36
- - [License](#license)
29
+ ## โญ Why AISnitch?
37
30
 
38
- ---
31
+ You have **multiple AI coding assistants** running at the same time:
39
32
 
40
- ## Why AISnitch?
33
+ ```
34
+ ๐Ÿ”ต Claude Code โ†’ working on your main project
35
+ ๐ŸŸก OpenCode โ†’ reviewing a PR
36
+ ๐ŸŸฃ Codex โ†’ writing tests
37
+ ๐ŸŸข Aider โ†’ refactoring legacy code
38
+ ```
41
39
 
42
- 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.
40
+ **The problem?** You have 4 terminals open, tabbing between them, missing things, context-switching like crazy.
43
41
 
44
- **AISnitch solves this in one line:**
42
+ **The solution?**
45
43
 
46
44
  ```bash
47
45
  aisnitch start
48
46
  ```
49
47
 
50
- 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.
48
+ Now you see **everything in one dashboard**:
51
49
 
52
- 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.
50
+ ```
51
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
52
+ โ”‚ ๐Ÿค– AISnitch [q] quit [?] help โ”‚
53
+ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
54
+ โ”‚ ๐Ÿ”ต Claude Code โ— thinking... โ”‚ ๐Ÿ“ src/app.ts โ”‚
55
+ โ”‚ ๐ŸŸก OpenCode โœ“ idle โ”‚ ๐Ÿ“ /projects/api โ”‚
56
+ โ”‚ ๐ŸŸฃ Codex โณ coding... โ”‚ ๐Ÿ“„ tests/users.test.ts โ”‚
57
+ โ”‚ ๐ŸŸข Aider โ— task: "cleanup" โ”‚ ๐Ÿ“ /legacy/db โ”‚
58
+ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
59
+ โ”‚ Events (42) [Space] freeze [c] clear โ”‚
60
+ โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ โ”‚
61
+ โ”‚ ๐Ÿ”ต 14:30:01 agent.thinking "Implementing user auth..." โ”‚
62
+ โ”‚ ๐Ÿ”ต 14:29:58 agent.coding Edit โ†’ src/auth/login.ts โ”‚
63
+ โ”‚ ๐ŸŸก 14:29:55 agent.idle waiting for prompt... โ”‚
64
+ โ”‚ ๐ŸŸฃ 14:29:52 tool_call Bash โ†’ git status โ”‚
65
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
66
+ ```
53
67
 
54
68
  ---
55
69
 
56
- ## Quick Start
70
+ ## ๐Ÿš€ Quick Start (30 seconds)
71
+
72
+ ### 1. Install
57
73
 
58
74
  ```bash
59
- # Install and run
75
+ # npm (recommended)
60
76
  npm i -g aisnitch
61
- aisnitch start
62
77
 
63
- # Try it without any AI tool โ€” simulated events
64
- aisnitch start --mock all
78
+ # or Homebrew
79
+ brew install aisnitch
65
80
  ```
66
81
 
67
- That's it. The TUI dashboard opens, and you see live activity from every configured AI tool.
68
-
69
- To set up tools:
82
+ ### 2. Run
70
83
 
71
84
  ```bash
72
- aisnitch setup claude-code # hooks into Claude Code
73
- aisnitch setup opencode # hooks into OpenCode
74
- aisnitch adapters # check what's enabled
85
+ aisnitch start
75
86
  ```
76
87
 
77
- ---
78
-
79
- ## Install
88
+ That's it! The dashboard opens with live events from all configured tools.
80
89
 
81
- **npm (recommended):**
90
+ **No AI tools yet?** Try the demo mode:
82
91
 
83
92
  ```bash
84
- npm i -g aisnitch
93
+ aisnitch start --mock all
85
94
  ```
86
95
 
87
- **Homebrew:**
96
+ ### 3. Connect your tools
88
97
 
89
98
  ```bash
90
- brew install aisnitch
91
- ```
92
-
93
- **From source:**
99
+ # Pick your tools
100
+ aisnitch setup claude-code # hooks into Claude Code
101
+ aisnitch setup opencode # hooks into OpenCode
102
+ aisnitch setup aider # hooks into Aider
94
103
 
95
- ```bash
96
- git clone https://github.com/vava-nessa/AISnitch.git
97
- cd AISnitch
98
- pnpm install && pnpm build
99
- node dist/cli/index.js start
104
+ # Verify everything
105
+ aisnitch adapters
100
106
  ```
101
107
 
102
108
  ---
103
109
 
104
- ## Ecosystem
110
+ ## ๐ŸŽฏ Common Use Cases
105
111
 
106
- AISnitch ships as two packages with distinct audiences:
112
+ ### "I want to see all my AI agents in real time"
107
113
 
108
- | Package | For | Install |
109
- |---|---|---|
110
- | [`aisnitch`](https://www.npmjs.com/package/aisnitch) | **Users** โ€” the daemon, CLI, TUI dashboard, adapters | `npm i -g aisnitch` |
111
- | [`@aisnitch/client`](https://www.npmjs.com/package/@aisnitch/client) | **Developers** โ€” TypeScript SDK to consume the event stream | `pnpm add @aisnitch/client zod` |
114
+ ```bash
115
+ aisnitch start
116
+ ```
112
117
 
113
- **You're a user?** Install `aisnitch`, run `aisnitch start`, you're done.
118
+ Opens the TUI dashboard. Live events stream in as your tools work.
119
+
120
+ ### "I want to build something on top of AISnitch"
121
+
122
+ ```bash
123
+ # Start the daemon (runs in background)
124
+ aisnitch start --daemon
114
125
 
115
- **You're building something on top?** Install `@aisnitch/client` and connect in 3 lines:
126
+ # Now connect your app to ws://127.0.0.1:4820
127
+ ```
116
128
 
117
129
  ```typescript
118
- import { createAISnitchClient, describeEvent } from '@aisnitch/client';
130
+ import { createAISnitchClient } from '@aisnitch/client';
119
131
  import WebSocket from 'ws';
120
132
 
121
133
  const client = createAISnitchClient({ WebSocketClass: WebSocket as any });
122
- client.on('event', (e) => console.log(describeEvent(e)));
123
- // โ†’ "claude-code is editing code โ†’ src/index.ts [myproject]"
134
+
135
+ client.on('event', (e) => {
136
+ console.log(`${e['aisnitch.tool']}: ${e.type}`);
137
+ });
124
138
  ```
125
139
 
126
- Auto-reconnect, Zod-validated parsing, session tracking, filters, mascot state mapping โ€” all included. See the full **[Client SDK documentation](./packages/client/README.md)**.
140
+ ### "I want a fancy web dashboard on another computer"
127
141
 
128
- ---
142
+ ```bash
143
+ aisnitch fs --daemon
144
+ # โ†’ Opens http://127.0.0.1:5174 in browser
145
+ # โ†’ Connects to daemon automatically
146
+ ```
129
147
 
130
- ## How It Works
131
-
132
- ```
133
- Claude Code โ”€โ”€โ”
134
- OpenCode โ”€โ”€โ”€โ”€โ”€โ”ค
135
- Gemini CLI โ”€โ”€โ”€โ”คโ”€โ”€ hooks / file watchers / process detection
136
- Codex โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
137
- Goose โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
138
- Aider โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
139
- Copilot CLI โ”€โ”€โ”ค
140
- OpenClaw โ”€โ”€โ”€โ”€โ”€โ”˜
141
- โ”‚
142
- โ–ผ
143
- โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
144
- โ”‚ AISnitch Core โ”‚
145
- โ”‚ โ”‚
146
- โ”‚ Validate (Zod) โ”‚
147
- โ”‚ Normalize โ”‚
148
- โ”‚ Enrich context โ”‚
149
- โ”‚ (terminal, cwd, โ”‚
150
- โ”‚ pid, session) โ”‚
151
- โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
152
- โ”‚
153
- โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
154
- โ–ผ โ–ผ
155
- ws://127.0.0.1:4820 TUI
156
- (your consumers) (built-in)
157
- ```
158
-
159
- 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).
160
-
161
- **Nothing is stored on disk.** Events exist in memory during transit, then they're gone. Privacy-first by design.
148
+ ### "I want sound notifications when agents finish"
162
149
 
163
- ---
150
+ ```typescript
151
+ const client = createAISnitchClient();
164
152
 
165
- ## Architecture
166
-
167
- ```mermaid
168
- flowchart LR
169
- subgraph Tools["External AI tools"]
170
- CC["Claude Code"]
171
- OC["OpenCode"]
172
- GM["Gemini CLI"]
173
- CX["Codex"]
174
- GS["Goose"]
175
- AD["Aider"]
176
- OCL["OpenClaw"]
177
- PTY["Generic PTY"]
178
- end
179
-
180
- subgraph AIS["AISnitch runtime"]
181
- HTTP["HTTP hook receiver :4821"]
182
- UDS["UDS ingest"]
183
- REG["Adapter registry"]
184
- BUS["Typed EventBus"]
185
- WS["WebSocket server :4820"]
186
- TUI["Ink TUI"]
187
- end
188
-
189
- subgraph SDK["Consumer ecosystem"]
190
- CLIENT["@aisnitch/client SDK"]
191
- DASH["Dashboards"]
192
- SOUND["Sound engines"]
193
- MASCOT["Companions"]
194
- BOT["Bots"]
195
- end
196
-
197
- CC --> HTTP
198
- OC --> HTTP
199
- GM --> HTTP
200
- OCL --> HTTP
201
- CX --> REG
202
- GS --> REG
203
- AD --> REG
204
- PTY --> UDS
205
- HTTP --> BUS
206
- UDS --> BUS
207
- REG --> BUS
208
- BUS --> WS
209
- BUS --> TUI
210
- WS --> CLIENT
211
- CLIENT --> DASH
212
- CLIENT --> SOUND
213
- CLIENT --> MASCOT
214
- CLIENT --> BOT
153
+ client.on('event', (e) => {
154
+ if (e.type === 'task.complete') playSound('success.mp3');
155
+ if (e.type === 'agent.error') playSound('error.mp3');
156
+ if (e.type === 'agent.asking_user') playSound('ping.mp3');
157
+ });
215
158
  ```
216
159
 
217
160
  ---
218
161
 
219
- ## Supported Tools
162
+ ## ๐Ÿ“ฆ Installation Options
220
163
 
221
- | Tool | Strategy | Setup |
222
- |---|---|---|
223
- | **Claude Code** | Command hooks + JSONL transcript watching + process detection | `aisnitch setup claude-code` |
224
- | **OpenCode** | Local plugin + process detection | `aisnitch setup opencode` |
225
- | **Gemini CLI** | Command hooks + `logs.json` watching + process detection | `aisnitch setup gemini-cli` |
226
- | **Codex** | `codex-tui.log` parsing + process detection | `aisnitch setup codex` |
227
- | **Goose** | `goosed` API polling + SSE streams + SQLite fallback | `aisnitch setup goose` |
228
- | **Copilot CLI** | Repo hooks + session-state JSONL watching | `aisnitch setup copilot-cli` |
229
- | **Aider** | `.aider.chat.history.md` watching + notifications command | `aisnitch setup aider` |
230
- | **OpenClaw** | Managed hooks + command/memory/session watchers | `aisnitch setup openclaw` |
231
- | **Any other CLI** | PTY wrapper with output heuristics | `aisnitch wrap <command>` |
164
+ ### npm (Recommended)
232
165
 
233
- Run `aisnitch setup <tool>` to configure each tool, then `aisnitch adapters` to verify what's active.
166
+ ```bash
167
+ npm i -g aisnitch
168
+ ```
169
+
170
+ ### Homebrew (macOS/Linux)
171
+
172
+ ```bash
173
+ brew install aisnitch
174
+ ```
175
+
176
+ ### From Source
177
+
178
+ ```bash
179
+ git clone https://github.com/vava-nessa/AISnitch.git
180
+ cd AISnitch
181
+ pnpm install && pnpm build
182
+ node dist/cli/index.js start
183
+ ```
184
+
185
+ ### Upgrade
186
+
187
+ ```bash
188
+ # npm
189
+ npm update -g aisnitch
190
+
191
+ # Homebrew
192
+ brew upgrade aisnitch
193
+ ```
234
194
 
235
195
  ---
236
196
 
237
- ## Event Model
197
+ ## ๐Ÿ› ๏ธ Supported Tools
198
+
199
+ | Tool | Status | Setup Command |
200
+ |:---|:---:|:---|
201
+ | **Claude Code** | โœ… Active | `aisnitch setup claude-code` |
202
+ | **OpenCode** | โœ… Active | `aisnitch setup opencode` |
203
+ | **Gemini CLI** | โœ… Active | `aisnitch setup gemini-cli` |
204
+ | **Aider** | โœ… Active | `aisnitch setup aider` |
205
+ | **Codex** | โœ… Active | `aisnitch setup codex` |
206
+ | **Goose** | โœ… Active | `aisnitch setup goose` |
207
+ | **Copilot CLI** | โœ… Active | `aisnitch setup copilot-cli` |
208
+ | **OpenClaw** | โœ… Active | `aisnitch setup openclaw` |
209
+ | **Cursor** | โœ… Active | `aisnitch setup cursor` |
210
+ | **Zed** | โœ… Active | `aisnitch setup zed` |
211
+ | **Devin** | โœ… Active | `aisnitch setup devin` |
212
+ | **Kilo** | โœ… Active | `aisnitch setup kilo` |
213
+ | **Pi (zealncer)** | โœ… Active | `aisnitch setup pi` |
214
+ | **Any CLI** | ๐Ÿ”ง Fallback | `aisnitch wrap <command>` |
215
+
216
+ > ๐Ÿ’ก Run `aisnitch adapters` to see which tools are currently connected.
238
217
 
239
- Every event is a [CloudEvents v1.0](https://cloudevents.io/) envelope with AISnitch extensions:
218
+ ---
240
219
 
241
- ```jsonc
242
- {
243
- "specversion": "1.0",
244
- "id": "019713a4-beef-7000-8000-deadbeef0042", // UUIDv7
245
- "source": "aisnitch://claude-code/myproject",
246
- "type": "agent.coding", // one of 12 types below
247
- "time": "2026-03-28T14:30:00.000Z",
220
+ ## ๐Ÿ”Œ Web Dashboard
248
221
 
249
- "aisnitch.tool": "claude-code",
250
- "aisnitch.sessionid": "claude-code:myproject:p12345",
251
- "aisnitch.seqnum": 42,
222
+ Open a beautiful real-time dashboard in your browser:
252
223
 
253
- "data": {
254
- "state": "agent.coding",
255
- "project": "myproject",
256
- "projectPath": "/home/user/myproject",
257
- "activeFile": "src/index.ts",
258
- "toolName": "Edit",
259
- "toolInput": { "filePath": "src/index.ts" },
260
- "model": "claude-sonnet-4-5-20250514",
261
- "tokensUsed": 1500,
262
- "terminal": "iTerm2",
263
- "cwd": "/home/user/myproject",
264
- "pid": 12345,
265
- "instanceIndex": 1,
266
- "instanceTotal": 3,
267
- "errorMessage": "Rate limit exceeded", // only on agent.error
268
- "errorType": "rate_limit", // only on agent.error
269
- "raw": { /* original adapter payload */ }
270
- }
271
- }
224
+ ```bash
225
+ aisnitch fs # Open dashboard (auto-starts daemon if needed)
226
+ aisnitch fs --daemon # Start daemon + open dashboard
227
+ aisnitch fs --dashboard-port 8080 # Custom port
228
+ aisnitch fs --no-browser # Just start the server
272
229
  ```
273
230
 
274
- ### The 12 Event Types
231
+ **From another computer?** Make sure the host machine has the daemon running:
275
232
 
276
- | Type | What it means |
277
- |---|---|
278
- | `session.start` | A tool session began |
279
- | `session.end` | Session closed |
280
- | `task.start` | User submitted a prompt |
281
- | `task.complete` | Task finished |
282
- | `agent.thinking` | Model is reasoning |
283
- | `agent.streaming` | Model is generating output |
284
- | `agent.coding` | Model is editing files |
285
- | `agent.tool_call` | Model is using a tool (Bash, Grep, etc.) |
286
- | `agent.asking_user` | Waiting for human input |
287
- | `agent.idle` | No activity (120s timeout, configurable) |
288
- | `agent.error` | Something went wrong (rate limit, API error, tool failure) |
289
- | `agent.compact` | Context compaction / memory cleanup |
233
+ ```bash
234
+ aisnitch start --daemon # Start on host machine first
235
+ aisnitch fs # Connect from any browser
236
+ ```
290
237
 
291
238
  ---
292
239
 
293
- ## Build on Top of AISnitch
240
+ ## ๐Ÿ“ก WebSocket API (Build Anything)
241
+
242
+ AISnitch exposes a WebSocket stream at `ws://127.0.0.1:4820`. Connect with the SDK:
294
243
 
295
- 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:
244
+ ### Install the SDK
245
+
246
+ ```bash
247
+ pnpm add @aisnitch/client zod
248
+ ```
296
249
 
297
- ### Live Dashboard
250
+ ### Basic Usage
298
251
 
299
252
  ```typescript
300
253
  import { createAISnitchClient, describeEvent } from '@aisnitch/client';
@@ -302,268 +255,351 @@ import WebSocket from 'ws';
302
255
 
303
256
  const client = createAISnitchClient({ WebSocketClass: WebSocket as any });
304
257
 
305
- client.on('connected', (w) => {
306
- console.log(`Connected to AISnitch v${w.version}`);
307
- console.log(`Active tools: ${w.activeTools.join(', ')}`);
258
+ // Get notified when connected
259
+ client.on('connected', (info) => {
260
+ console.log(`Connected to AISnitch ${info.version}`);
261
+ console.log(`Tools: ${info.activeTools.join(', ')}`);
308
262
  });
309
263
 
310
- client.on('event', (e) => {
311
- const line = describeEvent(e);
312
- console.log(`[${e['aisnitch.tool']}] ${line}`);
264
+ // Receive all events
265
+ client.on('event', (event) => {
266
+ console.log(describeEvent(event));
267
+ // โ†’ "claude-code is thinking... โ†’ user auth module"
268
+ // โ†’ "opencode is coding... โ†’ src/api/users.ts"
313
269
  });
314
270
 
315
- // Track all active sessions
271
+ // Track sessions
316
272
  setInterval(() => {
317
273
  const sessions = client.sessions?.getAll() ?? [];
318
- console.log(`\n--- ${sessions.length} active session(s) ---`);
319
- for (const s of sessions) {
320
- console.log(` ${s.tool} โ†’ ${s.lastActivity} (${s.eventCount} events)`);
321
- }
274
+ console.log(`${sessions.length} active sessions`);
322
275
  }, 5000);
323
276
  ```
324
277
 
325
- ### Sound Notifications (PeonPing-style)
278
+ ### Sound Notifications
326
279
 
327
280
  ```typescript
328
- import { createAISnitchClient, filters } from '@aisnitch/client';
329
-
330
- const client = createAISnitchClient({ WebSocketClass: WebSocket as any });
331
-
332
- const SOUNDS: Record<string, string> = {
333
- 'session.start': 'boot.mp3',
334
- 'task.complete': 'success.mp3',
335
- 'agent.asking_user': 'alert.mp3',
336
- 'agent.error': 'error.mp3',
337
- 'agent.coding': 'keyboard.mp3',
281
+ import { createAISnitchClient } from '@aisnitch/client';
282
+
283
+ const SOUNDS = {
284
+ 'session.start': 'sounds/boot.mp3',
285
+ 'task.complete': 'sounds/done.mp3',
286
+ 'agent.asking_user': 'sounds/ping.mp3',
287
+ 'agent.error': 'sounds/error.mp3',
288
+ 'agent.coding': 'sounds/keyboard.mp3',
338
289
  };
339
290
 
340
- client.on('event', (e) => {
341
- const sound = SOUNDS[e.type];
342
- if (sound) playSound(`./sounds/${sound}`);
343
- });
344
- ```
345
-
346
- ### Animated Mascot / Companion
347
-
348
- ```typescript
349
- import { createAISnitchClient, eventToMascotState } from '@aisnitch/client';
350
-
351
291
  const client = createAISnitchClient();
352
-
353
292
  client.on('event', (e) => {
354
- const state = eventToMascotState(e);
355
- // state.mood โ†’ 'thinking' | 'working' | 'celebrating' | 'panicking' | ...
356
- // state.animation โ†’ 'ponder' | 'type' | 'dance' | 'shake' | ...
357
- // state.color โ†’ '#a855f7' (hex)
358
- // state.label โ†’ 'Thinking...'
359
- // state.detail โ†’ 'src/index.ts' (optional)
360
- updateMySprite(state);
293
+ if (SOUNDS[e.type]) playSound(SOUNDS[e.type]);
361
294
  });
362
295
  ```
363
296
 
364
- ### Slack / Discord Bot
365
-
366
- ```typescript
367
- import { createAISnitchClient, filters, formatStatusLine } from '@aisnitch/client';
368
- import WebSocket from 'ws';
369
-
370
- const client = createAISnitchClient({ WebSocketClass: WebSocket as any });
371
-
372
- // Only notify on events that need attention
373
- client.on('event', (e) => {
374
- if (filters.needsAttention(e)) {
375
- postToSlack(`โš ๏ธ ${formatStatusLine(e)}`);
376
- }
377
-
378
- if (e.type === 'task.complete') {
379
- postToSlack(`โœ… ${formatStatusLine(e)}`);
380
- }
381
- });
382
- ```
383
-
384
- ### Menu Bar Widget (Electron / Tauri)
297
+ ### Slack/Discord Bot
385
298
 
386
299
  ```typescript
387
300
  import { createAISnitchClient, formatStatusLine } from '@aisnitch/client';
388
301
 
389
302
  const client = createAISnitchClient();
390
- let sessionCounter = 0;
391
- const sessionMap = new Map<string, number>();
392
303
 
393
304
  client.on('event', (e) => {
394
- if (!sessionMap.has(e['aisnitch.sessionid'])) {
395
- sessionMap.set(e['aisnitch.sessionid'], ++sessionCounter);
305
+ // Notify on important events
306
+ if (e.type === 'agent.error') {
307
+ postToSlack(`๐Ÿ”ด Error: ${formatStatusLine(e)}`);
308
+ }
309
+ if (e.type === 'task.complete') {
310
+ postToDiscord(`โœ… Done: ${formatStatusLine(e)}`);
396
311
  }
397
- const num = sessionMap.get(e['aisnitch.sessionid'])!;
398
-
399
- // Update your menu bar / tray icon
400
- tray.setTitle(formatStatusLine(e, num));
401
- tray.setToolTip(`${client.sessions?.count ?? 0} active sessions`);
402
312
  });
403
313
  ```
404
314
 
405
- For complete API docs, React/Vue hooks, filters, TypeScript integration, and more examples, see the **[Client SDK README](./packages/client/README.md)**.
406
-
407
- <details>
408
- <summary>Raw WebSocket (without SDK)</summary>
409
-
410
- If you don't want the SDK, you can connect directly:
315
+ ### Direct WebSocket (No SDK)
411
316
 
412
317
  ```bash
413
- # One-liner to see raw events
318
+ # See raw events in one line
414
319
  node -e "
415
320
  const WebSocket = require('ws');
416
321
  const ws = new WebSocket('ws://127.0.0.1:4820');
417
- ws.on('message', m => {
418
- const e = JSON.parse(m.toString());
419
- if (e.type !== 'welcome') console.log(e.type, e['aisnitch.tool'], e.data?.project);
420
- });
322
+ ws.on('message', m => console.log(JSON.parse(m.toString()).type));
421
323
  "
422
324
  ```
423
325
 
424
- The first message is always a `welcome` payload with version, active tools, and uptime. Every subsequent message is a CloudEvents event as described above.
326
+ ---
425
327
 
426
- </details>
328
+ ## โŒจ๏ธ CLI Reference
427
329
 
428
- ### Health Check
330
+ ### Dashboard & TUI
429
331
 
430
332
  ```bash
431
- curl http://127.0.0.1:4821/health
333
+ aisnitch start # Open TUI dashboard
334
+ aisnitch start --tool claude-code # Filter by tool
335
+ aisnitch start --type agent.coding # Filter by event type
336
+ aisnitch start --view full-data # Show full JSON
432
337
  ```
433
338
 
434
- ```json
435
- {
436
- "status": "ok",
437
- "uptime": 3600,
438
- "consumers": 2,
439
- "events": 1542,
440
- "droppedEvents": 0
441
- }
442
- ```
339
+ ### Web Dashboard
443
340
 
444
- ---
341
+ ```bash
342
+ aisnitch fs # Open web dashboard
343
+ aisnitch fs --daemon # Start daemon + open
344
+ aisnitch fs --dashboard-port 8080 # Custom port
345
+ aisnitch fs --no-browser # Server only
346
+ ```
445
347
 
446
- ## CLI Reference
348
+ ### Daemon Management
447
349
 
448
350
  ```bash
449
- # Dashboard mode (always opens the TUI)
450
- aisnitch start
451
- aisnitch start --tool claude-code # pre-filter by tool
452
- aisnitch start --type agent.coding # pre-filter by event type
453
- aisnitch start --view full-data # expanded JSON inspector
454
-
455
- # Background daemon
456
- aisnitch start --daemon
457
- aisnitch status # check if daemon is running
458
- aisnitch attach # open TUI attached to running daemon
459
- aisnitch stop # kill daemon
351
+ aisnitch start --daemon # Start daemon in background
352
+ aisnitch status # Check daemon status
353
+ aisnitch attach # Attach TUI to running daemon
354
+ aisnitch stop # Stop daemon
355
+ ```
460
356
 
461
- # Raw event logger (no TUI, full payload)
462
- aisnitch logger
357
+ ### Tool Setup
463
358
 
464
- # Tool setup (run once per tool)
465
- aisnitch setup claude-code
359
+ ```bash
360
+ aisnitch setup claude-code # Configure tool
466
361
  aisnitch setup opencode
467
- aisnitch setup gemini-cli
468
- aisnitch setup codex
469
- aisnitch setup goose
470
- aisnitch setup copilot-cli
471
362
  aisnitch setup aider
472
- aisnitch setup openclaw
473
- aisnitch setup claude-code --revert # undo setup
474
-
475
- # Check enabled adapters
476
- aisnitch adapters
363
+ aisnitch setup claude-code --revert # Remove configuration
364
+ ```
477
365
 
478
- # Demo mode (simulated events)
479
- aisnitch mock claude-code --speed 2 --duration 20
480
- aisnitch start --mock all
366
+ ### Utilities
481
367
 
482
- # PTY wrapper (any unsupported CLI)
483
- aisnitch wrap aider --model sonnet
484
- aisnitch wrap goose session
368
+ ```bash
369
+ aisnitch adapters # Show enabled tools
370
+ aisnitch logger # Stream raw events (no TUI)
371
+ aisnitch mock claude-code # Simulate events
372
+ aisnitch mock all --speed 2 # Demo mode (2x speed)
373
+ aisnitch wrap aider --model sonnet # Wrap any CLI
374
+ aisnitch setup claude-code # Run setup wizard
375
+ aisnitch self-update # Update AISnitch
485
376
  ```
486
377
 
487
378
  ---
488
379
 
489
- ## TUI Keybinds
380
+ ## ๐Ÿ–ฅ๏ธ TUI Controls
490
381
 
491
382
  | Key | Action |
492
- |---|---|
383
+ |:---:|:---|
493
384
  | `q` / `Ctrl+C` | Quit |
494
- | `d` | Start / stop the daemon |
495
- | `r` | Refresh daemon status |
496
- | `v` | Toggle full-data JSON inspector |
497
- | `f` | Tool filter picker |
498
- | `t` | Event type filter picker |
499
- | `/` | Free-text search |
500
- | `Esc` | Clear all filters |
501
- | `Space` | Freeze / resume live tailing |
502
- | `c` | Clear event buffer |
503
- | `?` | Help overlay |
504
- | `Tab` | Switch panel focus |
505
- | `โ†‘โ†“` / `jk` | Navigate rows |
506
- | `[` `]` | Page inspector up / down |
385
+ | `d` | Toggle daemon |
386
+ | `r` | Refresh |
387
+ | `v` | Toggle JSON inspector |
388
+ | `f` | Filter by tool |
389
+ | `t` | Filter by event type |
390
+ | `/` | Search |
391
+ | `Esc` | Clear filters |
392
+ | `Space` | Freeze/resume |
393
+ | `c` | Clear buffer |
394
+ | `?` | Help |
395
+ | `Tab` | Switch panel |
396
+ | `โ†‘โ†“` / `jk` | Navigate |
397
+ | `[]` | Page inspector |
398
+
399
+ ---
400
+
401
+ ## ๐Ÿ—๏ธ Architecture
402
+
403
+ ```
404
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
405
+ โ”‚ External AI Tools โ”‚
406
+ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚
407
+ โ”‚ โ”‚ Claude โ”‚ โ”‚ OpenCode โ”‚ โ”‚ Gemini โ”‚ โ”‚ Aider โ”‚ ... โ”‚
408
+ โ”‚ โ”‚ Code โ”‚ โ”‚ โ”‚ โ”‚ CLI โ”‚ โ”‚ โ”‚ โ”‚
409
+ โ”‚ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚
410
+ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚
411
+ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚
412
+ โ”‚ โ”‚ โ”‚
413
+ โ”‚ โ–ผ โ”‚
414
+ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚
415
+ โ”‚ โ”‚ HTTP Receiver โ”‚ โ”‚
416
+ โ”‚ โ”‚ :4821 โ”‚ โ”‚
417
+ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚
418
+ โ”‚ โ”‚ โ”‚
419
+ โ”‚ โ–ผ โ”‚
420
+ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚
421
+ โ”‚ โ”‚ EventBus โ”‚ โ”‚
422
+ โ”‚ โ”‚ (validation + โ”‚ โ”‚
423
+ โ”‚ โ”‚ normalization) โ”‚ โ”‚
424
+ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚
425
+ โ”‚ โ”‚ โ”‚
426
+ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚
427
+ โ”‚ โ–ผ โ”‚ โ–ผ โ”‚
428
+ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚
429
+ โ”‚ โ”‚ WebSocket โ”‚ โ”‚ โ”‚ TUI โ”‚ โ”‚
430
+ โ”‚ โ”‚ :4820 โ”‚ โ”‚ โ”‚ Dashboard โ”‚ โ”‚
431
+ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚
432
+ โ”‚ โ”‚ โ”‚ โ”‚
433
+ โ”‚ โ–ผ โ–ผ โ”‚
434
+ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚
435
+ โ”‚ โ”‚ Client โ”‚ โ”‚ Sound โ”‚ โ”‚ Mascot โ”‚ โ”‚
436
+ โ”‚ โ”‚ Dashboard โ”‚ โ”‚ Engine โ”‚ โ”‚ Companion โ”‚ โ”‚
437
+ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚
438
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
439
+ ```
440
+
441
+ ### Key Points
442
+
443
+ - **Zero storage**: Events live in memory only, never written to disk
444
+ - **Privacy-first**: No data leaves your machine
445
+ - **Multi-instance tracking**: Handles multiple sessions of the same tool
446
+ - **Auto-reconnect**: SDK handles reconnection automatically
447
+ - **Zod validation**: All events validated before processing
448
+
449
+ ---
450
+
451
+ ## ๐Ÿ“Š Event Model
452
+
453
+ Every event follows [CloudEvents v1.0](https://cloudevents.io/) format:
454
+
455
+ ```json
456
+ {
457
+ "specversion": "1.0",
458
+ "id": "019713a4-beef-7000-8000-deadbeef0042",
459
+ "source": "aisnitch://claude-code/myproject",
460
+ "type": "agent.coding",
461
+ "time": "2026-03-28T14:30:00.000Z",
462
+
463
+ "aisnitch.tool": "claude-code",
464
+ "aisnitch.sessionid": "claude-code:myproject:p12345",
465
+ "aisnitch.seqnum": 42,
466
+
467
+ "data": {
468
+ "state": "agent.coding",
469
+ "project": "myproject",
470
+ "projectPath": "/home/user/myproject",
471
+ "activeFile": "src/index.ts",
472
+ "toolName": "Edit",
473
+ "model": "claude-sonnet-4-20250514",
474
+ "tokensUsed": 1500,
475
+ "inputTokens": 450,
476
+ "outputTokens": 1050,
477
+ "terminal": "iTerm2",
478
+ "cwd": "/home/user/myproject"
479
+ }
480
+ }
481
+ ```
482
+
483
+ ### Event Types
484
+
485
+ | Type | Description |
486
+ |:---|:---|
487
+ | `session.start` | Tool started |
488
+ | `session.end` | Tool closed |
489
+ | `task.start` | User submitted prompt |
490
+ | `task.complete` | Task finished |
491
+ | `agent.thinking` | Model reasoning |
492
+ | `agent.streaming` | Output being generated |
493
+ | `agent.coding` | Editing files |
494
+ | `agent.tool_call` | Using Bash, Grep, etc. |
495
+ | `agent.asking_user` | Waiting for input |
496
+ | `agent.idle` | No activity (2+ min) |
497
+ | `agent.error` | Error occurred |
498
+ | `agent.compact` | Context cleanup |
507
499
 
508
500
  ---
509
501
 
510
- ## Config Reference
502
+ ## ๐Ÿ“ File Structure
511
503
 
512
- AISnitch state lives under `~/.aisnitch/` (override with `AISNITCH_HOME`).
504
+ ```
505
+ ~/.aisnitch/
506
+ โ”œโ”€โ”€ config.json # Your configuration
507
+ โ”œโ”€โ”€ aisnitch.pid # Daemon PID
508
+ โ”œโ”€โ”€ daemon-state.json # Connection info
509
+ โ”œโ”€โ”€ daemon.log # Daemon logs (5MB max)
510
+ โ””โ”€โ”€ aisnitch.sock # Unix socket (IPC)
511
+ ```
513
512
 
514
- | Path | Purpose |
515
- |---|---|
516
- | `config.json` | User configuration |
517
- | `aisnitch.pid` | Daemon PID file |
518
- | `daemon-state.json` | Daemon connection info |
519
- | `daemon.log` | Daemon output log (5 MB max) |
520
- | `aisnitch.sock` | Unix domain socket (IPC) |
513
+ ### Ports
521
514
 
522
515
  | Port | Purpose |
523
- |---|---|
524
- | `4820` | WebSocket stream (consumers connect here) |
525
- | `4821` | HTTP hook receiver + `/health` endpoint |
516
+ |:---:|:---|
517
+ | `4820` | WebSocket (connect here) |
518
+ | `4821` | HTTP webhook receiver + health |
519
+
520
+ ### Health Check
521
+
522
+ ```bash
523
+ curl http://127.0.0.1:4821/health
524
+ ```
526
525
 
527
526
  ---
528
527
 
529
- ## Development
528
+ ## ๐Ÿงช Development
530
529
 
531
530
  ```bash
531
+ # Setup
532
+ git clone https://github.com/vava-nessa/AISnitch.git
533
+ cd AISnitch
532
534
  pnpm install
533
- pnpm build # ESM + CJS + .d.ts (main + client SDK)
534
- pnpm lint # ESLint
535
- pnpm typecheck # tsc --noEmit
536
- pnpm test # Vitest (156 tests)
537
- pnpm test:coverage
538
- pnpm test:e2e # requires opencode installed
539
535
 
540
- # Client SDK only
541
- pnpm --filter @aisnitch/client build
542
- pnpm --filter @aisnitch/client test # 48 tests
536
+ # Build
537
+ pnpm build # ESM + CJS + TypeScript types
538
+
539
+ # Quality
540
+ pnpm lint # ESLint
541
+ pnpm typecheck # TypeScript
542
+ pnpm test # 300+ tests
543
+ pnpm test:coverage # Coverage report
543
544
  ```
544
545
 
545
- Project structure:
546
+ ### Project Structure
546
547
 
547
548
  ```
548
- aisnitch/ # main package โ€” daemon, CLI, TUI, adapters
549
+ aisnitch/
549
550
  โ”œโ”€โ”€ src/
550
- โ”‚ โ”œโ”€โ”€ adapters/ # 13 adapter implementations
551
- โ”‚ โ”œโ”€โ”€ cli/ # commander commands
552
- โ”‚ โ”œโ”€โ”€ core/ # events, pipeline, config
553
- โ”‚ โ””โ”€โ”€ tui/ # Ink dashboard
551
+ โ”‚ โ”œโ”€โ”€ adapters/ # 13 tool adapters
552
+ โ”‚ โ”œโ”€โ”€ cli/ # Commander CLI
553
+ โ”‚ โ”œโ”€โ”€ core/ # Events, pipeline, config
554
+ โ”‚ โ””โ”€โ”€ tui/ # Ink terminal dashboard
554
555
  โ”œโ”€โ”€ packages/
555
- โ”‚ โ””โ”€โ”€ client/ # @aisnitch/client SDK
556
- โ”‚ โ””โ”€โ”€ src/ # types, client, sessions, filters, helpers
557
- โ”œโ”€โ”€ docs/ # technical documentation
558
- โ””โ”€โ”€ tasks/ # kanban task board
556
+ โ”‚ โ””โ”€โ”€ client/ # @aisnitch/client SDK
557
+ โ”œโ”€โ”€ docs/ # Technical docs
558
+ โ””โ”€โ”€ tasks/ # Task board
559
559
  ```
560
560
 
561
- Docs: [`docs/index.md`](./docs/index.md) | Tasks: [`tasks/tasks.md`](./tasks/tasks.md)
561
+ ---
562
+
563
+ ## ๐Ÿ“š Resources
562
564
 
563
- Contributing: [`CONTRIBUTING.md`](./CONTRIBUTING.md) | [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)
565
+ - [Documentation](./docs/index.md) โ€” Technical details
566
+ - [Client SDK](./packages/client/README.md) โ€” Build on top
567
+ - [Tasks](./tasks/tasks.md) โ€” What's being worked on
568
+ - [Contributing](./CONTRIBUTING.md) โ€” How to contribute
564
569
 
565
570
  ---
566
571
 
567
- ## License
572
+ ## โ“ FAQ
573
+
574
+ **Q: Does AISnitch store my data?**
575
+
576
+ No. Events transit through memory only and are never written to disk. Nothing leaves your machine.
577
+
578
+ **Q: Which tools are supported?**
579
+
580
+ 13 tools out of the box: Claude Code, OpenCode, Gemini CLI, Aider, Codex, Goose, Copilot CLI, OpenClaw, Cursor, Zed, Devin, Kilo, Pi. Plus any CLI via the `wrap` command.
568
581
 
569
- Apache-2.0, ยฉ [Vanessa Depraute / vava-nessa](https://github.com/vava-nessa).
582
+ **Q: Can I build my own dashboard?**
583
+
584
+ Yes! Use the `@aisnitch/client` SDK or connect directly to `ws://127.0.0.1:4820`.
585
+
586
+ **Q: How do I update AISnitch?**
587
+
588
+ ```bash
589
+ npm update -g aisnitch # npm
590
+ brew upgrade aisnitch # Homebrew
591
+ ```
592
+
593
+ **Q: Why "Snitch"?**
594
+
595
+ Because it snitches on your AI agents โ€” tells you what they're doing! ๐ŸŽญ
596
+
597
+ ---
598
+
599
+ ## ๐Ÿ“œ License
600
+
601
+ Apache-2.0 โ€” [Vanessa Depraute](https://github.com/vava-nessa)
602
+
603
+ [![CI](https://github.com/vava-nessa/AISnitch/actions/workflows/ci.yml/badge.svg)](https://github.com/vava-nessa/AISnitch/actions/workflows/ci.yml)
604
+ [![npm](https://img.shields.io/npm/v/aisnitch?logo=npm)](https://www.npmjs.com/package/aisnitch)
605
+ [![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js)](https://nodejs.org/)