@superbased/observer 1.8.0 → 1.8.2

package/README.md

@@ -140,6 +140,8 @@ env var that matches your client(s); both can coexist on one machine.
 | **OpenClaw** ([openclaw.ai](https://openclaw.ai/)) | (no proxy yet)                     | JSONL + sqlite — `~/.openclaw/tasks/runs.sqlite` + `~/.openclaw/agents/<agent>/sessions/sessions.json` |
 | **Pi** ([pi.dev](https://pi.dev/)) | (no proxy yet)                                       | JSONL — `~/.pi/agent/sessions/--<path>--/*.jsonl` (per upstream `docs/session-format.md` v3). Captures user / assistant / toolResult / `bashExecution` message roles; `usage.cost.total` → per-message USD; terminal `stopReason` (stop/length/error/aborted) → `task_complete` with `success=false` for failures (mid-turn `toolUse` is correctly skipped); `thinking` blocks surface as preceding reasoning. Tagged `Source=jsonl, Reliability=approximate`. |
 | **Google Antigravity** | (no proxy yet) | Encrypted protobuf — `~/.gemini/antigravity/conversations/*.pb` (Linux-native) and the matching Windows-side path on WSL2. Observer ships a per-OS Chromium-pattern `oscrypt` key fetcher (macOS Keychain / libsecret / DPAPI / WSL2-via-PowerShell helper) and a multi-cipher try-loop for local decryption. Sessions whose ciphers don't validate locally fall back to the language_server's `GetCascadeTrajectory` gRPC endpoint via a built-in helper (`antigravity-bridge.exe` on WSL2 / native gRPC elsewhere) — extracts model + per-turn token counts + Tier 0–6 ToolEvents (file views, artifact edits/writes, user prompts, assistant text, run_command terminal snapshots, structured plan steps, final summaries). State index + per-conversation title/workspace URI read from `state.vscdb` + `state.vscdb.backup`. Tagged `Source=jsonl, Reliability=approximate`. |
+| **Kilo Code IDE extension (legacy)** | (no proxy yet) | JSON — `<vsCodeGlobalStorage>/kilocode.kilo-code/tasks/<taskId>/api_conversation_history.json`. The legacy Kilo extension is a Cline + Roo Code fork and shares the Cline parser; emitted rows are re-tagged `Tool="kilo-code"` so dashboard rollups don't blur Kilo activity into Cline. Tagged `Source=jsonl, Reliability=approximate`. |
+| **Kilo Code CLI (current)**     | Optional: `OPENAI_BASE_URL=http://127.0.0.1:8820/v1` (Kilo Gateway is OpenAI-compatible at the wire) | SQLite — `~/.local/share/kilo/kilo.db` on every OS (Kilo intentionally mirrors XDG; Windows does NOT use `%APPDATA%`). The new `@kilocode/cli` (npm) is a fork of sst/opencode and uses the same `message`/`part`/`todo` tables shape with Kilo additions (`project`, `workspace`, `event`, `session_message`, `account`, `permission`, `session_share`). Captures **token counts + model + cost** per assistant message from `message.data.tokens = {total, input, output, reasoning, cache: {read, write}}`. Tool name coverage inherits OpenCode's surface (`read` → `read_file`, `bash` → `run_command`, `websearch` → `web_search`, etc.). Tagged `Source=jsonl, Reliability=approximate`. |
 | **Gemini CLI** | (no proxy yet) | JSONL or single-object JSON — `~/.gemini/tmp/<hash>/chats/session-*.{json,jsonl}`. Dual-format dispatch: legacy single-object JSON (size-based cursor, cline-style) and proposed JSONL event records (byte-offset cursor, issue [#15292](https://github.com/google-gemini/gemini-cli/issues/15292)). Action mapping covers `read_file` / `write_file` / `edit_file` / `run_command` / `search_files` / `web_fetch` and arbitrary MCP tool calls. Project root falls back through tool-call `cwd` → `~/.gemini/history/<hash>/.git/config` worktree pointer → synthetic `[gemini-cli:<hash>]` key (promoted via ON CONFLICT DO UPDATE on `sessions.project_id` once a future scan supplies a real cwd). Tagged `Source=jsonl, Reliability=approximate`. |
 
 **JSONL-only** clients are captured passively by the watcher whenever
@@ -150,7 +152,7 @@ call shows up on Sessions / Actions / Discovery / Tools / Patterns and
 the JSONL-derived token counts feed the Cost tab. Reliability tagging
 is per-adapter: Claude Code emits `unreliable` (the JSONL stream uses
 streaming-time placeholder counts per spec §24); Codex / Cline / Pi /
-OpenCode / OpenClaw / Antigravity / Gemini CLI emit `approximate`
+OpenCode / OpenClaw / Antigravity / Gemini CLI / Kilo Code / Kilo Code CLI emit `approximate`
 (provider-reported usage that hasn't been reconciled against an
 upstream invoice).
 
@@ -342,8 +344,9 @@ sessions that could have used Sonnet).
 </p>
 
 One row per AI-coding session. Each session has a stable ID, a tool
-(claude-code / cursor / codex / cline / copilot / opencode / openclaw /
-pi / antigravity / gemini-cli), a working-directory project, action
+(claude-code / cursor / codex / cline / cline-cli / copilot / copilot-cli /
+opencode / openclaw / pi / antigravity / gemini-cli / hermes /
+kilo-code / kilo-code-cli), a working-directory project, action
 count, sub-agent action count (when the session spawned sub-agents via
 the `Agent` tool), per-session **Tokens** and **Cost** columns, and —
 if `observer score` has run — quality / errors / redundancy ratios. The `~` suffix on Cost flags rows whose pricing
@@ -817,8 +820,9 @@ dashboard) has the full versions with cross-links.
   changed between reads. Cross-session reads are excluded (a fresh
   session has no memory of a prior session's read).
 - **Tool** — in this dashboard, "tool" means the *AI client*
-  (claude-code, cursor, codex, cline, copilot, opencode, openclaw,
-  pi, antigravity, gemini-cli), not the per-tool name (`read_file`,
+  (claude-code, cursor, codex, cline, cline-cli, copilot, copilot-cli,
+  opencode, openclaw, pi, antigravity, gemini-cli, hermes, kilo-code,
+  kilo-code-cli), not the per-tool name (`read_file`,
   `run_command`). The latter is "Tool name" on the Actions tab.
 - **Tool-pair integrity** — Anthropic requires every `tool_result`
   block to have a corresponding `tool_use` block in a preceding

package/README.template.md

@@ -0,0 +1,299 @@
+# @superbased/observer
+
+[![npm](https://img.shields.io/npm/v/@superbased/observer.svg)](https://www.npmjs.com/package/@superbased/observer)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+[![Platforms: Linux • macOS • Windows](https://img.shields.io/badge/platforms-linux%20%7C%20macos%20%7C%20windows-blue.svg)](https://github.com/marmutapp/superbased-observer)
+
+**Capture, normalize, compress, and analyze every AI coding tool call you
+run** — across Claude Code, Codex, Cursor, Cline / Roo Code, GitHub
+Copilot (VS Code), GitHub Copilot CLI, OpenCode, OpenClaw, Pi, Google
+Antigravity, Gemini CLI, and Cowork — in one local single-binary tool.
+No telemetry, no cloud, no data leaves your machine.
+
+<p align="center">
+  <img src="https://github.com/marmutapp/superbased-observer/raw/main/docs/assets/infographics/one-local-path.png" alt="One local path for AI coding activity" width="780">
+</p>
+
+# Table of contents
+
+- [Install](#install)
+- [Five-minute quickstart](#five-minute-quickstart)
+- [Per-AI-client setup](#per-ai-client-setup)
+- [Architecture in detail](#architecture-in-detail)
+- [Dashboard tour](#dashboard-tour)
+- [MCP tools reference](#mcp-tools-reference)
+- [Compression mechanisms](#compression-mechanisms)
+- [Cost and token math](#cost-and-token-math)
+- [Terminology and glossary](#terminology-and-glossary)
+- [CLI reference](#cli-reference)
+- [Configuration](#configuration)
+- [Troubleshooting](#troubleshooting)
+- [Security and privacy](#security-and-privacy)
+- [Source, contributing, license](#source-contributing-license)
+
+
+## Install
+
+**Use a global install** (`-g`) so the `observer` command is available
+on your `$PATH` from any directory:
+
+```bash
+npm install -g @superbased/observer
+observer --version
+```
+
+If you install locally (without `-g`) the binary lives at
+`./node_modules/.bin/observer` and isn't on your `$PATH`. Run it
+with `npx`:
+
+```bash
+npm install @superbased/observer    # local install
+npx observer --version              # ↑ what to use everywhere `observer` is shown below
+```
+
+A note for shared / CI machines where `npm install -g` may need
+`sudo`: see [Troubleshooting → EACCES](#npm-install--g-fails-with-eacces-permission-denied)
+for user-writable-prefix and version-manager fixes.
+
+> **Python users:** `pip install superbased-observer` ships the
+> same binary; version numbers are kept in lock-step. See
+> [the PyPI page](https://pypi.org/project/superbased-observer/).
+> Don't install both globally — whichever directory comes first on
+> `$PATH` wins, which gets confusing if their versions drift.
+
+Pre-built binaries ship for:
+
+| Platform              | Architecture |
+|-----------------------|--------------|
+| Linux                 | x64, arm64   |
+| macOS (Intel)         | x64          |
+| macOS (Apple Silicon) | arm64        |
+| Windows               | x64          |
+
+The package uses the `optionalDependencies`-per-platform pattern (same
+shape as `esbuild` / `swc` / `@biomejs/biome`) — only the binary
+matching your machine downloads. No postinstall network calls, no
+compile step.
+
+If your platform isn't listed, build from source — instructions in
+the [main repo](https://github.com/marmutapp/superbased-observer).
+
+
+## Five-minute quickstart
+
+```bash
+# 1) Install. `observer init` is OPTIONAL — only run it if you want
+#    the MCP server registered with your AI clients (gives them
+#    on-demand tools like check_file_freshness / get_cost_summary
+#    at the cost of ~1,800 tokens of schema per turn).
+npm install -g @superbased/observer
+observer init                 # OPTIONAL — interactive: pick clients;
+                              # writes MCP + codex proxy-route into AI client configs.
+                              # Skip this step for an MCP-free install.
+
+# 2) Start the long-running services (proxy + watcher + dashboard).
+#    Auto-registers HOOKS for every detected AI tool on first launch.
+observer start &
+
+# 3) Engage the proxy by pointing your AI client at the local URL.
+#    See "Per-AI-client setup" for the matching env var.
+export ANTHROPIC_BASE_URL=http://127.0.0.1:8820     # Claude Code
+export OPENAI_BASE_URL=http://127.0.0.1:8820/v1     # Codex / OpenAI
+
+# 4) Open the dashboard.
+open http://127.0.0.1:8081/   # macOS
+xdg-open http://127.0.0.1:8081/   # Linux
+start http://127.0.0.1:8081/   # Windows
+```
+
+**What `start` does vs what `init` adds:**
+
+| Step | Hooks | Proxy listening | Watcher | Dashboard | MCP in AI clients | Codex proxy route |
+|---|---|---|---|---|---|---|
+| `observer start` alone | auto-registers ✓ | ✓ | ✓ | ✓ | — | — |
+| `observer init` + `observer start` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `observer init --skip-mcp` + `start` | ✓ | ✓ | ✓ | ✓ | — | ✓ |
+
+MCP and codex routing are explicit-only because both write per-client
+config files. Hooks self-heal on every `start`.
+
+After ten minutes of normal AI-coding usage, the dashboard will be
+populated with cost over time, per-tool activity, compression
+savings, and stale-reread waste signals.
+
+
+<!-- @@INCLUDE:docs/distribution/README-body.md@@ -->
+
+
+## Troubleshooting
+
+### `npm install -g` fails with `EACCES: permission denied`
+
+Default npm puts globals under `/usr/local/lib/node_modules` which
+Homebrew-managed Node owns as root on macOS. Three fixes; pick one:
+
+```bash
+# 1) RECOMMENDED — point npm at a user-writable prefix.
+mkdir -p ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
+source ~/.zshrc
+npm install -g @superbased/observer
+
+# 2) Use a Node version manager — fnm / nvm install Node into your
+#    home directory and dodge the permission issue entirely.
+brew install fnm
+fnm install --lts
+npm install -g @superbased/observer
+
+# 3) sudo (works but you'll fight permissions on every update).
+sudo npm install -g @superbased/observer
+```
+
+### `observer: command not found` after install
+
+The shim binary is at `~/.npm-global/bin/observer` (or wherever your
+npm prefix points). Make sure that directory is on `$PATH`:
+
+```bash
+echo $PATH | tr ':' '\n' | grep -E 'npm|node'
+# add the prefix's bin/ to PATH if missing — see fix above
+```
+
+If you installed only a platform package (e.g. `@superbased/observer-darwin-x64`)
+without the main `@superbased/observer`, the shim doesn't get created
+— there's no `bin` field. Install the main package; npm picks up the
+right platform binary automatically via `optionalDependencies`.
+
+### `observer init` says "no tools selected and none auto-detected"
+
+Auto-detection looks for the AI clients' default session-log dirs
+(`~/.claude/projects/`, `~/.codex/sessions/`, `~/.cursor/`, etc.).
+On a fresh machine where no client has run yet, those dirs don't
+exist. Pass the flag explicitly:
+
+```bash
+observer init --claude-code     # or --codex / --cursor / --cline / --all
+```
+
+This registers hooks regardless — the next time the client runs,
+its dirs get created and the watcher picks them up.
+
+### Empty dashboard / "No proxy traffic"
+
+The JSONL adapter populates passively after `observer init`, but
+ground-truth cost / compression numbers require the proxy. Set
+`ANTHROPIC_BASE_URL=http://127.0.0.1:8820` (Claude Code) or
+`OPENAI_BASE_URL=http://127.0.0.1:8820/v1` (Codex) in the shell
+that launches your AI client.
+
+Verify with `observer status | grep api_turns` — count should
+climb during AI-client activity.
+
+### `observer --version` says `dev`
+
+You're on a non-released build. Reinstall with `npm install -g @superbased/observer` or rebuild with the workflow's `-X main.version=$VERSION` ldflag.
+
+### `tool_result block must have a corresponding tool_use block`
+
+Anthropic 400. Means the conversation-compression pipeline dropped
+a `tool_use` while keeping its matching `tool_result`. Versions
+prior to 1.3.2 had this bug; upgrade. If you're on 1.3.2+ and still
+see it, file an issue with the conversation prefix.
+
+### `tool use concurrency issues`
+
+Anthropic 400 surfaced in Claude Code as this message. Means the
+parallel-tool-use case (multiple `tool_use` blocks in one assistant
+message) isn't paired correctly with the multi-block tool_result
+that follows. Versions prior to 1.3.2 had this bug; upgrade.
+
+### Cross-thread numbers are 0
+
+Pre-migration data was ingested without the `is_sidechain` flag.
+Run `observer backfill --is-sidechain` once to re-walk JSONL and
+populate the flag on existing rows.
+
+### Migration error: `duplicate column name`
+
+Race condition between concurrent daemon startups, fixed in 1.4.1.
+Upgrade. If you still see it, run daemons serially: `observer
+watch`, wait, then `observer dashboard`, then `observer proxy
+start` (or just use `observer start` which runs all three in one
+process — proxy + watcher + dashboard).
+
+### `observer start` log says only `proxy + observer` — no `:8081`
+
+You're on a pre-1.4.7 build. Earlier versions ran only proxy +
+watcher under `observer start`; the dashboard had to be started
+separately via `observer dashboard --addr 127.0.0.1:8081`. Upgrade
+to 1.4.7+ — the dashboard goroutine is now part of `observer start`
+and the log line confirms all three: `proxy <addr> + watcher +
+dashboard http://127.0.0.1:8081`. Pass `--no-dashboard` to opt out.
+
+### "address already in use" on port 8820
+
+Another `observer proxy start` or `observer start` is still running.
+Find it with `pgrep -af 'observer (proxy|start)'` and `kill <pid>`.
+On macOS:
+
+```bash
+lsof -nP -iTCP:8820 -sTCP:LISTEN
+kill <pid>
+```
+
+### Dashboard port already in use
+
+```bash
+observer dashboard --addr 127.0.0.1:8082    # pick a different port
+# or
+[dashboard]
+port = 8082                                  # in config.toml
+```
+
+
+## Security and privacy
+
+**Local-only. No telemetry. No remote anything.** The watcher, hook
+handler, dashboard, MCP server, and CLI never make an outbound network
+call on observer's behalf. The only code paths that touch the network
+are the optional API proxy (which forwards **your** requests unchanged
+to the AI provider you already use) and a handful of explicit opt-in
+features (message-summary LLM, codegraph MCP, Teams org-server).
+
+The full privacy statement — what observer stores, what it reads,
+what it never stores, the explicit list of outbound-network call sites
+gated behind config, and how to verify "no telemetry" yourself with
+`grep`, `strings`, and a network-namespaced shell — lives in
+[`PRIVACY.md`](https://github.com/marmutapp/superbased-observer/blob/main/PRIVACY.md).
+
+Operational shorthand:
+
+- **Local-only HTTP.** The proxy and dashboard bind to `127.0.0.1`
+  by default. Don't bind to `0.0.0.0` unless you've thought about
+  it — there's no auth.
+- **Secrets scrubbing.** Tool inputs and outputs pass through
+  `internal/scrub/` before persistence; review the regex set if your
+  secrets follow non-default formats.
+- **Database.** `~/.observer/observer.db` is a SQLite file with the
+  same security posture as your `~/.claude/` and `~/.codex/` session
+  logs (which already hold the same content). Encrypt the disk if
+  your threat model needs that.
+- **Full delete.** `rm -rf ~/.observer/` removes everything observer
+  ever stored — no traces elsewhere on your system.
+
+
+## Source, contributing, license
+
+- **Source**: https://github.com/marmutapp/superbased-observer
+- **Specification**: `superbased-final-spec-v2.md` in the repo
+- **Issues**: https://github.com/marmutapp/superbased-observer/issues
+- **License**: [Apache 2.0](https://github.com/marmutapp/superbased-observer/blob/main/LICENSE)
+- **Author**: Santosh Kathira <contact@marmut.app>
+
+This npm package is a thin Node.js shim that resolves the right
+pre-built binary at runtime and spawns it. Same shape as `esbuild` /
+`swc` / `@biomejs/biome`. The Go source lives in the main repo;
+binaries are cross-compiled per release tag via GitHub Actions and
+published as `@superbased/observer-<platform>-<arch>` per-platform
+packages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superbased/observer",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "SuperBased Observer — capture, normalize, compress, and analyze AI coding tool activity across Claude Code, Codex, Cursor, Cline/Roo, and Copilot.",
   "keywords": [
     "ai",
@@ -36,11 +36,11 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@superbased/observer-linux-x64": "1.8.0",
-    "@superbased/observer-linux-arm64": "1.8.0",
-    "@superbased/observer-darwin-x64": "1.8.0",
-    "@superbased/observer-darwin-arm64": "1.8.0",
-    "@superbased/observer-win32-x64": "1.8.0"
+    "@superbased/observer-linux-x64": "1.8.2",
+    "@superbased/observer-linux-arm64": "1.8.2",
+    "@superbased/observer-darwin-x64": "1.8.2",
+    "@superbased/observer-darwin-arm64": "1.8.2",
+    "@superbased/observer-win32-x64": "1.8.2"
   },
   "scripts": {
     "test": "node bin/observer.js --version"