claw-insights 0.1.3 → 0.1.5

package/README.md

@@ -1,20 +1,22 @@
 <div align="center">
   <img src="packages/web/public/logo/icon-dark.svg" width="80" alt="Claw Insights" />
   <h1>Claw Insights</h1>
-  <p><strong>Replay, metrics, logs &amp; shareable snapshots for <a href="https://github.com/openclaw/openclaw">OpenClaw</a> agents</strong></p>
+  <p><strong>Open-source agent observability — replay, metrics, logs & shareable snapshots</strong></p>
+  <p><sub>Built for <a href="https://github.com/openclaw/openclaw">OpenClaw</a> · Adapter architecture — extend to any agent runtime</sub></p>
   <p>
     <img src="https://img.shields.io/badge/%F0%9F%94%8C_Zero_Intrusion-read--only_sidecar-10b981" alt="Zero Intrusion" />
     <img src="https://img.shields.io/badge/%F0%9F%94%8D_Full_Replay-session_transcripts-6366f1" alt="Full Replay" />
     <img src="https://img.shields.io/badge/%F0%9F%93%B8_Shareable_Snapshots-PNG_%7C_SVG-f59e0b" alt="Shareable Snapshots" />
   </p>
   <p>
+    <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>
     <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
     <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-%E2%89%A522.5-green" alt="Node.js" /></a>
     <img src="https://img.shields.io/badge/macOS-supported-blue" alt="macOS" />
     <img src="https://img.shields.io/badge/Linux-supported-blue" alt="Linux" />
   </p>
   <br />
-  <img src="docs/assets/hero-montage.png" width="100%" alt="Dashboard, Session Transcript, and Snapshot API" />
+  <img src="docs/assets/hero-montage.png" width="100%" alt="Claw Insights dashboard — agent observability with session replay, token analytics, and shareable snapshots" />
 </div>
 
 ---
@@ -26,25 +28,25 @@
 
 ## Features
 
-- **Zero Intrusion** — Pure read-only sidecar; no code changes, no cloud calls, data never leaves your machine
-- **Session Replay** — Full transcript timeline with role separation, tool calls, and per-turn token tracking
-- **Shareable Snapshots** — Generate PNG/SVG status cards via REST API with themes, languages, and detail levels
-- **Metrics Dashboard** — Per-model token breakdown, error rates, and uptime over 30m / 1h / 6h / 12h / 24h
-- **Event Logs** — Structured viewer with density heatmap, filtering, and search
+- **Zero Intrusion** — Self-hosted, local-first observability sidecar; no SDK, no code changes, no cloud calls, data never leaves your machine
+- **Session Replay** — Full transcript timeline with role separation, tool calls, thinking steps, and per-turn token tracking
+- **Shareable Snapshots** — Generate PNG/SVG status cards via REST API or CLI with themes, languages, and detail levels
+- **Metrics Dashboard** — Per-model token analytics, error rates, and uptime over 30m / 1h / 6h / 12h / 24h
+- **Event Logs** — Structured log viewer with density heatmap, filtering, and search for AI agent debugging
 - **One Command Setup** — Auto-discovers your running gateway, lightweight SQLite storage
 - **Dark / Light · EN / 中文** — Full theming and i18n with runtime toggle
 
 ## Quick Start
 
 ```bash
-# Install
+# Install globally
 npm install -g claw-insights
 
-# Start (auto-connects to your running OpenClaw gateway)
+# Start — auto-connects to your running OpenClaw gateway
 claw-insights start
 ```
 
-On launch you'll see an access URL:
+On launch you'll see:
 
 ```
 ✅ Claw Insights v0.1.0    ready in 1.2s
@@ -57,22 +59,111 @@ PID 12345 · daemon · Port 41041
 
 Open the URL — token is exchanged for a session cookie, and you're in.
 
+## Usage
+
+### 🔌 Zero Intrusion — start & connect
+
+```bash
+claw-insights start                    # Auto-discovers running OpenClaw gateway
+claw-insights start --gateway <url>    # Connect to specific gateway
+claw-insights start --no-auth          # Disable token authentication
+claw-insights start --open             # Start and open browser automatically
+claw-insights status                   # Show access URL & connection info
+claw-insights status --json            # Machine-readable status (includes auth.accessUrl)
+claw-insights logs -n 50               # Tail daemon logs
+claw-insights restart                  # Restart daemon
+claw-insights stop                     # Stop daemon
+```
+
+### 🔍 Full Replay — sessions & transcripts
+
+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.
+
+### 📸 Shareable Snapshots — capture & share
+
 ```bash
