claw-insights 0.1.4 → 0.1.5

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 (3) hide show
  1. package/README.md +114 -40
  2. package/package.json +2 -2
  3. package/server/index.js +6 -1
package/README.md CHANGED
@@ -1,20 +1,22 @@
1
1
  <div align="center">
2
2
  <img src="packages/web/public/logo/icon-dark.svg" width="80" alt="Claw Insights" />
3
3
  <h1>Claw Insights</h1>
4
- <p><strong>Replay, metrics, logs &amp; shareable snapshots for <a href="https://github.com/openclaw/openclaw">OpenClaw</a> agents</strong></p>
4
+ <p><strong>Open-source agent observability — replay, metrics, logs & shareable snapshots</strong></p>
5
+ <p><sub>Built for <a href="https://github.com/openclaw/openclaw">OpenClaw</a> · Adapter architecture — extend to any agent runtime</sub></p>
5
6
  <p>
6
7
  <img src="https://img.shields.io/badge/%F0%9F%94%8C_Zero_Intrusion-read--only_sidecar-10b981" alt="Zero Intrusion" />
7
8
  <img src="https://img.shields.io/badge/%F0%9F%94%8D_Full_Replay-session_transcripts-6366f1" alt="Full Replay" />
8
9
  <img src="https://img.shields.io/badge/%F0%9F%93%B8_Shareable_Snapshots-PNG_%7C_SVG-f59e0b" alt="Shareable Snapshots" />
9
10
  </p>
10
11
  <p>
12
+ <a href="https://github.com/LucaL6/claw-insights/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/LucaL6/claw-insights/ci.yml?branch=main&label=CI" alt="CI" /></a>
11
13
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
12
14
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-%E2%89%A522.5-green" alt="Node.js" /></a>
13
15
  <img src="https://img.shields.io/badge/macOS-supported-blue" alt="macOS" />
14
16
  <img src="https://img.shields.io/badge/Linux-supported-blue" alt="Linux" />
15
17
  </p>
16
18
  <br />
17
- <img src="docs/assets/hero-montage.png" width="100%" alt="Dashboard, Session Transcript, and Snapshot API" />
19
+ <img src="docs/assets/hero-montage.png" width="100%" alt="Claw Insights dashboard — agent observability with session replay, token analytics, and shareable snapshots" />
18
20
  </div>
19
21
 
20
22
  ---
@@ -26,25 +28,25 @@
26
28
 
27
29
  ## Features
28
30
 
29
- - **Zero Intrusion** — Pure read-only sidecar; no code changes, no cloud calls, data never leaves your machine
30
- - **Session Replay** — Full transcript timeline with role separation, tool calls, and per-turn token tracking
31
- - **Shareable Snapshots** — Generate PNG/SVG status cards via REST API with themes, languages, and detail levels
32
- - **Metrics Dashboard** — Per-model token breakdown, error rates, and uptime over 30m / 1h / 6h / 12h / 24h
33
- - **Event Logs** — Structured viewer with density heatmap, filtering, and search
31
+ - **Zero Intrusion** — Self-hosted, local-first observability sidecar; no SDK, no code changes, no cloud calls, data never leaves your machine
32
+ - **Session Replay** — Full transcript timeline with role separation, tool calls, thinking steps, and per-turn token tracking
33
+ - **Shareable Snapshots** — Generate PNG/SVG status cards via REST API or CLI with themes, languages, and detail levels
34
+ - **Metrics Dashboard** — Per-model token analytics, error rates, and uptime over 30m / 1h / 6h / 12h / 24h
35
+ - **Event Logs** — Structured log viewer with density heatmap, filtering, and search for AI agent debugging
34
36
  - **One Command Setup** — Auto-discovers your running gateway, lightweight SQLite storage
35
37
  - **Dark / Light · EN / 中文** — Full theming and i18n with runtime toggle
36
38
 
37
39
  ## Quick Start
38
40
 
39
41
  ```bash
40
- # Install
42
+ # Install globally
41
43
  npm install -g claw-insights
42
44
 
43
- # Start (auto-connects to your running OpenClaw gateway)
45
+ # Start — auto-connects to your running OpenClaw gateway
44
46
  claw-insights start
45
47
  ```
46
48
 
47
- On launch you'll see an access URL:
49
+ On launch you'll see:
48
50
 
