@superbased/observer 1.6.23 → 1.6.25

package/README.md

@@ -76,13 +76,18 @@ the [main repo](https://github.com/marmutapp/superbased-observer).
 ## Five-minute quickstart
 
 ```bash
-# 1) Install + register hooks with whichever AI clients you use.
+# 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                 # interactive: pick clients
+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 (watcher + dashboard + proxy).
-observer start &              # all three in one process
-                              # (or run them separately, see CLI ref)
+# 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.
@@ -95,6 +100,17 @@ 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.
@@ -120,8 +136,9 @@ env var that matches your client(s); both can coexist on one machine.
 | **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`. |
 | **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 (always-on,
-no setup beyond `observer init`). You won't see real-time cost numbers
+**JSONL-only** clients are captured passively by the watcher whenever
+`observer start` is running. Hooks self-heal on every `start`, so a
+fresh install captures the JSONL side without any `init` step. You won't see real-time cost numbers
 for them on the Compression tab (those need the proxy), but every tool
 call shows up on Sessions / Actions / Discovery / Tools / Patterns and
 the JSONL-derived token counts feed the Cost tab. Reliability tagging
@@ -177,8 +194,9 @@ Watch `~/.claude/projects/`, `~/.codex/sessions/`,
 (and the matching Antigravity index `state.vscdb`), etc. for new
 session log lines. Normalize per-client tool names to a shared
 taxonomy (`read_file`, `run_command`, `spawn_subagent`, …) and write
-them into the actions table. **Always-on**, no setup required —
-`observer init` registers the hooks once.
+them into the actions table. Active whenever `observer start` is
+running; hooks self-heal on each start so no separate `init` step is
+required for capture.
 
 For Antigravity (which stores conversations as encrypted protobufs),
 observer ships a per-OS `oscrypt` key fetcher (Chromium Safe Storage
@@ -231,14 +249,23 @@ Compression, Discovery, Patterns. See [Dashboard tour](#dashboard-tour).
 
 Static HTML + Chart.js. No analytics, no external requests.
 
-### 5. MCP server (stdio)
+### 5. MCP server (stdio) — opt-in via `observer init`
 
-12 read-only tools the AI client itself can call mid-conversation —
+13 read-only tools the AI client itself can call mid-conversation —
 `check_file_freshness`, `get_last_test_result`, `search_past_outputs`,
-etc. Powers cross-client tool sharing: if Claude Code ran `go test`,
+etc. (plus `retrieve_stashed` when the proxy stash is configured).
+Powers cross-client tool sharing: if Claude Code ran `go test`,
 Cursor's MCP query for the latest test result will return Claude
 Code's run. See [MCP tools reference](#mcp-tools-reference).
 
+**Lifecycle**: the MCP server is a stdio subprocess spawned by your
+AI tool — not by the observer daemon. It's registered into each AI
+client's MCP config only when you run `observer init`. `observer
+start` alone does NOT register the MCP server. Adds roughly 1,800
+tokens of tool-schema overhead per AI-client turn; opt out with
+`observer init --skip-mcp` (registers hooks only) or by simply not
+running `init`.
+
 
 ## Dashboard tour
 
@@ -469,10 +496,13 @@ explaining the actual algorithm.
 
 ## MCP tools reference
 
-Every AI client running through `observer init` gets these 12 tools
-registered as an MCP server. They're **read-only** queries against
-the unified database, so any agent can read any other agent's
-recorded work — true cross-platform tool-call sharing.
+Once you've run `observer init` (it's opt-in — `observer start`
+alone does NOT register the MCP server), every connected AI client
+gets these 13 tools registered as an MCP server — plus
+`retrieve_stashed` when the proxy stash is configured. They're
+**read-only** queries against the unified database, so any agent
+can read any other agent's recorded work — true cross-platform
+tool-call sharing.
 
 | Tool                              | Purpose |
 |-----------------------------------|---------|
@@ -488,10 +518,18 @@ recorded work — true cross-platform tool-call sharing.
 | `get_project_patterns`            | High-confidence patterns derived from this project's history |
 | `get_cost_summary`                | Daily / per-model / per-session cost rollups |
 | `get_redundancy_report`           | Stale rereads, repeated commands, cross-tool overlap for the project |
+| `list_actions_around`             | ±N actions adjacent to a pivot `action_id` — browse a session's local timeline cheaply |
+| `retrieve_stashed` _(conditional)_| Pulls original bytes of a tool_result the proxy compressed away. Only registered when `[compression.conversation].stash` is configured. |
+
+**Cost trade-off**: with the MCP registered, the AI client sends the
+full tool-schema payload (~7.2 KB / ~1,800 tokens) in its system
+context on every turn — whether or not the model actually invokes
+any tool. To eliminate this overhead, run `observer init --skip-mcp`
+(registers hooks only) or skip `init` entirely.
 
 **Cross-tool sharing**: when `observer init` registers the MCP server
 with Claude Code AND Cursor (and Codex…), all of them call the same
-12 tools against the same database. Cursor's `get_last_test_result`
+tools against the same database. Cursor's `get_last_test_result`
 returns Claude Code's last test run; Codex's `check_file_freshness`
 reflects edits made by Cursor.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superbased/observer",
-  "version": "1.6.23",
+  "version": "1.6.25",
   "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.6.23",
-    "@superbased/observer-linux-arm64": "1.6.23",
-    "@superbased/observer-darwin-x64": "1.6.23",
-    "@superbased/observer-darwin-arm64": "1.6.23",
-    "@superbased/observer-win32-x64": "1.6.23"
+    "@superbased/observer-linux-x64": "1.6.25",
+    "@superbased/observer-linux-arm64": "1.6.25",
+    "@superbased/observer-darwin-x64": "1.6.25",
+    "@superbased/observer-darwin-arm64": "1.6.25",
+    "@superbased/observer-win32-x64": "1.6.25"
   },
   "scripts": {
     "test": "node bin/observer.js --version"