-claw-insights status          # Show current access URL
-claw-insights stop            # Stop daemon
-claw-insights start --no-auth # Disable authentication
+claw-insights snapshot                              # Default: PNG, dark theme, 6h range
+claw-insights snapshot --format svg --theme light   # SVG light theme
+claw-insights snapshot --range 24h --detail full    # 24h detailed snapshot
+claw-insights snapshot --lang zh --quick            # Quick Chinese compact card
 ```
 
-→ Full install options, snapshot API, and troubleshooting: [docs/configuration.md](docs/configuration.md)
+REST API for programmatic access:
+
+```bash
+curl -X POST http://localhost:41041/api/snapshot \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"format":"svg","theme":"light","detail":"full","range":"24h"}'
+```
+
+## How It Works
+
+Claw Insights runs as a **read-only sidecar** for LLM & agent observability alongside your AI agent runtime.
+It tails log files and CLI output — no SDK, no code changes, no network calls.
+
+```
+Agent Runtime (OpenClaw / Claude Code / ...)
+  │
+  ├─ log files ──→  claw-insights daemon
+  │                     │
+  ├─ CLI probe ──→      ├─→ SQLite (local-only storage)
+  │                     ├─→ GraphQL API + SSE subscriptions
+  │                     └─→ Satori renderer (PNG/SVG)
+  │                              │
+  └─────────────────────────→  React dashboard (real-time)
+```
+
+**Tech stack:** Express · GraphQL Yoga · SQLite · Satori · React 19 · Vite · ECharts
+
+→ Full configuration and install options: [docs/configuration.md](docs/configuration.md)
 
 ## 🤖 AI Agent Friendly
 
-Ships with structured resources for AI agents — see **[AGENTS.md](AGENTS.md)** for the full index:
+Claw Insights ships with structured skills for AI agents —
+your agent can install, operate, and capture snapshots autonomously.
+
+See **[AGENTS.md](AGENTS.md)** for the full index.
 
-| Skill                                     | Use case                                          |
-| ----------------------------------------- | ------------------------------------------------- |
-| [install](docs/skills/install/SKILL.md)   | Install, configure, and launch                    |
-| [snapshot](docs/skills/snapshot/SKILL.md) | Capture dashboard as PNG/SVG/JSON via REST or CLI |
+### Install Skill
+
+Help AI agents set up Claw Insights from scratch — install, configure, launch, and verify.
+
+```bash
+# Agent reads the skill, then executes:
+npm install -g claw-insights
+claw-insights start
+claw-insights status   # Verify: running + gateway connected
+```
+
+→ Full skill: [docs/skills/install/SKILL.md](docs/skills/install/SKILL.md)
+
+### Snapshot Skill
+
+Teach agents to capture dashboard state as PNG/SVG/JSON and share to chat channels.
+
+```bash
+# Capture a dark-theme Chinese snapshot for the last 6 hours
+claw-insights snapshot --theme dark --lang zh --range 6h -o status.png
+
+# REST API — programmatic access from any agent
+curl -X POST http://localhost:41041/api/snapshot \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"format":"svg","theme":"light","detail":"full"}'
+```
+
+→ Full skill: [docs/skills/snapshot/SKILL.md](docs/skills/snapshot/SKILL.md)
+
+## Roadmap
+
+✅ Shipped · 🔧 In Progress · 📋 Planned
+
+- ✅ Session replay & transcript timeline
+- ✅ Metrics dashboard (token analytics, error rates, uptime)
+- ✅ Shareable snapshots (PNG / SVG / JSON)
+- 🔧 Thinking / reasoning step visualization — *in progress*
+- 🔧 Agent tool call observability — *in progress*
+- 📋 Multiple data source adapters (Claude Code, Codex, ...)
+- 📋 Multi-agent topology view
 
 ## Architecture
 
@@ -86,18 +177,16 @@ claw-insights/
 └── codegen.ts      GraphQL codegen config (3 targets)
 ```
 
-**Data flow:** OpenClaw gateway → log tailing + CLI → SQLite → GraphQL (SSE subscriptions) → React
-
 → Full architecture, dev setup, and codegen: [docs/architecture.md](docs/architecture.md)
 
 ## Documentation
 