49
51
  ```
50
52
  ✅ Claw Insights v0.1.0 ready in 1.2s
@@ -57,37 +59,111 @@ PID 12345 · daemon · Port 41041
57
59
 
58
60
  Open the URL — token is exchanged for a session cookie, and you're in.
59
61
 
62
+ ## Usage
63
+
64
+ ### 🔌 Zero Intrusion — start & connect
65
+
66
+ ```bash
67
+ claw-insights start # Auto-discovers running OpenClaw gateway
68
+ claw-insights start --gateway <url> # Connect to specific gateway
69
+ claw-insights start --no-auth # Disable token authentication
70
+ claw-insights start --open # Start and open browser automatically
71
+ claw-insights status # Show access URL & connection info
72
+ claw-insights status --json # Machine-readable status (includes auth.accessUrl)
73
+ claw-insights logs -n 50 # Tail daemon logs
74
+ claw-insights restart # Restart daemon
75
+ claw-insights stop # Stop daemon
76
+ ```
77
+
78
+ ### 🔍 Full Replay — sessions & transcripts
79
+
80
+ Browse all sessions in the dashboard. Click any session to see the full transcript timeline — with role separation, tool call detail, and per-turn token / latency tracking.
81
+
82
+ ### 📸 Shareable Snapshots — capture & share
83
+
84
+ ```bash
85
+ claw-insights snapshot # Default: PNG, dark theme, 6h range
86
+ claw-insights snapshot --format svg --theme light # SVG light theme
87
+ claw-insights snapshot --range 24h --detail full # 24h detailed snapshot
88
+ claw-insights snapshot --lang zh --quick # Quick Chinese compact card
89
+ ```
90
+
91
+ REST API for programmatic access:
92
+
60
93
  ```bash
61
- claw-insights status # Show current access URL
62
- claw-insights status --json # Machine-readable status (includes auth.accessUrl)
63
- claw-insights stop # Stop daemon
64
- claw-insights start --no-auth # Disable authentication
94
+ curl -X POST http://localhost:41041/api/snapshot \
95
+ -H "Authorization: Bearer $TOKEN" \
96
+ -d '{"format":"svg","theme":"light","detail":"full","range":"24h"}'
65
97
  ```
66
98
 
67
- Example (`status --json`, trimmed):
68
-
69
- ```json
70
- {
71
- "schemaVersion": 1,
72
- "server": { "port": 41041, "url": "http://127.0.0.1:41041" },
73
- "auth": {
74
- "mode": "token-cookie",
75
- "tokenUrlPresent": true,
76
- "accessUrl": "http://127.0.0.1:41041/?token=..."
77
- }
78
- }
99
+ ## How It Works
100
+
101
+ Claw Insights runs as a **read-only sidecar** for LLM & agent observability alongside your AI agent runtime.
102
+ It tails log files and CLI output — no SDK, no code changes, no network calls.
103
+
79
104
  ```
105
+ Agent Runtime (OpenClaw / Claude Code / ...)
106
+ │
107
+ ├─ log files ──→ claw-insights daemon
108
+ │ │
109
+ ├─ CLI probe ──→ ├─→ SQLite (local-only storage)
110
+ │ ├─→ GraphQL API + SSE subscriptions
111
+ │ └─→ Satori renderer (PNG/SVG)
112
+ │ │
113
+ └─────────────────────────→ React dashboard (real-time)
114
+ ```
115
+
116
+ **Tech stack:** Express · GraphQL Yoga · SQLite · Satori · React 19 · Vite · ECharts
80
117
 
81
- → Full install options, snapshot API, and troubleshooting: [docs/configuration.md](docs/configuration.md)
118
+ → Full configuration and install options: [docs/configuration.md](docs/configuration.md)
82
119
 
83
120
  ## 🤖 AI Agent Friendly
84
121
 
85
- Ships with structured resources for AI agents — see **[AGENTS.md](AGENTS.md)** for the full index:
122
+ Claw Insights ships with structured skills for AI agents —
123
+ your agent can install, operate, and capture snapshots autonomously.
124
+
125
+ See **[AGENTS.md](AGENTS.md)** for the full index.
126
+
127
+ ### Install Skill
86
128
 