-| Document                               | Description                           |
-| -------------------------------------- | ------------------------------------- |
-| [Configuration](docs/configuration.md) | All env vars, config file, auth model |
-| [Architecture](docs/architecture.md)   | System design, dev setup, testing     |
-| [API Reference](docs/api-reference.md) | GraphQL + REST endpoint signatures    |
-| [AGENTS.md](AGENTS.md)                 | AI agent skill index                  |
+| Document                               | Description                                        |
+| -------------------------------------- | -------------------------------------------------- |
+| [Configuration](docs/configuration.md) | All env vars, config file, auth model              |
+| [Architecture](docs/architecture.md)   | System design, dev setup, testing                  |
+| [API Reference](docs/api-reference.md) | GraphQL + REST endpoint signatures                 |
+| [AGENTS.md](AGENTS.md)                 | AI agent skill index                               |
 
 ## Contributing
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claw-insights",
-  "version": "0.1.3",
-  "description": "Real-time monitoring dashboard for OpenClaw gateway",
+  "version": "0.1.5",
+  "description": "Open-source agent observability — replay, metrics, logs & shareable snapshots",
   "type": "module",
   "bin": {
     "claw-insights": "./bin/claw-insights"

package/server/cli/daemon.d.ts

@@ -29,6 +29,7 @@ interface StatusJsonPayload {
     auth: {
         mode: string;
         tokenUrlPresent: boolean;
+        accessUrl: string | null;
     };
     health: {
         ok: boolean;

package/server/cli/daemon.js

@@ -519,7 +519,11 @@ async function daemonStatus(options = {}) {
         version,
         server: { state: "stopped", pid: null, port, url: `http://127.0.0.1:${port}` },
         web: { enabled: !serverOnly, port: webPort, url: `http://127.0.0.1:${webPort}` },
-        auth: { mode: noAuth ? "none" : "token-cookie", tokenUrlPresent: false },
+        auth: {
+          mode: noAuth ? "none" : "token-cookie",
+          tokenUrlPresent: false,
+          accessUrl: noAuth ? `http://127.0.0.1:${port}/` : null
+        },
         health: { ok: false, ready: false, gateway: "unknown", db: "unknown" }
       });
       console.log(JSON.stringify(payload));
@@ -542,12 +546,25 @@ async function daemonStatus(options = {}) {
     const version = resolveCliVersion(process.env);
     const isOk = healthResponseOk && healthData?.status === "ok";
     const state = healthResponseOk ? isOk ? "running" : "degraded" : "degraded";
-    const tokenUrlPresent = existsSync2(join(paths.dataDir, "auth-token"));
+    const tokenFile = join(paths.dataDir, "auth-token");
+    let token = null;
+    if (!noAuth) {
+      try {
+        const rawToken = readFileSync2(tokenFile, "utf-8").trim();
+        if (rawToken) {
+          token = rawToken;
+        }
+      } catch {
+        token = null;
+      }
+    }
+    const tokenUrlPresent = token !== null;
+    const accessUrl = noAuth ? `http://127.0.0.1:${port}/` : token ? `http://127.0.0.1:${port}/?token=${token}` : null;
     const payload = buildStatusJson({
       version,
       server: { state, pid, port, url: `http://127.0.0.1:${port}` },
       web: { enabled: !serverOnly, port: webPort, url: `http://127.0.0.1:${webPort}` },
-      auth: { mode: noAuth ? "none" : "token-cookie", tokenUrlPresent },
+      auth: { mode: noAuth ? "none" : "token-cookie", tokenUrlPresent, accessUrl },
       health: {
         ok: isOk,
         ready: isOk,

package/server/index.js

@@ -3566,9 +3566,14 @@ function createGatewayClient(platform, options) {
     if (json.trim() === "") {
       return { ok: false, reason: "empty" };
     }
+    const jsonStartIdx = json.indexOf("{");
+    if (jsonStartIdx === -1) {
+      return { ok: false, reason: "invalid-json" };
+    }
+    const cleanedJson = json.substring(jsonStartIdx);
     let d;
     try {
-      d = JSON.parse(json);
+      d = JSON.parse(cleanedJson);
     } catch {
       return { ok: false, reason: "invalid-json" };
     }