87
- | Skill | Use case |
88
- | ----------------------------------------- | ------------------------------------------------- |
89
- | [install](docs/skills/install/SKILL.md) | Install, configure, and launch |
90
- | [snapshot](docs/skills/snapshot/SKILL.md) | Capture dashboard as PNG/SVG/JSON via REST or CLI |
129
+ Help AI agents set up Claw Insights from scratch — install, configure, launch, and verify.
130
+
131
+ ```bash
132
+ # Agent reads the skill, then executes:
133
+ npm install -g claw-insights
134
+ claw-insights start
135
+ claw-insights status # Verify: running + gateway connected
136
+ ```
137
+
138
+ → Full skill: [docs/skills/install/SKILL.md](docs/skills/install/SKILL.md)
139
+
140
+ ### Snapshot Skill
141
+
142
+ Teach agents to capture dashboard state as PNG/SVG/JSON and share to chat channels.
143
+
144
+ ```bash
145
+ # Capture a dark-theme Chinese snapshot for the last 6 hours
146
+ claw-insights snapshot --theme dark --lang zh --range 6h -o status.png
147
+
148
+ # REST API — programmatic access from any agent
149
+ curl -X POST http://localhost:41041/api/snapshot \
150
+ -H "Authorization: Bearer $TOKEN" \
151
+ -d '{"format":"svg","theme":"light","detail":"full"}'
152
+ ```
153
+
154
+ → Full skill: [docs/skills/snapshot/SKILL.md](docs/skills/snapshot/SKILL.md)
155
+
156
+ ## Roadmap
157
+
158
+ ✅ Shipped · 🔧 In Progress · 📋 Planned
159
+
160
+ - ✅ Session replay & transcript timeline
161
+ - ✅ Metrics dashboard (token analytics, error rates, uptime)
162
+ - ✅ Shareable snapshots (PNG / SVG / JSON)
163
+ - 🔧 Thinking / reasoning step visualization — *in progress*
164
+ - 🔧 Agent tool call observability — *in progress*
165
+ - 📋 Multiple data source adapters (Claude Code, Codex, ...)
166
+ - 📋 Multi-agent topology view
91
167
 
92
168
  ## Architecture
93
169
 
@@ -101,18 +177,16 @@ claw-insights/
101
177
  └── codegen.ts GraphQL codegen config (3 targets)
102
178
  ```
103
179
 
104
- **Data flow:** OpenClaw gateway → log tailing + CLI → SQLite → GraphQL (SSE subscriptions) → React
105
-
106
180
  → Full architecture, dev setup, and codegen: [docs/architecture.md](docs/architecture.md)
107
181
 
108
182
  ## Documentation
109
183
 
110
- | Document | Description |
111
- | -------------------------------------- | ------------------------------------- |
112
- | [Configuration](docs/configuration.md) | All env vars, config file, auth model |
113
- | [Architecture](docs/architecture.md) | System design, dev setup, testing |
114
- | [API Reference](docs/api-reference.md) | GraphQL + REST endpoint signatures |
115
- | [AGENTS.md](AGENTS.md) | AI agent skill index |
184
+ | Document | Description |
185
+ | -------------------------------------- | -------------------------------------------------- |
186
+ | [Configuration](docs/configuration.md) | All env vars, config file, auth model |
187
+ | [Architecture](docs/architecture.md) | System design, dev setup, testing |
188
+ | [API Reference](docs/api-reference.md) | GraphQL + REST endpoint signatures |
189
+ | [AGENTS.md](AGENTS.md) | AI agent skill index |
116
190
 
117
191
  ## Contributing
118
192
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "claw-insights",
3
- "version": "0.1.4",
4
- "description": "Real-time monitoring dashboard for OpenClaw gateway",
3
+ "version": "0.1.5",
4
+ "description": "Open-source agent observability — replay, metrics, logs & shareable snapshots",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "claw-insights": "./bin/claw-insights"
package/server/index.js CHANGED
@@ -3566,9 +3566,14 @@ function createGatewayClient(platform, options) {
3566
3566
  if (json.trim() === "") {
3567
3567
  return { ok: false, reason: "empty" };
3568
3568
  }
3569
+ const jsonStartIdx = json.indexOf("{");
3570
+ if (jsonStartIdx === -1) {
3571
+ return { ok: false, reason: "invalid-json" };
3572
+ }
3573
+ const cleanedJson = json.substring(jsonStartIdx);
3569
3574
  let d;
3570
3575
  try {
3571
- d = JSON.parse(json);
3576
+ d = JSON.parse(cleanedJson);
3572
3577
  } catch {
3573
3578
  return { ok: false, reason: "invalid-json" };
3574
3579
  }