@superbased/observer 1.34.0 → 1.36.0
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.
- package/README.md +69 -1622
- package/README.template.md +28 -312
- package/bin/postinstall.js +156 -0
- package/package.json +21 -14
package/README.md
CHANGED
|
@@ -1,1657 +1,104 @@
|
|
|
1
1
|
# @superbased/observer
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](https://www.apache.org/licenses/LICENSE-2.0)
|
|
5
|
-
[](https://github.com/superbasedapp/observer)
|
|
6
|
-
[](https://superbased.app/)
|
|
7
|
-
|
|
8
|
-
**Homepage:** [https://superbased.app/](https://superbased.app/)
|
|
3
|
+
<img src="https://raw.githubusercontent.com/superbasedapp/observer/main/vscode/media/logo-dark.png" alt="SuperBased logo" height="56">
|
|
9
4
|
|
|
10
|
-
**
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
coding tool call across **40 adapters** — Claude Code, Codex, Cursor,
|
|
14
|
-
Cline + Cline CLI, GitHub Copilot (VS Code) + Copilot CLI, Gemini CLI,
|
|
15
|
-
OpenCode, Google Antigravity, Cowork, Nous Research's Hermes Agent,
|
|
16
|
-
Kilo Code (legacy IDE extension + CLI), Aider, Goose, Devin, OpenClaw,
|
|
17
|
-
Pi, Factory Droid, Open Interpreter, Command Code, and more — in one
|
|
18
|
-
local single-binary tool. An optional API proxy
|
|
19
|
-
reconciles the *exact* tokens your provider billed (net input, cache
|
|
20
|
-
5m/1h splits, reasoning tokens, long-context surcharges) instead of a
|
|
21
|
-
JSONL-derived estimate. No telemetry and no cloud by default - nothing
|
|
22
|
-
leaves your machine unless you explicitly opt in to the sign-in beta.
|
|
5
|
+
**Local-first observability for AI coding agents.** See what Claude Code, Codex, Cursor and every
|
|
6
|
+
other coding agent you run really cost, from the tokens your provider actually billed. On your own
|
|
7
|
+
machine, with no account.
|
|
23
8
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
9
|
+
[](https://www.npmjs.com/package/@superbased/observer)
|
|
10
|
+
[](https://github.com/superbasedapp/observer/blob/main/LICENSE)
|
|
11
|
+
[](https://superbased.app/)
|
|
27
12
|
|
|
28
|
-
|
|
29
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/infographics/one-local-path.png" alt="One local path for AI coding activity" width="780">
|
|
30
|
-
</p>
|
|
13
|
+

|
|
31
14
|
|
|
32
|
-
|
|
15
|
+
## Try it without installing
|
|
33
16
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
- [One local binary](#one-local-binary)
|
|
38
|
-
- [Per-AI-client setup](#per-ai-client-setup)
|
|
39
|
-
- [Architecture in detail](#architecture-in-detail)
|
|
40
|
-
- [Dashboard tour](#dashboard-tour)
|
|
41
|
-
- [Terminals — launch, join, and track your AI CLIs](#terminals--launch-join-and-track-your-ai-clis)
|
|
42
|
-
- [MCP tools reference](#mcp-tools-reference)
|
|
43
|
-
- [Compression mechanisms](#compression-mechanisms)
|
|
44
|
-
- [Cost and token math](#cost-and-token-math)
|
|
45
|
-
- [Terminology and glossary](#terminology-and-glossary)
|
|
46
|
-
- [CLI reference](#cli-reference)
|
|
47
|
-
- [Configuration](#configuration)
|
|
48
|
-
- [Troubleshooting](#troubleshooting)
|
|
49
|
-
- [Security and privacy](#security-and-privacy)
|
|
50
|
-
- [Source, contributing, license](#source-contributing-license)
|
|
17
|
+
```bash
|
|
18
|
+
npx @superbased/observer
|
|
19
|
+
```
|
|
51
20
|
|
|
21
|
+
Reads the session logs your coding agents already keep on disk, prints a 30-day cost table by tool
|
|
22
|
+
and model, and deletes its temporary database on exit. No config, no network.
|
|
52
23
|
|
|
53
24
|
## Install
|
|
54
25
|
|
|
55
|
-
**Use a global install** (`-g`) so the `observer` command is available
|
|
56
|
-
on your `$PATH` from any directory:
|
|
57
|
-
|
|
58
26
|
```bash
|
|
59
27
|
npm install -g @superbased/observer
|
|
60
28
|
observer --version
|
|
61
29
|
```
|
|
62
30
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
npm install @superbased/observer # local install
|
|
69
|
-
npx observer --version # ↑ what to use everywhere `observer` is shown below
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
A note for shared / CI machines where `npm install -g` may need
|
|
73
|
-
`sudo`: see [Troubleshooting → EACCES](#npm-install--g-fails-with-eacces-permission-denied)
|
|
74
|
-
for user-writable-prefix and version-manager fixes.
|
|
31
|
+
Prebuilt binaries for Linux (x64, arm64), macOS (Intel, Apple Silicon) and Windows x64. npm fetches
|
|
32
|
+
only the one for your machine; there is no compile step and no postinstall download. Also on
|
|
33
|
+
[PyPI](https://pypi.org/project/superbased-observer/) and the
|
|
34
|
+
[VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=superbased.superbased-observer)
|
|
35
|
+
with the same version numbers; install from one channel only.
|
|
75
36
|
|
|
76
|
-
|
|
77
|
-
> same binary; version numbers are kept in lock-step. See
|
|
78
|
-
> [the PyPI page](https://pypi.org/project/superbased-observer/).
|
|
79
|
-
> Don't install both globally — whichever directory comes first on
|
|
80
|
-
> `$PATH` wins, which gets confusing if their versions drift.
|
|
37
|
+
## Why SuperBased
|
|
81
38
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
| Platform | Architecture |
|
|
85
|
-
|-----------------------|--------------|
|
|
86
|
-
| Linux | x64, arm64 |
|
|
87
|
-
| macOS (Intel) | x64 |
|
|
88
|
-
| macOS (Apple Silicon) | arm64 |
|
|
89
|
-
| Windows | x64 |
|
|
90
|
-
|
|
91
|
-
The package uses the `optionalDependencies`-per-platform pattern (same
|
|
92
|
-
shape as `esbuild` / `swc` / `@biomejs/biome`) — only the binary
|
|
93
|
-
matching your machine downloads. No postinstall network calls, no
|
|
94
|
-
compile step.
|
|
95
|
-
|
|
96
|
-
If your platform isn't listed, build from source — instructions in
|
|
97
|
-
the [main repo](https://github.com/superbasedapp/observer).
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
## Five-minute quickstart
|
|
101
|
-
|
|
102
|
-
**No install at all, just a cost table:**
|
|
103
|
-
|
|
104
|
-
```bash
|
|
105
|
-
npx @superbased/observer # a 30-day cost table, right now
|
|
106
|
-
npx @superbased/observer usage # the explicit, same-thing form
|
|
107
|
-
```
|
|
39
|
+
**One local binary that tracks Claude Code token usage, Codex cost and Cursor spend side by side,
|
|
40
|
+
and helps you control them.**
|
|
108
41
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
no
|
|
114
|
-
|
|
42
|
+
- **Provider-exact cost, not estimates.** An optional local proxy records the tokens your provider
|
|
43
|
+
returned: net input, 5-minute vs 1-hour cache writes, reasoning tokens and long-context repricing.
|
|
44
|
+
- **Every coding agent in one place.** 40 adapters normalize Claude Code, Codex, Cursor, GitHub
|
|
45
|
+
Copilot, Gemini CLI, Cline, Aider, Kiro, Devin, OpenCode, Junie and more into one local database.
|
|
46
|
+
- **Local-first, no account.** No telemetry and no sign-in. Everything lives in one SQLite file
|
|
47
|
+
under `~/.observer/`.
|
|
48
|
+
- **Know the next bill before it lands.** Prompt-cache tracking with expiry warnings, a cost band
|
|
49
|
+
for your next message, and a 5-hour and weekly limit gauge for proxied sessions.
|
|
50
|
+
- **Guardrails on your own agents.** Built-in and custom rules for destructive commands, secrets
|
|
51
|
+
egress, MCP pinning and budgets. Observe mode by default; `observer guard simulate` first.
|
|
52
|
+
- **Your agents as terminals.** Launch agent CLIs from the dashboard, join a running session from a
|
|
53
|
+
paired device over your Tailscale tailnet, and hand a session from one tool to another.
|
|
115
54
|
|
|
116
|
-
|
|
117
|
-
conversation compression, cache tracking:
|
|
55
|
+
## Get started
|
|
118
56
|
|
|
119
57
|
```bash
|
|
120
|
-
#
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
# 2) Start everything: proxy + watcher + dashboard in one process.
|
|
124
|
-
# Hooks auto-register for every detected AI tool, and the
|
|
125
|
-
# dashboard opens in your browser (suppress with --no-open).
|
|
126
|
-
observer start
|
|
127
|
-
```
|
|
128
|
-
|
|
129
|
-
From here the dashboard drives:
|
|
130
|
-
|
|
131
|
-
3. **Route your AI client through the proxy** — on the Compression
|
|
132
|
-
tab's **Proxy** banner, click your tool's status pill, then
|
|
133
|
-
**Route through the observer proxy…**. The button previews the
|
|
134
|
-
exact file change and writes only on confirm. (Every other
|
|
135
|
-
routing mechanism — `observer init`, the `observer claude` /
|
|
136
|
-
`observer codex` wrappers, plain env vars — is listed in
|
|
137
|
-
[Per-AI-client setup](#per-ai-client-setup).)
|
|
138
|
-
4. **Use your AI tool as normal.** The Overview tab's onboarding
|
|
139
|
-
checklist tracks your first captured session; cost, compression,
|
|
140
|
-
and cache numbers populate within minutes of real activity.
|
|
141
|
-
|
|
142
|
-
`observer init` is OPTIONAL — run it only if you want the MCP server
|
|
143
|
-
registered with your AI clients (gives them on-demand tools like
|
|
144
|
-
`check_file_freshness` / `get_cost_summary`, at the cost of ~1,800
|
|
145
|
-
tokens of schema per turn). Skip it for an MCP-free install.
|
|
146
|
-
|
|
147
|
-
**What `start` does vs what `init` adds:**
|
|
148
|
-
|
|
149
|
-
| Step | Hooks | Proxy listening | Watcher | Dashboard | MCP in AI clients | Codex proxy route |
|
|
150
|
-
|---|---|---|---|---|---|---|
|
|
151
|
-
| `observer start` alone | auto-registers ✓ | ✓ | ✓ | ✓ | — | — |
|
|
152
|
-
| `observer init` + `observer start` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
153
|
-
| `observer init --skip-mcp` + `start` | ✓ | ✓ | ✓ | ✓ | — | ✓ |
|
|
154
|
-
|
|
155
|
-
MCP and codex routing are explicit-only because both write per-client
|
|
156
|
-
config files. Hooks self-heal on every `start`.
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
## Zero-setup cost report: `observer usage`
|
|
160
|
-
|
|
161
|
-
Before `observer start` and the daemon, there's a one-shot path for
|
|
162
|
-
"how much have I spent so far": `observer usage` reads each detected
|
|
163
|
-
AI tool's own local session files (JSONL / SQLite — the same files
|
|
164
|
-
the watcher normally tails), rolls up the last 30 days into one
|
|
165
|
-
tool × model cost table, and prints it. Everything it reads goes into
|
|
166
|
-
a throwaway database in a temp directory (foreign-mount adapter
|
|
167
|
-
mirrors — e.g. WSL reading a Windows-side tool store — land there too),
|
|
168
|
-
deleted again when the command exits — it never creates or touches
|
|
169
|
-
`~/.observer`, never writes any AI tool's config, and never opens a
|
|
170
|
-
socket. Pricing is embedded in the binary (the same rate sheet the
|
|
171
|
-
dashboard's Cost tab uses), so the whole run makes zero network calls.
|
|
172
|
-
|
|
173
|
-
On a fresh machine with no SuperBased state yet — no
|
|
174
|
-
`~/.observer/observer.db` and no `~/.observer/config.toml` — running
|
|
175
|
-
bare `observer` with no arguments runs this same report instead of the
|
|
176
|
-
usual welcome screen. Set `OBSERVER_ONESHOT=off` to always get the
|
|
177
|
-
welcome screen instead; a default-config daemon can't run without
|
|
178
|
-
first creating one of those two files, so there's no separate "is a
|
|
179
|
-
daemon listening" check — no port probe, no network activity at all.
|
|
180
|
-
Once either file exists on the machine, the fallthrough stops firing
|
|
181
|
-
on its own and bare `observer` goes back to the welcome screen —
|
|
182
|
-
`observer usage` stays available as an explicit command regardless.
|
|
183
|
-
|
|
184
|
-
The report is honest about its own limits: reliability is **log
|
|
185
|
-
tier** — parsed from each tool's own self-reported counts, not the
|
|
186
|
-
wire-accurate numbers the proxy captures — and every dollar figure is
|
|
187
|
-
labeled `estimated list price, not invoiced`. When it's ready for
|
|
188
|
-
more, `observer start` is the next step: it keeps the proxy, the
|
|
189
|
-
watcher, and the dashboard running so cost, cache, and compression
|
|
190
|
-
numbers stay current instead of being recomputed from scratch on
|
|
191
|
-
every invocation.
|
|
192
|
-
|
|
193
|
-
Flags: `--since` (`7d`/`30d`/`90d`/`all`/an RFC3339 timestamp, default
|
|
194
|
-
`30d`), `--group-by` (`tool-model`/`tool`/`model`/`day`), `--tool`,
|
|
195
|
-
`--budget` (wall-clock cap on the scan only, default `30s`, `0` =
|
|
196
|
-
unlimited — on expiry the table still prints with a `partial:`
|
|
197
|
-
footer), `--json`, and `--keep-db <path>` to keep the scratch database
|
|
198
|
-
instead of deleting it. See `observer usage --help` for the full
|
|
199
|
-
reference.
|
|
200
|
-
|
|
201
|
-
## A wordmarked one-line status: `observer statusline`
|
|
202
|
-
|
|
203
|
-
For an always-on glance instead of an on-demand report, `observer
|
|
204
|
-
statusline` prints exactly one line — a short `▞ superbased` wordmark plus
|
|
205
|
-
(when the data is available that invocation) the current session's
|
|
206
|
-
cost, today's total observed spend, and the active model name — sized
|
|
207
|
-
for a terminal prompt (Claude Code's `statusLine` contract) or any host
|
|
208
|
-
tool that execs a command and reads its stdout. It's fail-open by
|
|
209
|
-
design: with no daemon running it degrades to the wordmark alone (and
|
|
210
|
-
makes no network call of any kind to find that out), and with a daemon
|
|
211
|
-
running the only network-shaped call it makes is a bounded loopback
|
|
212
|
-
request to that same-machine daemon. Every dollar figure is an
|
|
213
|
-
estimated list-price total, not an invoiced amount. Registration is
|
|
214
|
-
opt-in (`observer init --statusline`) — never automatic. See
|
|
215
|
-
[`docs/observer-statusline.md`](https://github.com/superbasedapp/observer/blob/main/docs/observer-statusline.md)
|
|
216
|
-
for the full reference.
|
|
217
|
-
|
|
218
|
-
## One local binary
|
|
219
|
-
|
|
220
|
-
Everything below this line (proxy routing, per-client capture,
|
|
221
|
-
compression, cache, MCP tools) is what this package is for: a local
|
|
222
|
-
node that watches your own AI coding tools and gives you
|
|
223
|
-
proxy-accurate cost and cache numbers, on your own machine.
|
|
224
|
-
|
|
225
|
-
## Per-AI-client setup
|
|
226
|
-
|
|
227
|
-
### Routing through the proxy — the canonical section
|
|
228
|
-
|
|
229
|
-
Accurate token counts, conversation compression, and cache tracking
|
|
230
|
-
all require your AI client to send its API traffic through the local
|
|
231
|
-
proxy on `127.0.0.1:8820`. There is one decision to make — *how* to
|
|
232
|
-
route — and four mechanisms that all end at the same proxy. Pick the
|
|
233
|
-
first one that fits:
|
|
234
|
-
|
|
235
|
-
| Mechanism | What it does | Use it when |
|
|
236
|
-
|---|---|---|
|
|
237
|
-
| **Dashboard button** *(recommended)* | On the Compression tab's **Proxy** banner, click your tool's status pill, then **Route through the observer proxy…**. It previews the exact file change and writes only on confirm: Claude Code gets `"env": { "ANTHROPIC_BASE_URL": … }` in `~/.claude/settings.json`; Codex gets an `observer` model provider in `~/.codex/config.toml`. Durable — every later session routes automatically, no wrapper, no env vars. Undo: remove the entry, or `observer uninstall --claude-code` / `--codex`. | You have a browser open. This is the default path. |
|
|
238
|
-
| **`observer init`** | Writes the same durable routing from the CLI, alongside hooks + MCP registration (each side defaults on; opt out with `--skip-hooks` / `--skip-mcp` / `--skip-proxy-route`). | Headless machines, scripted setups. |
|
|
239
|
-
| **Wrapper commands** — `observer claude` / `observer codex` | Launch the tool with routing injected for that session only; nothing is written to any config file. The claude wrapper also re-exports a fresh Pro/Max OAuth token so the SDK's OAuth path can't bypass the proxy (an expired stored token is left alone — Claude Code then refreshes natively). `observer claude --verify` runs the pre-flight checks without launching. | Trying the proxy out, or you don't want config writes. |
|
|
240
|
-
| **Env var export** | `export ANTHROPIC_BASE_URL=http://127.0.0.1:8820` (Anthropic clients) or `export OPENAI_BASE_URL=http://127.0.0.1:8820/v1` (OpenAI clients — note the `/v1`) in the shell that launches the tool. | One-off shells; clients without a button or wrapper. |
|
|
241
|
-
|
|
242
|
-
Routing is per-tool, not global: route Claude Code and Codex
|
|
243
|
-
independently, and both can coexist on one machine — the proxy
|
|
244
|
-
routes by URL path.
|
|
245
|
-
|
|
246
|
-
> **Claude Code + MCP servers**: set `ENABLE_TOOL_SEARCH=true` in the
|
|
247
|
-
> same environment. Claude Code's SDK disables deferred MCP schema
|
|
248
|
-
> loading whenever `ANTHROPIC_BASE_URL` is set and eager-inlines every
|
|
249
|
-
> registered MCP schema (~+21K tokens/turn) — enough to turn the proxy
|
|
250
|
-
> into a net cost. The override restores lazy loading; the proxy
|
|
251
|
-
> forwards `tool_reference` blocks byte-identically.
|
|
252
|
-
|
|
253
|
-
> **If the daemon is down while a tool is routed**, Claude Code does
|
|
254
|
-
> not silently bypass to the real API — it retries the dead port
|
|
255
|
-
> (verified live: it hangs rather than failing over). `observer
|
|
256
|
-
> doctor` and the dashboard's Health panel flag this state as a
|
|
257
|
-
> "proxy routing gap"; bring the daemon back with `observer start`.
|
|
258
|
-
|
|
259
|
-
### Capture modes per client
|
|
260
|
-
|
|
261
|
-
The proxy covers the clients that speak the Anthropic / OpenAI wire
|
|
262
|
-
APIs. Everything else is captured passively from session logs. The
|
|
263
|
-
table below is the full per-client reference.
|
|
264
|
-
|
|
265
|
-
| AI client | Env var | Capture mode |
|
|
266
|
-
|---------------------------------|-------------------------------------------------------|--------------|
|
|
267
|
-
| **Claude Code** | `ANTHROPIC_BASE_URL=http://127.0.0.1:8820` | proxy + JSONL |
|
|
268
|
-
| **Cursor** (Anthropic mode) | `ANTHROPIC_BASE_URL=http://127.0.0.1:8820` | proxy + JSONL |
|
|
269
|
-
| **Codex** | `OPENAI_BASE_URL=http://127.0.0.1:8820/v1` (note `/v1`) | proxy + JSONL with API-key auth; ChatGPT-plan login currently behaves as JSONL only |
|
|
270
|
-
| **Cursor** (OpenAI mode) | `OPENAI_BASE_URL=http://127.0.0.1:8820/v1` | proxy + JSONL |
|
|
271
|
-
| **Cline (VS Code) / Roo Code** | `ANTHROPIC_BASE_URL=...` or `OPENAI_BASE_URL=...` per provider | proxy + JSONL |
|
|
272
|
-
| **Cline CLI** (npm `cline` 3.0.20+) | (no proxy route yet — the CLI ignores base-URL env vars; per-provider `baseUrl` overrides live in `~/.cline/data/settings/providers.json`, a credentials file only the operator should edit) | JSONL — SQLite session metadata at `~/.cline/data/db/sessions.db` (schema v1, 28 columns) plus per-session `<id>.messages.json` content blocks. Captures `user_prompt` / `assistant_text` / `tool_use` / paired `tool_result` rows + Tier 2 per-API-call token usage from `modelInfo` overrides. Subagent + team linkage via 5 new `ActionMetadata` fields (`ParentSessionID`, `ParentAgentID`, `AgentID`, `IsSubagent`, `TeamName`). 28-tool taxonomy (10 core + 18 `team_*` coordination primitives). WSL2 over `/mnt/c` uses the same `stageMirror` pattern as opencode/kilocode. Tagged `Source=jsonl, Reliability=approximate`. |
|
|
273
|
-
| **GitHub Copilot** | (no proxy yet) | JSONL only |
|
|
274
|
-
| **OpenCode** ([opencode.ai](https://opencode.ai/)) | (no proxy yet) | SQLite — actual install path is `~/.local/share/opencode/opencode.db` (XDG). Captures **token counts + model + cost** per assistant message from OpenCode's InfoData (`tokens.input/output/reasoning/cache.{read,write}` + `cost`); **subtask** parts → `spawn_subagent` actions; **todo** table → `todo_update` actions; tool-name coverage extended to webfetch/websearch/task/todowrite/todoread/multiedit. Tagged `Source=jsonl, Reliability=approximate`. |
|
|
275
|
-
| **OpenClaw** ([openclaw.ai](https://openclaw.ai/)) | (no proxy yet) | JSONL + sqlite — `~/.openclaw/tasks/runs.sqlite` + `~/.openclaw/agents/<agent>/sessions/sessions.json` |
|
|
276
|
-
| **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`. |
|
|
277
|
-
| **Google Antigravity** | (no proxy yet) | Encrypted protobuf — `~/.gemini/antigravity/conversations/*.pb` (Linux-native) and the matching Windows-side path on WSL2. SuperBased 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`. |
|
|
278
|
-
| **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`. |
|
|
279
|
-
| **Kilo Code CLI (current)** | (no proxy route yet — base-URL env vars are not honored; a project-scoped `kilo.json` provider `baseURL` override reaches the proxy, but the Gateway provider's model-catalog calls share that base URL and have no upstream there — see `docs/kilo-code-adapter.md`) | 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`. |
|
|
280
|
-
| **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`. |
|
|
281
|
-
| **Hermes Agent** ([Nous Research](https://github.com/NousResearch/hermes-agent)) | (provider-routed; uses your existing `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` when set) | Hooks + SQLite — Python plugin at `~/.hermes/plugins/superbased-observer/` registers `post_tool_call` / `post_api_request` / `on_session_start` / `on_session_end` / `subagent_stop` callbacks (fire-and-forget via `observer hook hermes`); the watcher walks `~/.hermes/state.db` (schema v14, `messages.active = 1` filter) and emits `ToolEvent` + `TokenEvent` rows via `modernc.org/sqlite`. 70+ Hermes tools fold into the normalized action set (`read_file` / `write_file` / `patch` / `terminal` / `search_files` / `web_search` / `web_extract` / `browser_*` / `delegate_task` / `todo` / `clarify` / `memory` + `mcp_call` fall-through). Token bundles lifted from `post_api_request.usage{input/output/cache/reasoning_tokens}`; OpenRouter `:suffix` tails (`:free`, `:beta`, `:fast`) preserved so the dashboard distinguishes paid vs free tiers. Install via `observer init --hermes`; backfill via `observer backfill --hermes-rescan`. Tagged `Source=jsonl, Reliability=approximate`. |
|
|
282
|
-
| **Junie** (JetBrains) | (no proxy yet) | Event-sourced JSONL — `~/.junie/sessions/<id>/events.jsonl` on every OS (resumes with `junie --session-id <id>`). Each line is a typed envelope (`SessionA2uxEvent` wrapping `event.agentEvent.kind`); Terminal/FileChanges/Result blocks recur under a stable `stepId` (IN_PROGRESS to COMPLETED/FAILED to a completion rebroadcast) and are collapsed by `stepId`. Captures user prompts, `run_command` / `write_file` / `edit_file` / `task_complete` actions, and per-call **model + NET input tokens + provider-stated cost** from `LlmResponseMetadataEvent.modelUsage[]`. Project root from the session's `CurrentDirectoryUpdatedEvent` with a `sessions/index.jsonl` `projectDir` fallback. Never reads `secure_credentials.json` / `trust/`. Tagged `Source=jsonl, Reliability=accurate`. |
|
|
283
|
-
|
|
284
|
-
**JSONL-only** clients are captured passively by the watcher whenever
|
|
285
|
-
`observer start` is running. Hooks self-heal on every `start`, so a
|
|
286
|
-
fresh install captures the JSONL side without any `init` step. You won't see real-time cost numbers
|
|
287
|
-
for them on the Compression tab (those need the proxy), but every tool
|
|
288
|
-
call shows up on Sessions / Actions / Discovery / Tools / Patterns and
|
|
289
|
-
the JSONL-derived token counts feed the Cost tab. Reliability tagging
|
|
290
|
-
is per-adapter: Claude Code emits `unreliable` (the JSONL stream uses
|
|
291
|
-
streaming-time placeholder counts per spec §24); Codex / Cline / Cline CLI /
|
|
292
|
-
Pi / OpenCode / OpenClaw / Antigravity / Gemini CLI / Hermes / Kilo Code / Kilo Code CLI emit `approximate`
|
|
293
|
-
(provider-reported usage that hasn't been reconciled against an
|
|
294
|
-
upstream invoice).
|
|
295
|
-
|
|
296
|
-
For **Codex specifically**, SuperBased currently has two practical support modes:
|
|
297
|
-
|
|
298
|
-
- `Proxy + JSONL`: Codex is routed through `OPENAI_BASE_URL=http://127.0.0.1:8820/v1` and SuperBased can link proxy turns to the session, so live compression metrics are available.
|
|
299
|
-
- `JSONL only`: SuperBased can still recover sessions, actions, and approximate token counts from `~/.codex/sessions`, but live proxy compression is currently not available when Codex is logged in with a ChatGPT plan on the local machine.
|
|
300
|
-
|
|
301
|
-
## Architecture in detail
|
|
302
|
-
|
|
303
|
-
<p align="center">
|
|
304
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/infographics/intelligence-across-tools.png" alt="Shared local intelligence layer across tools" width="780">
|
|
305
|
-
</p>
|
|
306
|
-
|
|
307
|
-
Five components running side by side:
|
|
308
|
-
|
|
309
|
-
### 1. JSONL adapters (passive ingest)
|
|
310
|
-
|
|
311
|
-
Watch `~/.claude/projects/`, `~/.codex/sessions/`,
|
|
312
|
-
`~/.gemini/tmp/.../chats/`, `~/.gemini/antigravity/conversations/`
|
|
313
|
-
(and the matching Antigravity index `state.vscdb`), etc. for new
|
|
314
|
-
session log lines. Normalize per-client tool names to a shared
|
|
315
|
-
taxonomy (`read_file`, `run_command`, `spawn_subagent`, …) and write
|
|
316
|
-
them into the actions table. Active whenever `observer start` is
|
|
317
|
-
running; hooks self-heal on each start so no separate `init` step is
|
|
318
|
-
required for capture.
|
|
319
|
-
|
|
320
|
-
For Antigravity (which stores conversations as encrypted protobufs),
|
|
321
|
-
observer ships a per-OS `oscrypt` key fetcher (Chromium Safe Storage
|
|
322
|
-
pattern: macOS Keychain / Linux libsecret + peanuts fallback / Windows
|
|
323
|
-
DPAPI / WSL2-via-PowerShell helper) plus a `language_server`-aware
|
|
324
|
-
gRPC fallback that calls `GetCascadeTrajectory` through the bundled
|
|
325
|
-
`antigravity-bridge.exe` when local decryption can't validate the
|
|
326
|
-
ciphertext. Tier 0–6 ToolEvents (file views, artifact edits/writes,
|
|
327
|
-
user prompts, assistant text, run_command terminal snapshots,
|
|
328
|
-
structured plan steps, final summaries) are extracted from the
|
|
329
|
-
trajectory's wire format without committing to specific .proto field
|
|
330
|
-
numbers.
|
|
331
|
-
|
|
332
|
-
What this gets you: every tool call you've ever run, queryable.
|
|
333
|
-
|
|
334
|
-
### 2. API reverse proxy (active capture)
|
|
335
|
-
|
|
336
|
-
A localhost HTTP server (`127.0.0.1:8820`) you point your AI client
|
|
337
|
-
at via `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL`. Intercepts every
|
|
338
|
-
request before it hits Anthropic / OpenAI and:
|
|
339
|
-
|
|
340
|
-
- Records exact token usage from the upstream `usage` envelope (the
|
|
341
|
-
most accurate cost source — proxy beats JSONL parsing here).
|
|
342
|
-
- Runs the **conversation compression pipeline** to trim large
|
|
343
|
-
`tool_result` blocks and drop low-importance messages before
|
|
344
|
-
forwarding upstream.
|
|
345
|
-
- Captures the `cost_usd` the upstream reports (when present).
|
|
346
|
-
|
|
347
|
-
What this gets you: ground-truth cost numbers and conversation
|
|
348
|
-
compression savings you can measure.
|
|
349
|
-
|
|
350
|
-
### 3. SQLite store
|
|
351
|
-
|
|
352
|
-
A single file at `~/.observer/observer.db`. Tables include:
|
|
353
|
-
|
|
354
|
-
- `projects`, `sessions`, `actions` — the taxonomy
|
|
355
|
-
- `api_turns` — one row per proxy-intercepted upstream request
|
|
356
|
-
- `token_usage` — JSONL-derived token-row events (deduped via spec §A1)
|
|
357
|
-
- `file_state` — content hashes for freshness classification
|
|
358
|
-
- `compression_events` — per-event compression detail (post-migration 010)
|
|
359
|
-
- `project_patterns` — derived patterns from `observer patterns`
|
|
360
|
-
- `failure_context`, `action_excerpts` — diagnostic data
|
|
361
|
-
|
|
362
|
-
Pure-Go via `modernc.org/sqlite`, no CGO. WAL mode by default.
|
|
363
|
-
|
|
364
|
-
### 4. Local dashboard (`:8081`)
|
|
365
|
-
|
|
366
|
-
Eighteen tabs in four groups — Monitor (Overview, Live, Sessions,
|
|
367
|
-
Actions, Trajectories, Evals, Security, Search), Analyze (Cost,
|
|
368
|
-
Analysis, Tools), Optimize (Compression, Cache, Suggestions,
|
|
369
|
-
Discovery, Patterns), Configure (Privacy, Settings). See
|
|
370
|
-
[Dashboard tour](#dashboard-tour).
|
|
371
|
-
|
|
372
|
-
A React + TypeScript single-page app (Vite build, Recharts charts),
|
|
373
|
-
embedded in the binary and served locally. No analytics, no external
|
|
374
|
-
requests.
|
|
375
|
-
|
|
376
|
-
### 5. MCP server (stdio) — opt-in via `observer init`
|
|
377
|
-
|
|
378
|
-
21 read-only tools are always registered — `check_file_freshness`,
|
|
379
|
-
`get_last_test_result`, `search_past_outputs`, `search_symbols`,
|
|
380
|
-
etc. — plus 4 more (`get_file`, `get_symbols`, `get_relations`,
|
|
381
|
-
`retrieve_stashed`) that register conditionally, only when the
|
|
382
|
-
capability they depend on (the proxy stash, or the codeintel index)
|
|
383
|
-
is actually configured.
|
|
384
|
-
Powers cross-client tool sharing: if Claude Code ran `go test`,
|
|
385
|
-
Cursor's MCP query for the latest test result will return Claude
|
|
386
|
-
Code's run. The code-aware tools (`get_symbols`, `get_relations`,
|
|
387
|
-
`search_symbols`) are backed by a native, CGO-free code-intelligence
|
|
388
|
-
engine (tree-sitter via wasm) that indexes your repo locally. See
|
|
389
|
-
[MCP tools reference](#mcp-tools-reference).
|
|
390
|
-
|
|
391
|
-
**Lifecycle**: the MCP server is a stdio subprocess spawned by your
|
|
392
|
-
AI tool — not by the observer daemon. It's registered into each AI
|
|
393
|
-
client's MCP config only when you run `observer init`. `observer
|
|
394
|
-
start` alone does NOT register the MCP server. Adds roughly 1,800
|
|
395
|
-
tokens of tool-schema overhead per AI-client turn; opt out with
|
|
396
|
-
`observer init --skip-mcp` (registers hooks only) or by simply not
|
|
397
|
-
running `init`.
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
## Dashboard tour
|
|
401
|
-
|
|
402
|
-
`observer start` opens the dashboard automatically on interactive
|
|
403
|
-
launches (suppress with `--no-open`; the URL is also printed —
|
|
404
|
-
`http://127.0.0.1:8081/` by default). Eighteen tabs in four nav groups
|
|
405
|
-
(Monitor / Analyze / Optimize / Configure) — the tour below covers the
|
|
406
|
-
core surfaces; Live (recent sessions with a real-time action feed),
|
|
407
|
-
Trajectories + Evals (OTLP trace/span capture for your own agents),
|
|
408
|
-
Search (full-text over captured tool outputs), and Privacy (capture
|
|
409
|
-
map + scrub tester) are self-explanatory once you're in. On an empty
|
|
410
|
-
database the Overview tab leads with a three-step onboarding
|
|
411
|
-
checklist that takes you from zero to your first captured session
|
|
412
|
-
without leaving the browser.
|
|
413
|
-
|
|
414
|
-
**Just looking?** The empty-database Overview also offers **demo
|
|
415
|
-
mode**: one click seeds a temporary synthetic dataset so every chart
|
|
416
|
-
and table renders with realistic data — parsed through the real
|
|
417
|
-
ingest pipeline into a temp DB; your real `observer.db` is never read
|
|
418
|
-
or written. A persistent banner marks demo state, and one click
|
|
419
|
-
clears it again. The fastest way to evaluate the dashboard before
|
|
420
|
-
routing any real traffic.
|
|
421
|
-
|
|
422
|
-
**Time windows.** Every page follows one window (1h / 12h / 1d / 7d /
|
|
423
|
-
14d / 30d / 90d / 1y / all, or Custom: a picker with one-click presets
|
|
424
|
-
such as Today or Last week, a month calendar and hour / minute
|
|
425
|
-
selects). Time-series charts bucket by that window in your browser's
|
|
426
|
-
time zone - 5 minutes up to 3 hours, hourly up to 7 days, daily up to
|
|
427
|
-
180 days, weekly beyond - and each chart has an Auto / 5 min / Hour /
|
|
428
|
-
Day / Week control; empty buckets are drawn as zero. A density toggle
|
|
429
|
-
switches tables between comfortable and compact.
|
|
430
|
-
|
|
431
|
-
### Overview tab
|
|
432
|
-
|
|
433
|
-
<p align="center">
|
|
434
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/screenshots/01-overview.png" alt="Overview tab" width="900">
|
|
435
|
-
</p>
|
|
436
|
-
|
|
437
|
-
High-level snapshot of the selected window:
|
|
438
|
-
|
|
439
|
-
- **KPI tiles**: Sessions count, API turns (proxy-captured), Token
|
|
440
|
-
rows (JSONL-recovered), Failures (24h)
|
|
441
|
-
- **Cost over time** chart — token volume per time bucket (following
|
|
442
|
-
the window), split into the four billable buckets (net input / cache
|
|
443
|
-
read / cache write / output)
|
|
444
|
-
- **Actions over time** chart — total actions vs failures
|
|
445
|
-
- **Top models (by tokens)** chart — top-8 models stacked by net
|
|
446
|
-
input / cache read / output
|
|
447
|
-
- **Top tools (actions over time)** — per-AI-client stacked-area
|
|
448
|
-
showing when each client is active
|
|
449
|
-
|
|
450
|
-
### Cost tab
|
|
451
|
-
|
|
452
|
-
<p align="center">
|
|
453
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/screenshots/04-cost.png" alt="Cost tab" width="900">
|
|
454
|
-
</p>
|
|
455
|
-
|
|
456
|
-
Per-model breakdown over the selected window. Tokens split into the
|
|
457
|
-
four billing buckets, with computed dollar cost and a reliability
|
|
458
|
-
flag. Cost is always computed locally as `tokens × pricing_table[model]`
|
|
459
|
-
— neither Anthropic nor OpenAI returns cost in their API responses, so
|
|
460
|
-
the proxy can't capture upstream-billed cost. Reliability values:
|
|
461
|
-
`accurate` (proxy-captured tokens, exact rate), `approximate` (JSONL-
|
|
462
|
-
sourced tokens, rate may be a family-prefix fallback), `unreliable`
|
|
463
|
-
(Claude Code JSONL streaming placeholders, ~10% off output), `unknown`
|
|
464
|
-
(no pricing entry for the model). Two adapters — OpenCode and Pi —
|
|
465
|
-
write their own per-turn cost into `estimated_cost_usd`; the engine
|
|
466
|
-
uses those as-is when present. See
|
|
467
|
-
`docs/pricing-reference.md` for the rate sheet.
|
|
468
|
-
|
|
469
|
-
Costs are stamped when a turn is captured. When a price changes or is
|
|
470
|
-
corrected later, `observer reprice` (a dry run unless `--apply`,
|
|
471
|
-
revertible with `--revert`) or Settings -> Pricing re-prices stored
|
|
472
|
-
turns at the rate in force when each one ran; a cost the tool itself
|
|
473
|
-
reported is never overwritten.
|
|
474
|
-
|
|
475
|
-
Hover any column header for tooltip; click for the full definition
|
|
476
|
-
in the help drawer.
|
|
477
|
-
|
|
478
|
-
### Analysis tab
|
|
479
|
-
|
|
480
|
-
<p align="center">
|
|
481
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/screenshots/05-analysis.png" alt="Analysis tab" width="900">
|
|
482
|
-
</p>
|
|
483
|
-
|
|
484
|
-
Spending insights for the selected window. Twelve headline KPI
|
|
485
|
-
tiles comparing this period to prior: spend Δ%, MTD vs budget with
|
|
486
|
-
projection bar, $/M output rate, cache savings + cache efficacy %,
|
|
487
|
-
high-context turn count, $/turn, burn rate ($/active hour), top
|
|
488
|
-
model concentration %, Discovery waste $, sessions total. Below
|
|
489
|
-
the tiles: a daily-spend stacked bar with Model / Project / Tool
|
|
490
|
-
dimension toggle, hour-of-day heatmap, top-12 expensive sessions
|
|
491
|
-
with explanatory badges (`opus`, `lc_tier`, `many_turns`,
|
|
492
|
-
`large_prompt`), period-over-period movers (top increases / decreases
|
|
493
|
-
/ new entrants), and model right-sizing hints (trivial Opus
|
|
494
|
-
sessions that could have used Sonnet).
|
|
495
|
-
|
|
496
|
-
### Sessions tab
|
|
497
|
-
|
|
498
|
-
<p align="center">
|
|
499
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/screenshots/02-sessions.png" alt="Sessions tab" width="900">
|
|
500
|
-
</p>
|
|
501
|
-
|
|
502
|
-
One row per AI-coding session. Each session has a stable ID, a tool
|
|
503
|
-
(claude-code / cursor / codex / cline / cline-cli / copilot / copilot-cli /
|
|
504
|
-
opencode / openclaw / pi / antigravity / gemini-cli / hermes /
|
|
505
|
-
kilo-code / kilo-code-cli), a working-directory project, action
|
|
506
|
-
count, sub-agent action count (when the session spawned sub-agents via
|
|
507
|
-
the `Agent` tool), per-session **Tokens** and **Cost** columns, and
|
|
508
|
-
quality / errors / redundancy ratios (filled in by the daemon's session
|
|
509
|
-
scorer, `[intelligence.scoring]`, on by default, once a session has
|
|
510
|
-
been idle for 30 minutes). The `~` suffix on Cost flags rows whose pricing
|
|
511
|
-
was tier-fallback rather than billing-grade ("accurate" reliability).
|
|
512
|
-
|
|
513
|
-
Click a row to open the session-detail panel:
|
|
514
|
-
|
|
515
|
-
<p align="center">
|
|
516
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/screenshots/11-session-detail.png" alt="Session detail slide-over" width="900">
|
|
517
|
-
</p>
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
- **Top tiles** — Tool, Started, Actions count (ok/fail), Cost.
|
|
521
|
-
- **Action breakdown** — chart of action_type counts.
|
|
522
|
-
- **Tokens** — the four billing buckets (Net Input / Cache Read /
|
|
523
|
-
Cache Write / Output) for the whole session, per-turn-deduped
|
|
524
|
-
(proxy preferred, JSONL fills gaps).
|
|
525
|
-
- **Per-model breakdown** — when a session uses multiple models
|
|
526
|
-
(Claude Code's main + sub-agent dispatches always do), a row per
|
|
527
|
-
model with its tokens and cost.
|
|
528
|
-
- **Messages** — per-message timeline keyed on the upstream
|
|
529
|
-
Anthropic `msg_xxx`. Each row shows the message id, role, model,
|
|
530
|
-
the message's own token bucket, cost, and a `N ▾` pill that
|
|
531
|
-
expands inline to show the contained tool calls. Toggle radio at
|
|
532
|
-
the top: **Tool messages only** (default — assistant turns with
|
|
533
|
-
≥1 tool call + user prompts) vs **All messages** (also pure-text
|
|
534
|
-
assistant replies). Truncated IDs (session_id, message_id)
|
|
535
|
-
show a dotted underline on hover and copy the full value to
|
|
536
|
-
clipboard on click; truncated text fields (target, error message)
|
|
537
|
-
click to expand in-place. Server-side paginated at 50/100/200
|
|
538
|
-
messages per page (selectable in the panel footer) — keeps the
|
|
539
|
-
browser responsive on multi-thousand-message sessions. Requires
|
|
540
|
-
`observer backfill --message-id` on first upgrade for historical
|
|
541
|
-
sessions to surface their parent message ids.
|
|
542
|
-
- **Gauges, quality, lines and commits** — a context-window gauge (and,
|
|
543
|
-
for proxied subscription sessions, the 5-hour / weekly limit gauge), a
|
|
544
|
-
session quality card with the score's parts, AI lines of code split
|
|
545
|
-
into code and comments, and a Commits card listing the git commits the
|
|
546
|
-
session's edits reached and whether it owns each one (the session with
|
|
547
|
-
the most AI code lines in it; merges, teammates' commits and commits
|
|
548
|
-
no AI edit reached have no owner).
|
|
549
|
-
|
|
550
|
-
### Actions tab
|
|
551
|
-
|
|
552
|
-
<p align="center">
|
|
553
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/screenshots/03-actions.png" alt="Actions tab" width="900">
|
|
554
|
-
</p>
|
|
555
|
-
|
|
556
|
-
The flat firehose: every recorded tool call, normalized across
|
|
557
|
-
adapters. Filter by action type (`read_file`, `write_file`,
|
|
558
|
-
`run_command`, `spawn_subagent`, `todo_update`, `mcp_call`, …).
|
|
559
|
-
Pagination caps at 50 rows per page; total count is shown next to
|
|
560
|
-
the heading.
|
|
561
|
-
|
|
562
|
-
### Tools tab
|
|
563
|
-
|
|
564
|
-
<p align="center">
|
|
565
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/screenshots/06-tools.png" alt="Tools tab" width="900">
|
|
566
|
-
</p>
|
|
567
|
-
|
|
568
|
-
Per-AI-client (the *client* — claude-code / cursor / codex / etc., not
|
|
569
|
-
the per-tool name) aggregates plus three views:
|
|
570
|
-
|
|
571
|
-
- **KPI tiles**: Total actions, Distinct tools, Overall success rate,
|
|
572
|
-
Busiest tool
|
|
573
|
-
- **Activity over time** stacked-area showing per-tool action volume
|
|
574
|
-
per day
|
|
575
|
-
- **Action-type mix per tool** horizontal stacked bar — what each
|
|
576
|
-
tool actually does (read_file vs edit_file vs run_command vs
|
|
577
|
-
search_text vs spawn_subagent)
|
|
578
|
-
- The full per-tool aggregate table with first/last seen
|
|
579
|
-
|
|
580
|
-
### Compression tab
|
|
581
|
-
|
|
582
|
-
<p align="center">
|
|
583
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/screenshots/07-compression.png" alt="Compression tab" width="900">
|
|
584
|
-
</p>
|
|
585
|
-
|
|
586
|
-
How many tokens and dollars the conversation-compression pipeline
|
|
587
|
-
saved by trimming requests before forwarding upstream:
|
|
588
|
-
|
|
589
|
-
- **KPI tiles**: Tokens saved (est.), Dollars saved (est.), Bytes
|
|
590
|
-
saved, Turns compressed
|
|
591
|
-
- **Savings per day** chart — daily tokens-saved (left axis) and
|
|
592
|
-
bytes-saved (right axis)
|
|
593
|
-
- **Savings by mechanism** stacked bar — segments per mechanism
|
|
594
|
-
(json / code / logs / text / diff / html / drop). **Toggle the
|
|
595
|
-
y-axis between tokens and bytes** with the chart-header switch.
|
|
596
|
-
- **Per-model breakdown table** — tokens saved ~, $ saved ~, bytes
|
|
597
|
-
saved, saved %, turns, tool-results compressed, dropped, markers
|
|
598
|
-
- **Recent compression events** — paginated per-event detail with
|
|
599
|
-
mechanism, original / compressed / saved bytes, message slot, importance
|
|
600
|
-
score (for drops), and a **Source** column showing whether the
|
|
601
|
-
event came from a main-thread or sub-agent runtime call
|
|
602
|
-
|
|
603
|
-
### Cache tab
|
|
604
|
-
|
|
605
|
-
<p align="center">
|
|
606
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/screenshots/08-cache.png" alt="Cache tab" width="900">
|
|
607
|
-
</p>
|
|
608
|
-
|
|
609
|
-
Anthropic prompt-cache observation, attribution, and forecasting —
|
|
610
|
-
how well your sessions are reusing provider-cached prefixes.
|
|
611
|
-
|
|
612
|
-
- **KPI tiles**: Cache ratio (cache_read ÷ cache_write tokens; the
|
|
613
|
-
headline cache-payback signal), Cache read, Cache write, and
|
|
614
|
-
Avoidable spend / Event count. The avoidable-spend tile is the
|
|
615
|
-
dollar overhead of cache rewrites that wouldn't have happened on
|
|
616
|
-
a perfectly cache-friendly session — it surfaces in warn tone when
|
|
617
|
-
non-zero.
|
|
618
|
-
- **By model + By project tables** — for each rollup dimension: R%/W%
|
|
619
|
-
mix bars + absolute Read / Write / Events + cache Ratio + Avoidable
|
|
620
|
-
$. Identifies the model or repo that's pulling the most overhead.
|
|
621
|
-
- **Top causes histogram** — proportional bar list of `cache_events.cause`
|
|
622
|
-
values. Healthy baseline is `suffix_growth` + `hit` dominating
|
|
623
|
-
(info-toned warm prefix growth). Real invalidations (`system_changed`,
|
|
624
|
-
`expiry_rewrite`, `model_switch_rewrite`) render in warn tone. Causes
|
|
625
|
-
that legitimately fire on real operator toggles — currently
|
|
626
|
-
`tools_changed` on MCP server connect/disconnect — render with a
|
|
627
|
-
neutral "flagged" pill rather than alarm-red.
|
|
628
|
-
- **Worst sessions table** — ranked by rewrite count; click a row to
|
|
629
|
-
open the session's Cache panel with the full per-turn timeline.
|
|
630
|
-
|
|
631
|
-
#### How the cache data gets captured
|
|
632
|
-
|
|
633
|
-
Two capture paths feed the same engine; both write the same three
|
|
634
|
-
local-only tables (`cache_segments`, `cache_entries`, `cache_events`;
|
|
635
|
-
migrations 036 + 037 — node-local only, never leaving the machine, pinned by
|
|
636
|
-
`tests/invariant/privacy_test.go::TestSelectUnpushedSinceExcludesCacheTables`):
|
|
637
|
-
|
|
638
|
-
1. **Tier-1 (proxy)** — point your AI client at the local proxy
|
|
639
|
-
(`ANTHROPIC_BASE_URL=http://127.0.0.1:8820` for Claude Code;
|
|
640
|
-
`OPENAI_BASE_URL=http://127.0.0.1:8820/v1` for codex and
|
|
641
|
-
copilot-cli). The proxy reads the upstream usage envelope
|
|
642
|
-
(`cache_read_input_tokens` + `cache_creation_input_tokens`) and the
|
|
643
|
-
cachetrack engine attributes each turn live as it streams. Every
|
|
644
|
-
claude-code prompt-cache event surfaces here in real time.
|
|
645
|
-
2. **Tier-2 (transcript watcher)** — the watcher tails claude-code
|
|
646
|
-
JSONL transcripts and feeds the same engine retroactively for
|
|
647
|
-
sessions that didn't route through the proxy. Run
|
|
648
|
-
`observer backfill --cache-rescan` to retrofit pre-cachetrack
|
|
649
|
-
history.
|
|
650
|
-
|
|
651
|
-
#### How to enable / disable
|
|
652
|
-
|
|
653
|
-
- **Default-on.** Per spec §11, the loader merges `[cachetrack].enabled = true`
|
|
654
|
-
if the section is absent. No action needed for a fresh install.
|
|
655
|
-
- To disable: set `[cachetrack].enabled = false` in
|
|
656
|
-
`~/.observer/config.toml` and restart `observer start`.
|
|
657
|
-
- Inspect engine health: `observer cache-health --json` — §10 grading
|
|
658
|
-
gate + read:write consistency + cause-concentration WARNs.
|
|
659
|
-
- 90-day retention is on by default
|
|
660
|
-
(`[cachetrack].retention_days = 90`); the maintenance tick prunes
|
|
661
|
-
stale `cache_*` rows alongside the existing retention pass.
|
|
662
|
-
|
|
663
|
-
Operator reference: [superbased.app/docs/guides/cache-tracking](https://superbased.app/docs/guides/cache-tracking).
|
|
664
|
-
|
|
665
|
-
### Suggestions tab
|
|
666
|
-
|
|
667
|
-
The **advisor** — a prescriptive suggestions engine that turns the
|
|
668
|
-
window's captured activity into ranked, dollar- or minute-quantified
|
|
669
|
-
recommendations. **On by default** and entirely local: detectors are
|
|
670
|
-
pure reads over data the observer already stores, recomputed fresh on
|
|
671
|
-
every view — zero LLM calls, zero network.
|
|
672
|
-
|
|
673
|
-
Nineteen detectors across four categories:
|
|
674
|
-
|
|
675
|
-
- **cost** — session balloons (one session's context growth dominating
|
|
676
|
-
spend), idle re-cache (cache rewrites after idle gaps), long-context
|
|
677
|
-
tier crossings, trivial sessions on expensive models, cache hit-rate,
|
|
678
|
-
cache-write waste, prefix thrash, read-heavy sessions on expensive
|
|
679
|
-
models, effort overprovisioning, cross-session stale reads,
|
|
680
|
-
web-search spend, spend spikes ("today is 3× your daily average" —
|
|
681
|
-
the while-it's-still-happening check, linking to the Live view).
|
|
682
|
-
- **latency** — fast-tier premium (sessions that paid the 2× fast-tier
|
|
683
|
-
rate without needing it).
|
|
684
|
-
- **quality** — unrecovered failures, quality regressions.
|
|
685
|
-
- **hygiene** — MCP schema overhead vs. actual MCP calls, compression
|
|
686
|
-
off while proxied traffic flows, capture running without proxy
|
|
687
|
-
routing, guard observing idle (recurring high-severity verdicts
|
|
688
|
-
with zero approvals or tuning — linking to the Security page).
|
|
689
|
-
|
|
690
|
-
Each card carries the quantified claim ($ or minutes, with a
|
|
691
|
-
**show math** toggle exposing the arithmetic), a confidence score, a
|
|
692
|
-
scope chip (window / project / session — session scopes deep-link to
|
|
693
|
-
the session detail), and — when a dashboard control can fix the
|
|
694
|
-
finding — an action button that navigates to the right surface
|
|
695
|
-
(writes only ever happen behind that surface's own consent flow).
|
|
696
|
-
`snooze 7d` quiets a card temporarily; `dismiss` retires it, with a
|
|
697
|
-
7-day cooldown so the same finding doesn't re-nag. The all-clear
|
|
698
|
-
state means exactly what it says: nothing worth nagging about in
|
|
699
|
-
this window.
|
|
700
|
-
|
|
701
|
-
Tune it under Settings → Advisor (`[advisor]` in config.toml):
|
|
702
|
-
evidence window (default 14 days), confidence floor (0.5), minimum
|
|
703
|
-
claimed savings ($1), and the opt-in **session digest** — when
|
|
704
|
-
`session_digest = true`, the Claude Code session-start hook injects a
|
|
705
|
-
≤400-token digest of the top suggestions into new sessions (off by
|
|
706
|
-
default; the hook only reads a pre-computed snapshot, refreshed every
|
|
707
|
-
30 minutes). CLI twin: `observer advise`.
|
|
708
|
-
|
|
709
|
-
### Discovery tab
|
|
710
|
-
|
|
711
|
-
<p align="center">
|
|
712
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/screenshots/09-discovery.png" alt="Discovery tab" width="900">
|
|
713
|
-
</p>
|
|
714
|
-
|
|
715
|
-
Wasted-effort signals:
|
|
716
|
-
|
|
717
|
-
- **Stale rereads** — files re-read after they changed inside the
|
|
718
|
-
same session. KPI tiles show count, ~Tokens wasted, ~$ wasted (at
|
|
719
|
-
your blended input rate), affected files. The **CROSS-THREAD**
|
|
720
|
-
column flags re-reads that crossed the parent ↔ sub-agent
|
|
721
|
-
boundary — these are the "pass content via Agent's prompt
|
|
722
|
-
parameter" candidates.
|
|
723
|
-
- **Repeated commands** — commands run multiple times with no
|
|
724
|
-
relevant inputs changed in between (e.g. you ran `go test` three
|
|
725
|
-
times without editing anything between runs).
|
|
726
|
-
- **Cross-tool overlap** — files touched by ≥2 AI clients in the
|
|
727
|
-
window (e.g. claude-code AND cursor both edited `auth.ts`). This
|
|
728
|
-
is the visible side of cross-platform tool-call sharing via the
|
|
729
|
-
MCP server.
|
|
730
|
-
|
|
731
|
-
### Patterns tab
|
|
732
|
-
|
|
733
|
-
Repeatable behaviours the observer noticed across your sessions —
|
|
734
|
-
"after running `go test`, you almost always run `go vet`", "when
|
|
735
|
-
working on `auth.ts`, you also touch `login.tsx`", etc. Each pattern
|
|
736
|
-
has a confidence score (decay-weighted: more observations + recent
|
|
737
|
-
observations push it higher) and an observation count.
|
|
738
|
-
|
|
739
|
-
`observer patterns` derives them; `observer suggest` writes the
|
|
740
|
-
high-confidence ones into `CLAUDE.md` / `AGENTS.md` / `.cursorrules`
|
|
741
|
-
so new sessions inherit your habits.
|
|
742
|
-
|
|
743
|
-
### Security tab
|
|
744
|
-
|
|
745
|
-
The guard layer's operating surface — not just a verdict viewer.
|
|
746
|
-
Posture tiles (mode, verdict counts, audit-chain check) over a
|
|
747
|
-
filterable verdict timeline (rule / severity / decision / session,
|
|
748
|
-
with rule IDs resolved to their full definitions), then the routine
|
|
749
|
-
workflows end to end: a consent-gated **mode control** that shows the
|
|
750
|
-
simulate evidence before you flip enforce, the **enforce-readiness
|
|
751
|
-
card** (a replay of your real history under the enforce projection,
|
|
752
|
-
with per-rule blocking concentration), the **approvals register**
|
|
753
|
-
(scoped, expiring exceptions — DB writes, live immediately), a
|
|
754
|
-
**lint-gated policy editor** for your user rules (malformed files are
|
|
755
|
-
refused with the problems listed; `.bak` undo), **budget guardrails**
|
|
756
|
-
suggested from your own observed spend with a daily burn-down meter,
|
|
757
|
-
MCP pin approvals, and one-click **compliance evidence** downloads
|
|
758
|
-
(report / JSONL / CEF / audit verification).
|
|
759
|
-
|
|
760
|
-
### Settings tab
|
|
761
|
-
|
|
762
|
-
<p align="center">
|
|
763
|
-
<img src="https://github.com/superbasedapp/observer/raw/main/docs/assets/screenshots/10-settings.png" alt="Settings tab" width="900">
|
|
764
|
-
</p>
|
|
765
|
-
|
|
766
|
-
Fully editable visual editor for everything in `config.toml`, plus
|
|
767
|
-
the operational panels a config file can't express:
|
|
768
|
-
|
|
769
|
-
- **Config sections** — schema-driven forms for Watcher, Freshness,
|
|
770
|
-
Retention, Hooks, Proxy, Compression, Intelligence, Advisor, Cache
|
|
771
|
-
tracking, Secrets scrubbing, MCP, Profiles, Org share, and OTel.
|
|
772
|
-
Each section is honest about reload semantics: pricing and profile
|
|
773
|
-
changes apply hot, MCP settings apply to the next AI session, and
|
|
774
|
-
restart-gated sections raise a persistent restart-pending banner
|
|
775
|
-
that names the exact command and clears itself only when the
|
|
776
|
-
daemon actually restarts.
|
|
777
|
-
- **Connected tools** — one row per detected AI client (detected /
|
|
778
|
-
capturing / hooks / MCP / proxied), a per-tool setup wizard that
|
|
779
|
-
previews every config write and applies each one only on its own
|
|
780
|
-
consent click, and a Launch button (with a copy-paste fallback)
|
|
781
|
-
for opening a routed session.
|
|
782
|
-
- **Health** — the full `observer doctor` check set with remediation
|
|
783
|
-
hints, plus recent command failures (recovered vs not).
|
|
784
|
-
- **Backfill** — every `observer backfill` mode as a click-to-run
|
|
785
|
-
job with live streamed output, plus a full-rescan card with an
|
|
786
|
-
adapter picker.
|
|
787
|
-
- **Storage** — what's actually taking the space: per-table database
|
|
788
|
-
size breakdown (index and FTS5 shadow-table bytes folded into the
|
|
789
|
-
table they serve), vacuum and online backup as click-to-run jobs,
|
|
790
|
-
and the documented restore procedure (restore is deliberately
|
|
791
|
-
manual: stop the daemon, swap the file, start). CLI twin:
|
|
792
|
-
`observer db stats|vacuum|backup`.
|
|
793
|
-
- **Config file card** — view the active file; one-click restore of
|
|
794
|
-
the automatic `.bak` taken before every save.
|
|
795
|
-
|
|
796
|
-
### Help drawer
|
|
797
|
-
|
|
798
|
-
Press `?` anywhere on the dashboard or click the **? Help** button in
|
|
799
|
-
the topbar. Every column header, KPI tile, chart label, and filter
|
|
800
|
-
control on every tab is annotated — hover any element to see a
|
|
801
|
-
one-liner tooltip; click to open the drawer at the matching glossary
|
|
802
|
-
entry.
|
|
803
|
-
|
|
804
|
-
The drawer has full descriptions, formulas, data sources, examples,
|
|
805
|
-
"why it matters", "what to do", and cross-links. Search at the top.
|
|
806
|
-
Deep-linkable via URL fragment — `#help/metric.stale_count` opens
|
|
807
|
-
the drawer at that entry.
|
|
808
|
-
|
|
809
|
-
Each compression mechanism (json / code / logs / text / diff / html
|
|
810
|
-
/ drop) has a "Full methodology · see more" expandable section
|
|
811
|
-
explaining the actual algorithm.
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
## Terminals — launch, join, and track your AI CLIs
|
|
815
|
-
|
|
816
|
-
The dashboard is also a terminal host. Instead of tracking your AI
|
|
817
|
-
CLIs from the outside, you can launch them *inside* observer, watch
|
|
818
|
-
their live telemetry alongside the session they produce, and — new in
|
|
819
|
-
v1.25.0 — join a running one from a second browser tab. The terminal
|
|
820
|
-
surfaces are read-only where they touch your files and single-writer
|
|
821
|
-
where they touch your keyboard; nothing here mutates a repo or lets
|
|
822
|
-
two people type at once.
|
|
823
|
-
|
|
824
|
-
### Launch any supported AI CLI as a real terminal
|
|
825
|
-
|
|
826
|
-
Twenty-seven CLI launchers — claude, codex, opencode, cursor, copilot-cli,
|
|
827
|
-
kilo, cline-cli, hermes, gemini, openclaw, pi, antigravity, qwen,
|
|
828
|
-
kiro, grok, kimi, devin, qoder, goose, droid, open-interpreter,
|
|
829
|
-
command-code, muse, prime-agent, zcode, vibe (mistral-code), freebuff —
|
|
830
|
-
start from the dashboard's
|
|
831
|
-
**Launch here** control or from the command line as `observer <verb>`
|
|
832
|
-
(`observer claude`, `observer codex`, and so on). Each opens a **real
|
|
833
|
-
PTY** — a native pseudo-terminal on Linux and macOS, and a native
|
|
834
|
-
ConPTY on Windows 10 1809+ and Windows 11 (no WSL required). If the
|
|
835
|
-
tool's binary isn't on your `$PATH`, the launcher offers a guided
|
|
836
|
-
one-click install rather than failing. Dashboard launching is gated by
|
|
837
|
-
`[handoff].allow_dashboard_launch` (default `true`).
|
|
838
|
-
|
|
839
|
-
(The count is twenty-seven *launchers*, not the adapter count — observer
|
|
840
|
-
tracks 40 adapters in total, but only these twenty-seven ship a
|
|
841
|
-
first-class terminal launcher.)
|
|
842
|
-
|
|
843
|
-
### Attach-by-default
|
|
844
|
-
|
|
845
|
-
As of v1.25.0, `observer <verb>` runs the child **daemon-owned** so the
|
|
846
|
-
dashboard can join it, while the native terminal you launched from stays
|
|
847
|
-
fully interactive as seat #1 — you lose nothing by getting the extra
|
|
848
|
-
reach. Opt out per-run with `--no-attach`, or globally with
|
|
849
|
-
`[terminal.attach].default_on = false`; scripted or piped runs never
|
|
850
|
-
attach.
|
|
851
|
-
|
|
852
|
-
A daemon-owned child forwards more than the routing above: it also
|
|
853
|
-
carries over your shell's values for each tool's
|
|
854
|
-
registry-documented credential env keys — `ANTHROPIC_API_KEY` for
|
|
855
|
-
claude-code, `OPENAI_API_KEY` for codex and pi, `OPENROUTER_API_KEY`
|
|
856
|
-
for hermes, `XAI_API_KEY` for grok, `GEMINI_API_KEY`/`GOOGLE_API_KEY`
|
|
857
|
-
for gemini-cli, `COPILOT_PROVIDER_API_KEY` for copilot-cli, and others
|
|
858
|
-
with registry-documented key envs — so a shell-exported API key works
|
|
859
|
-
under attach exactly as it would bare. This is gated by
|
|
860
|
-
`[terminal.attach].forward_auth_env` (default `true`); values transit
|
|
861
|
-
the owner-only attach socket once per launch and are never logged or
|
|
862
|
-
persisted. One honest caveat remains: tools without a registry-documented
|
|
863
|
-
credential env (config-file, OAuth, or keychain auth) still see only
|
|
864
|
-
the **daemon's** environment, and dashboard-launched terminals always
|
|
865
|
-
do (there's no client shell to forward from) — for those, either
|
|
866
|
-
export the credential where `observer start` runs, or use
|
|
867
|
-
`--no-attach` to keep the child in your shell's environment.
|
|
868
|
-
|
|
869
|
-
### Jump in — multi-seat terminals
|
|
870
|
-
|
|
871
|
-
Every live daemon-owned run is joinable from any dashboard tab, whether
|
|
872
|
-
that tab is local or a paired remote device, as an extra seat. A
|
|
873
|
-
terminal holds up to **8 viewers** but exactly **one writer** at a time.
|
|
874
|
-
The writer lease moves seamlessly across the native terminal, a local
|
|
875
|
-
dashboard tab, and a remote dashboard tab — type into the native
|
|
876
|
-
terminal to reclaim it; an authenticated remote can take over with a
|
|
877
|
-
read-only fallback and a take-back for the seat it displaced. A freshly
|
|
878
|
-
launched run correlates to its observer session in roughly 10–30
|
|
879
|
-
seconds, after which its live telemetry lines up with the captured data.
|
|
880
|
-
|
|
881
|
-
### Per-terminal Files & Git panels
|
|
882
|
-
|
|
883
|
-
Each AI-tool terminal carries a read-only **Files** panel — a file tree
|
|
884
|
-
plus a text viewer rooted at that terminal's project root — and a
|
|
885
|
-
read-only **Git** panel showing branch, upstream, ahead/behind counts,
|
|
886
|
-
working-tree status, and a 100-commit log. Right-click to copy a path or
|
|
887
|
-
paste it into a live terminal. This is a read-only view in v1: no file
|
|
888
|
-
mutations, no diff view.
|
|
889
|
-
|
|
890
|
-
### Session Cockpit
|
|
891
|
-
|
|
892
|
-
Toggle the **⊙ Session** control on any AI-tool terminal for a
|
|
893
|
-
draggable, live panel of everything observer knows about that run:
|
|
894
|
-
|
|
895
|
-
- **Last activity** and **tokens/sec**, tagged with a measured-vs-
|
|
896
|
-
estimated badge
|
|
897
|
-
- **Live cost** with the AI-vs-tool split, plus the **next-message
|
|
898
|
-
cost band**
|
|
899
|
-
- **Context fill** against the model's context budget, and — for
|
|
900
|
-
proxy-routed sessions — the **5h / 7d rate-limit gauge**
|
|
901
|
-
- **Prompt-cache expiry chips** for the caches this session is keeping
|
|
902
|
-
warm
|
|
903
|
-
- **CPU / memory / disk sparklines** and the spawned-process tree for
|
|
904
|
-
the terminal
|
|
905
|
-
- The **last five turns**, each deep-linked into the full session
|
|
906
|
-
detail view
|
|
907
|
-
|
|
908
|
-
### Workspace grid
|
|
909
|
-
|
|
910
|
-
Run up to **9 concurrent tiles** (`[terminal].max_concurrent`),
|
|
911
|
-
drag and resize them, and your layout persists across reloads. On a
|
|
912
|
-
paired remote device the grid is read-only.
|
|
913
|
-
|
|
914
|
-
### Restarts & continuity
|
|
915
|
-
|
|
916
|
-
Twenty-six of the twenty-seven launchers **auto-resume the same
|
|
917
|
-
transcript** after a daemon restart — a verified native resume, so the
|
|
918
|
-
conversation continues where it left off. openclaw is the sole holdout:
|
|
919
|
-
its resume is picker-only, so its attached session ends when the daemon
|
|
920
|
-
restarts. To pick any session back up — including openclaw's — fork it
|
|
921
|
-
with `observer <verb> --continue-from <session-id>`. That opens a new
|
|
922
|
-
session id and seeds a distilled handover of the prior session as its
|
|
923
|
-
first prompt — it works for all twenty-seven launchers.
|
|
924
|
-
|
|
925
|
-
### Remote posture
|
|
926
|
-
|
|
927
|
-
Remote terminal access is opt-in, **tailnet-only** (served over your
|
|
928
|
-
private Tailscale network as private HTTPS), and off by default — there
|
|
929
|
-
is no public-internet exposure. It splits into a view tier and an
|
|
930
|
-
execute tier: `[remote].allow_terminal` (default `false`) governs remote
|
|
931
|
-
*keyboard* control, while `[remote].allow_terminal_view` (default
|
|
932
|
-
`true`) governs read-only viewing. Pairing is phone-first via QR code,
|
|
933
|
-
and the dashboard is mobile-friendly for checking in from a phone.
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
## MCP tools reference
|
|
937
|
-
|
|
938
|
-
Once you've run `observer init` (it's opt-in — `observer start`
|
|
939
|
-
alone does NOT register the MCP server), every connected AI client
|
|
940
|
-
gets 21 tools registered as an MCP server always, plus 4 more
|
|
941
|
-
(`get_file`, `get_symbols`, `get_relations`, `retrieve_stashed`) that
|
|
942
|
-
register conditionally, only when the capability they depend on is
|
|
943
|
-
actually configured. They're **read-only** queries against the
|
|
944
|
-
unified database, so any agent can read any other agent's recorded
|
|
945
|
-
work — true cross-platform tool-call sharing.
|
|
946
|
-
|
|
947
|
-
| Tool | Purpose |
|
|
948
|
-
|-----------------------------------|---------|
|
|
949
|
-
| `check_file_freshness` | Has this file been read in the current session? Has it changed since? |
|
|
950
|
-
| `get_file_history` | Full read/edit history of a file across all sessions and clients |
|
|
951
|
-
| `get_session_summary` | Roll-up stats for a session: action count, success rate, cost, token buckets |
|
|
952
|
-
| `search_past_outputs` | Full-text search across recorded tool outputs (FTS5-indexed) |
|
|
953
|
-
| `get_last_test_result` | Most recent `go test` / `npm test` / `pytest` etc. output |
|
|
954
|
-
| `get_failure_context` | Recent failures: which command, which file, which session |
|
|
955
|
-
| `get_action_details` | One specific action's full record (target, args, output excerpt) |
|
|
956
|
-
| `check_command_freshness` | Has this command been run in the current session? With what result? |
|
|
957
|
-
| `get_session_recovery_context` | Recent activity for resuming a paused session |
|
|
958
|
-
| `get_project_patterns` | High-confidence patterns derived from this project's history |
|
|
959
|
-
| `get_cost_summary` | Daily / per-model / per-session cost rollups |
|
|
960
|
-
| `get_redundancy_report` | Stale rereads, repeated commands, cross-tool overlap for the project |
|
|
961
|
-
| `list_actions_around` | ±N actions adjacent to a pivot `action_id` — browse a session's local timeline cheaply |
|
|
962
|
-
| `search_symbols` | Fuzzy symbol search across the project's codeintel index (Tier-C) |
|
|
963
|
-
| `get_output_composition` | Code vs. explanation split of a session's output, by bytes, with the code:explanation ratio and languages used |
|
|
964
|
-
| `get_suggestions` | Top dollar/time-quantified cost & quality suggestions from the local advisor |
|
|
965
|
-
| `cache_status` | Live prompt-cache health: which caches are warm, expiring, or cold, with value-at-risk |
|
|
966
|
-
| `get_model_recommendation` | Evidence-backed model suggestion per turn-kind, from the local Model Value Report |
|
|
967
|
-
| `get_routing_status` | Model-routing layer state: phase, available policy templates, tier-table size, decision-log counters |
|
|
968
|
-
| `continue_session` | A distilled, scrubbed handover of a session from another AI tool, so you can continue its work here |
|
|
969
|
-
| `get_session_message` | One full, un-excerpted message from a session's transcript — pulls the complete body a handover excerpt truncated |
|
|
970
|
-
| `get_file` _(conditional)_ | The file's current bytes (or at a given commit), with a path-safety gate + audit |
|
|
971
|
-
| `get_symbols` _(conditional)_ | Resolve a symbol name + range to its file path + body (codeintel-backed) |
|
|
972
|
-
| `get_relations` _(conditional)_ | Codeintel BFS — who calls / is called by this symbol |
|
|
973
|
-
| `retrieve_stashed` _(conditional)_| Pulls original bytes of a tool_result the proxy compressed away. Only registered when `[compression.conversation].stash` is configured. |
|
|
974
|
-
|
|
975
|
-
**Cost trade-off**: with the MCP registered, the AI client sends the
|
|
976
|
-
full tool-schema payload (~7.2 KB / ~1,800 tokens) in its system
|
|
977
|
-
context on every turn — whether or not the model actually invokes
|
|
978
|
-
any tool. To eliminate this overhead, run `observer init --skip-mcp`
|
|
979
|
-
(registers hooks only) or skip `init` entirely.
|
|
980
|
-
|
|
981
|
-
**Cross-tool sharing**: when `observer init` registers the MCP server
|
|
982
|
-
with Claude Code AND Cursor (and Codex…), all of them call the same
|
|
983
|
-
tools against the same database. Cursor's `get_last_test_result`
|
|
984
|
-
returns Claude Code's last test run; Codex's `check_file_freshness`
|
|
985
|
-
reflects edits made by Cursor.
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
## Sign in and Cloud Intelligence (beta, experimental)
|
|
989
|
-
|
|
990
|
-
Optional, opt-in, and **beta (experimental)**. Nothing is sent anywhere
|
|
991
|
-
unless you run `observer cloud login` and enrol a session yourself -
|
|
992
|
-
the `observer cloud` CLI is the only outbound trigger, and it touches
|
|
993
|
-
the network only while one of its commands is running. **Signed-in
|
|
994
|
-
Free** gives up to 20 session enrichments per day (100 per month) on
|
|
995
|
-
GPT-5.6 Luna (xhigh reasoning). **Plus (beta)** runs enrichments on
|
|
996
|
-
GPT-5.6 Sol (xhigh reasoning), capped at 120 per month, USD 15/month
|
|
997
|
-
with a 7-day trial. An enrichment returns a narrative summary of the
|
|
998
|
-
session: what was done, which plans were implemented, which issues or
|
|
999
|
-
bugs were found, what failed, and what to do next. Behaviour,
|
|
1000
|
-
allowances, and pricing may change. The local daemon - proxy, watcher,
|
|
1001
|
-
dashboard, MCP - needs no account and is unaffected by any of it. Full
|
|
1002
|
-
detail: [`docs/cloud-intelligence.md`](https://github.com/superbasedapp/observer/blob/main/docs/cloud-intelligence.md).
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
## Compression mechanisms
|
|
1006
|
-
|
|
1007
|
-
The conversation-compression pipeline runs inside the proxy on every
|
|
1008
|
-
upstream request. It tries to fit the request body within
|
|
1009
|
-
`target_ratio × original_bytes` (default 0.85) without breaking the
|
|
1010
|
-
conversation's referential integrity.
|
|
1011
|
-
|
|
1012
|
-
Two passes, in order:
|
|
1013
|
-
|
|
1014
|
-
### Pass 1 — per-content-type compression
|
|
1015
|
-
|
|
1016
|
-
Each `tool_result` block is sniffed for content type, then routed to
|
|
1017
|
-
a content-aware compressor. Six compressors:
|
|
1018
|
-
|
|
1019
|
-
| Mechanism | What it does | When it fires |
|
|
1020
|
-
|-----------|--------------|---------------|
|
|
1021
|
-
| **json** | Replaces every scalar value with a type sentinel (`"<string>"`, `"<number>"`, …) preserving structure (keys, arrays, nesting). Arrays of length > 1 collapse to one element with `_len: N`. | API responses, structured logs, telemetry exports. JSON tool_results are usually the biggest savings target. |
|
|
1022
|
-
| **code** | Heuristic skeleton: keeps top-of-file imports + signature lines (function / method / class / struct / interface / type), drops bodies. | Source code files. **On by default** as of v1.7.23 in the `claude-code` profile (V7-24 empirical winner). |
|
|
1023
|
-
| **logs** | Two-pass: collapses adjacent identical lines to `<line> [×N]`, then head+tail-truncates to 200 lines if still long. | Log-shaped output — `go test ./...`, `npm run build`, polling/retry loops. Lossless on distinct lines; only the truncate pass is lossy. |
|
|
1024
|
-
| **text** | Catch-all for content not classified as code/json/logs/diff/html. Head+tail truncation: keeps 40 + 40 lines on inputs over 80 lines. | Markdown bodies, README excerpts, narrative descriptions. |
|
|
1025
|
-
| **diff** | Strips unified-diff context beyond ±1 line of each change. Keeps every header, every `+`/`-` line, drops the rest with elision markers. | `git diff`, patch tool outputs. Lossless on changes; lossy only on the cheap-to-rebuild context. |
|
|
1026
|
-
| **html** | Three regex passes: strips `<script>`, `<style>`, and HTML comments. Tag attributes + visible text + structural elements survive. | `web_fetch` results pulling whole HTML pages — usually 80%+ scripts/styles. |
|
|
1027
|
-
|
|
1028
|
-
### Pass 2 — drop with marker
|
|
1029
|
-
|
|
1030
|
-
If Pass 1's compressed body is still over budget, the budget enforcer
|
|
1031
|
-
ranks remaining messages by **importance score** (a deterministic
|
|
1032
|
-
weighted sum) and drops the lowest-scored non-preserved ones until
|
|
1033
|
-
the budget is met. Each dropped message is replaced by a single
|
|
1034
|
-
marker block (a placeholder text) so the conversation flow stays
|
|
1035
|
-
intact for the model.
|
|
1036
|
-
|
|
1037
|
-
**Importance score** = `0.4 × recency + 0.3 × reference + 0.15 × density + 0.15 × role`
|
|
1038
|
-
|
|
1039
|
-
- **Recency** = `(i+1) / n` — newest message scores 1.0, oldest scores 1/n
|
|
1040
|
-
- **Reference** = `1.0` if any of the message's `tool_use_ids` is
|
|
1041
|
-
cited by a later `tool_result`, OR any of its `referenced_ids` points
|
|
1042
|
-
to a live tool_use; `0.0` otherwise. Tool-pair-live messages always
|
|
1043
|
-
get full weight regardless of position.
|
|
1044
|
-
- **Density** = fraction of non-whitespace runes (whitespace-padded
|
|
1045
|
-
outputs get dropped first)
|
|
1046
|
-
- **Role** = `system 1.0`, `user 0.9`, `assistant 0.7`, `tool 0.5`
|
|
1047
|
-
(tool outputs are the most-compressible by policy)
|
|
1048
|
-
|
|
1049
|
-
**Preserved messages** (never droppable):
|
|
1050
|
-
- The last `PreserveLastN` messages (default 4)
|
|
1051
|
-
- Any `system` role message
|
|
1052
|
-
- **Tool-pair-live messages**: any message whose `tool_use_id` is
|
|
1053
|
-
referenced by a later tool_result (parent side), AND any
|
|
1054
|
-
`tool_result` message whose `referenced_id` points to a live
|
|
1055
|
-
tool_use (consumer side)
|
|
1056
|
-
|
|
1057
|
-
Tool-pair preservation is symmetric — dropping either side leaves an
|
|
1058
|
-
orphan that Anthropic rejects with 400.
|
|
1059
|
-
|
|
1060
|
-
### Per-event detail
|
|
1061
|
-
|
|
1062
|
-
Every drop and every per-type compression is recorded as a row in
|
|
1063
|
-
the `compression_events` table (post migration 010). The Compression
|
|
1064
|
-
tab's "Recent compression events" view surfaces these with
|
|
1065
|
-
mechanism, original / compressed / saved bytes, message slot, and
|
|
1066
|
-
importance score (for drops).
|
|
1067
|
-
|
|
1068
|
-
### Tuning — profiles pick the parameters for you
|
|
1069
|
-
|
|
1070
|
-
Compression parameters are supplied by **profiles**: named parameter
|
|
1071
|
-
sets resolved per traffic class at the proxy boundary. The moment you
|
|
1072
|
-
enable compression, Anthropic-path traffic gets the `claude-code`
|
|
1073
|
-
profile and OpenAI-path traffic gets `codex-safe` — each tool gets
|
|
1074
|
-
its tuned parameters simultaneously; there is no recipe-picking step.
|
|
1075
|
-
Inspect with `observer profile list` / `observer profile show
|
|
1076
|
-
<name>`; reassign per class or per tool (`observer profile assign
|
|
1077
|
-
openai codex-variant`, `observer profile assign tool:kilo-code-cli
|
|
1078
|
-
codex-safe`); build your own (`observer profile create mine --from
|
|
1079
|
-
claude-code`, or Settings → Profiles in the dashboard). Per-tool
|
|
1080
|
-
assignment needs the proxy to identify the connecting tool: hook-fed
|
|
1081
|
-
identity (Claude Code) is exact, and Codex, Kilo CLI, opencode, and
|
|
1082
|
-
Claude Code are also recognized by their request headers; clients
|
|
1083
|
-
that send no distinctive headers (e.g. Cline CLI) fall back to the
|
|
1084
|
-
per-provider profile. Profile
|
|
1085
|
-
edits apply to **new sessions without a daemon restart**. A repo can
|
|
1086
|
-
also carry `<root>/.observer/config.toml` with `[profiles]` /
|
|
1087
|
-
`[compression]` keys to override per project — project files can turn
|
|
1088
|
-
compression *off* for their traffic, never on.
|
|
1089
|
-
|
|
1090
|
-
The master config (`~/.observer/config.toml`) keeps the one on/off
|
|
1091
|
-
switch and the fallback parameters used by the `default` profile:
|
|
1092
|
-
|
|
1093
|
-
```toml
|
|
1094
|
-
[compression.conversation]
|
|
1095
|
-
enabled = true # THE switch — profiles never flip this
|
|
1096
|
-
mode = "cache_aware" # "token" | "cache" | "cache_aware" — default cache_aware; see matrix below
|
|
1097
|
-
target_ratio = 0.85
|
|
1098
|
-
preserve_last_n = 5 # never drop the most recent N messages
|
|
1099
|
-
compress_types = ["json", "logs", "code"] # default; add "text", "diff", "html" to opt in
|
|
1100
|
-
```
|
|
1101
|
-
|
|
1102
|
-
High importance scores on dropped events (≥0.5) suggest the threshold
|
|
1103
|
-
is too aggressive — raise `target_ratio` (e.g. 0.9 or 0.95).
|
|
1104
|
-
|
|
1105
|
-
### Choosing a mode: Anthropic vs Codex
|
|
1106
|
-
|
|
1107
|
-
Per-type `tool_result` compression runs in every mode; `mode` only changes how
|
|
1108
|
-
messages are dropped and whether an Anthropic `cache_control` marker is injected.
|
|
1109
|
-
|
|
1110
|
-
| `mode` | What it does | Claude Code (Anthropic) | Codex / OpenAI |
|
|
1111
|
-
|---|---|---|---|
|
|
1112
|
-
| `token` | Per-type compress, then drop lowest-scored messages to hit `target_ratio`. | ✅ Works. | ✅ Clearest choice for Codex/OpenAI. |
|
|
1113
|
-
| `cache` | Restrict drops to the tail half + inject a `cache_control` marker at the prefix boundary. | ✅ Anthropic-specific. | ⚠️ No effect beyond `token`. |
|
|
1114
|
-
| `cache_aware` *(default)* | Skip drops, narrow compression to `tool_result` blocks, no marker; keep history byte-stable across turns so Anthropic's prefix cache keeps hitting. | ✅ **Recommended for Anthropic Pro/Max** — and the shipped default. | ⚠️ No effect beyond `token`. |
|
|
1115
|
-
|
|
1116
|
-
The shipped default is `cache_aware` (`token` is just the internal fallback when
|
|
1117
|
-
`mode` is empty). The cache modes exist for **Anthropic's content-hash prefix
|
|
1118
|
-
cache** (`cache_control` is an Anthropic Messages API concept). OpenAI/Codex
|
|
1119
|
-
prompt caching is **automatic and server-side** — nothing to mark or tune, so
|
|
1120
|
-
the proxy's OpenAI path is mode-agnostic (the default `cache_aware` behaves like
|
|
1121
|
-
`token` there). So: keep `cache_aware` for Claude Code; `mode = "token"` reads
|
|
1122
|
-
honestly for a Codex/OpenAI-only setup.
|
|
1123
|
-
|
|
1124
|
-
Beyond the keys above, three opt-in sub-features have their own tables —
|
|
1125
|
-
`[compression.conversation.stash]` (Compressed-Content Retrieval),
|
|
1126
|
-
`[compression.conversation.rolling]` (rolling summarisation, with a per-provider
|
|
1127
|
-
summary model: `summary_model` for Anthropic, `openai_summary_model` for
|
|
1128
|
-
OpenAI/Codex), and `[compression.conversation.compaction]`. The full knob
|
|
1129
|
-
reference lives in `docs/compression-modes.md`.
|
|
1130
|
-
|
|
1131
|
-
### Measured savings (v1.7.23)
|
|
1132
|
-
|
|
1133
|
-
We A/B every shipped profile against an OFF baseline on a real refactor
|
|
1134
|
-
workload (`lumen` TypeScript codebase, 408-line Zustand store →
|
|
1135
|
-
4 domain sub-stores) on the v1.7.22 binary tip. The numbers below are
|
|
1136
|
-
the **most recent statistically-meaningful measurements**.
|
|
1137
|
-
|
|
1138
|
-
The first two profiles are what the per-provider auto-assignment
|
|
1139
|
-
applies (Anthropic → `claude-code`, OpenAI → `codex-safe`);
|
|
1140
|
-
`codex-variant` is the manual pick for `-codex`-family models:
|
|
1141
|
-
|
|
1142
|
-
| Profile | Use when your model is… | Workload | n | Δ vs OFF (mean cost) | What's compressed |
|
|
1143
|
-
|---|---|---|---|---|---|
|
|
1144
|
-
| **`claude-code`** *(default)* | Any Anthropic Claude model — `claude-sonnet-4-6`, `claude-opus-4-7`, `claude-haiku-4-5`, … | Refactor, Claude Sonnet 4.6 via Claude Code 2.1.158 | n=8 B vs n=4 OFF | **−6.9%** (CV 7.6%; tighter than OFF's 7.5%) | json + logs + code bodies + tool-defs trim (A2-adopted 2026-06-11: −12.5% vs the pre-A2 set, zero `tools_changed` cache events); cache-aware; stash disabled |
|
|
1145
|
-
| **`codex-variant`** | OpenAI's `-codex` reasoning fork — `gpt-5.3-codex`, `gpt-5.4-codex`, `gpt-5-codex-agent`, anything matching `*-codex*` | Refactor, gpt-5.3-codex | n=10 B vs n=10 OFF | **−10%** ($0.270 vs $0.300) | Tools-defs trim; cache-aware; no per-type compression |
|
|
1146
|
-
| **`codex-safe`** | Plain OpenAI GPT under the codex CLI — `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.5`, `gpt-4o`, any non-`-codex` | Refactor, gpt-5.4 + `apply_patch` | n=3 B vs n=4 OFF | not statistically distinguishable on this workload | logs + tools-defs trim (A6-adopted 2026-06-11: fired on 117/117 candidate requests, ~0.8KB/request of definition prose, task-completion parity + no cache degradation at n=9 vs n=7; effect scales with envelope bulk — MCP-registered installs save more); token mode |
|
|
1147
|
-
|
|
1148
|
-
The word **"variant"** in `codex-variant` refers to the *model variant* (the `-codex` reasoning fork of GPT), NOT a variant of the codex CLI. Both codex profiles are for the codex CLI; they differ only in which model family they assume. `codex-safe` is so named because plain GPT models tolerate logs trimming safely — it's not "safer than codex-variant."
|
|
1149
|
-
|
|
1150
|
-
**Honest caveats:**
|
|
1151
|
-
|
|
1152
|
-
- **Workload-dependent.** The `codex-safe` row on gpt-5.4 was
|
|
1153
|
-
inconclusive because the test workload used `apply_patch` (classified
|
|
1154
|
-
as `code`, not `logs`) so `compress_types=["logs"]` never fired —
|
|
1155
|
-
the proxy was a functional no-op and the cost variance was session
|
|
1156
|
-
noise. A Bash-heavy workload would tell a different story.
|
|
1157
|
-
- **`claude-code` requires `ENABLE_TOOL_SEARCH=true`** in your shell.
|
|
1158
|
-
Without it, Claude Code's SDK disables ToolSearch under
|
|
1159
|
-
`ANTHROPIC_BASE_URL` and eager-inlines all MCP schemas (~+21K
|
|
1160
|
-
tokens per turn). The proxy then becomes a net loss instead of
|
|
1161
|
-
the −6.9% above. Setup steps cover this; verify with
|
|
1162
|
-
`printenv ENABLE_TOOL_SEARCH`.
|
|
1163
|
-
- **`stash` stays disabled by default for Anthropic** (V7-25 finding:
|
|
1164
|
-
+25% cost on n=1 due to prefix-cache miss; stash markers break
|
|
1165
|
-
Anthropic's content-hash cache). Operators can opt in for a measured
|
|
1166
|
-
workload but should A/B their own.
|
|
1167
|
-
- **Historic claims of higher savings are retracted.** The v1.4.38
|
|
1168
|
-
release notes cited −14.8%; the project itself walked that back
|
|
1169
|
-
after a deeper repro showed it was within noise. The numbers above
|
|
1170
|
-
are the post-retraction floor.
|
|
1171
|
-
|
|
1172
|
-
**Reproduce it yourself:** the numbers above are workload-specific, not a
|
|
1173
|
-
guarantee — A/B your own traffic with `observer profile show <name>` and
|
|
1174
|
-
an OFF-baseline comparison before relying on any of them in production.
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
## Cost and token math
|
|
1178
|
-
|
|
1179
|
-
Anthropic's usage envelope reports four token buckets per request,
|
|
1180
|
-
each at a different rate:
|
|
1181
|
-
|
|
1182
|
-
| Bucket | What it is | Bills at |
|
|
1183
|
-
|--------------------|------------------------------------------------------------------------------|-----------------------------|
|
|
1184
|
-
| `net_input` | Fresh prompt tokens not served from cache | model's standard input rate |
|
|
1185
|
-
| `cache_read` | Prompt tokens served from Anthropic's ephemeral cache | ~10% of input rate |
|
|
1186
|
-
| `cache_creation` | Tokens written to ephemeral cache | 1.25× input (5m tier) or 2× input (1h tier) |
|
|
1187
|
-
| `output` | What the model generated | typically 5× input rate |
|
|
1188
|
-
|
|
1189
|
-
`prompt_context = net_input + cache_read + cache_creation`
|
|
1190
|
-
`total_tokens = prompt_context + output`
|
|
1191
|
-
|
|
1192
|
-
The cost engine (`internal/intelligence/cost`) computes USD via:
|
|
1193
|
-
|
|
1194
|
-
```
|
|
1195
|
-
cost_usd = (net_input × p.input + cache_read × p.cache_read +
|
|
1196
|
-
cache_creation_5m × p.cache_creation +
|
|
1197
|
-
cache_creation_1h × p.cache_creation_1h +
|
|
1198
|
-
output × p.output) ÷ 1,000,000
|
|
1199
|
-
```
|
|
1200
|
-
|
|
1201
|
-
When the upstream API returns `cost_usd` in the response envelope
|
|
1202
|
-
(proxy-sourced rows), that value is preferred over the computed one —
|
|
1203
|
-
ground truth, reliability=high.
|
|
1204
|
-
|
|
1205
|
-
### Blended input rate
|
|
1206
|
-
|
|
1207
|
-
The Discovery tab's "~$ wasted" tile uses a **blended input rate**
|
|
1208
|
-
computed from your last-30d api_turns mix: each model's input rate
|
|
1209
|
-
weighted by the prompt-token volume it consumed. Example: if you
|
|
1210
|
-
spent 70% of prompt tokens on opus-4-7 ($15/1M) and 30% on
|
|
1211
|
-
haiku-4-5 ($1/1M), the blended rate is `0.7 × 15 + 0.3 × 1 = $10.80/1M`.
|
|
1212
|
-
|
|
1213
|
-
Falls back to $3/1M (claude-sonnet-4 input) on fresh installs with
|
|
1214
|
-
no proxy data.
|
|
1215
|
-
|
|
1216
|
-
### JSONL dedup
|
|
1217
|
-
|
|
1218
|
-
When the proxy isn't engaged, observer falls back to parsing the AI
|
|
1219
|
-
client's on-disk session log. Clients echo the same cumulative usage
|
|
1220
|
-
on every content block of a multi-block response, so naive parsing
|
|
1221
|
-
counts one API call 2-4×. Two layers of dedup catch this:
|
|
1222
|
-
|
|
1223
|
-
1. **Adapter-level**: dedupes on Anthropic `message.id` at write time
|
|
1224
|
-
2. **Cost-engine-level**: dedupes on `(source_file, model, timestamp-bucketed-to-minute, tokens)` at read time
|
|
1225
|
-
|
|
1226
|
-
Migration 007 ran a one-time pass collapsing pre-fix duplicates.
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
## Security & control layer (guard)
|
|
1230
|
-
|
|
1231
|
-
The guard evaluates every captured agent action against a
|
|
1232
|
-
table-driven policy — built-in rules (destructive commands, project
|
|
1233
|
-
boundaries, secrets egress, MCP pinning, taint/dataflow, budgets)
|
|
1234
|
-
plus your own TOML rules — records each verdict in a hash-chained,
|
|
1235
|
-
tamper-evident audit table, and on the channels that support it can
|
|
1236
|
-
block before execution. It ships **observe-only by default**: a fresh
|
|
1237
|
-
install records and alerts, and never blocks anything until you
|
|
1238
|
-
explicitly flip enforce.
|
|
1239
|
-
|
|
1240
|
-
What makes it different from standalone command-guards:
|
|
1241
|
-
|
|
1242
|
-
- **One policy, every tool.** The same rules evaluate Claude Code,
|
|
1243
|
-
Codex, Cursor, Cline and the rest through one engine — and
|
|
1244
|
-
`observer init --guard` additionally *compiles* the policy into
|
|
1245
|
-
each client's own native permission dialect, so the client itself
|
|
1246
|
-
enforces even when the observer daemon is down.
|
|
1247
|
-
- **Replay before you enforce.** `observer guard simulate --since 168h`
|
|
1248
|
-
replays your real captured history against current policy and shows
|
|
1249
|
-
what last week WOULD have flagged or blocked — a confidence check
|
|
1250
|
-
only a tool that already has your history can run.
|
|
1251
|
-
- **Proxy-level secrets egress scanning.** Clients routed through the
|
|
1252
|
-
observer proxy get outbound API bodies scanned for credentials,
|
|
1253
|
-
with mask/deny enforcement — an egress point no other local-first
|
|
1254
|
-
tool sits on.
|
|
1255
|
-
- **Auditable, honestly.** Verdicts are hash-chained
|
|
1256
|
-
(tamper-EVIDENT, not tamper-proof — the docs say exactly what that
|
|
1257
|
-
means), exportable as JSONL/CEF for your SIEM, and summarized by
|
|
1258
|
-
`observer guard report` into a compliance evidence pack mapped to
|
|
1259
|
-
SOC 2 / NIST 800-53.
|
|
1260
|
-
- **Operable from the dashboard, not just the CLI.** The Security
|
|
1261
|
-
page runs the routine workflows end to end: a consent-gated mode
|
|
1262
|
-
control that shows the simulate evidence before you flip enforce,
|
|
1263
|
-
an Enforce-readiness replay over your real history, the approvals
|
|
1264
|
-
register (scoped, expiring exceptions — live immediately), a
|
|
1265
|
-
lint-gated policy editor for your user rules (malformed files are
|
|
1266
|
-
refused before they touch disk, with `.bak` undo), budget
|
|
1267
|
-
guardrails suggested from your own observed spend (p95 + headroom)
|
|
1268
|
-
with a daily burn-down meter, MCP pin approvals, and one-click
|
|
1269
|
-
compliance evidence downloads.
|
|
1270
|
-
- **Alerting, not just logging.** Guard verdicts and budget/obs-alert
|
|
1271
|
-
crossings can push out through desktop toast notifications
|
|
1272
|
-
(`[guard.alerts] desktop = true`) and outbound webhooks — generic,
|
|
1273
|
-
Slack, Discord, or PagerDuty (`[[guard.cloud.webhooks]]` for guard
|
|
1274
|
-
events) — each behind its own opt-in, routed through one egress
|
|
1275
|
-
worker with an endpoint allowlist and a payload cap. Nothing fires
|
|
1276
|
-
until you configure it.
|
|
1277
|
-
- **Optional process observability.** `[observer.process]` (opt-in,
|
|
1278
|
-
off by default) attaches the OS-level process tree — Linux eBPF or
|
|
1279
|
-
Windows ETW — beneath each captured session, for runtime side
|
|
1280
|
-
effects hooks alone can't see.
|
|
1281
|
-
|
|
1282
|
-
Honest scope: hooks see declared commands, not side effects (use OS
|
|
1283
|
-
sandboxes for containment — the guard detects and recommends them);
|
|
1284
|
-
most adapters are watcher-channel and can only flag post-hoc; the
|
|
1285
|
-
proxy scan only covers proxy-routed clients. The full capability
|
|
1286
|
-
matrix is on the dashboard's Security page, and the no-network
|
|
1287
|
-
invariant holds — nothing leaves your machine unless you opt into
|
|
1288
|
-
OTel export or the cloud alerting tier, each individually.
|
|
1289
|
-
|
|
1290
|
-
Quick start:
|
|
1291
|
-
|
|
58
|
+
observer start # proxy + watcher + dashboard; opens http://localhost:8081
|
|
59
|
+
observer scan # backfill history from the session logs already on disk
|
|
60
|
+
observer doctor # check the install
|
|
1292
61
|
```
|
|
1293
|
-
observer guard status # mode, rules, recent verdicts, chain check
|
|
1294
|
-
observer guard test "rm -rf ./build" # would this block?
|
|
1295
|
-
observer guard simulate --since 168h # what would last week have flagged?
|
|
1296
|
-
observer guard enable --enforce # flip to enforce when ready
|
|
1297
|
-
```
|
|
1298
|
-
|
|
1299
|
-
Full reference: [superbased.app/docs/guides/security-guard](https://superbased.app/docs/guides/security-guard)
|
|
1300
|
-
(concepts, modes, the observe→enforce path, the honest
|
|
1301
|
-
"what guard does NOT do" list). The rule catalog, policy-authoring cookbook,
|
|
1302
|
-
enforce runbook, and SOC 2 / NIST compliance mapping ship as
|
|
1303
|
-
`docs/guard-rules.md`, `docs/guard-policy-authoring.md`,
|
|
1304
|
-
`docs/guard-enforce-runbook.md`, and `docs/guard-compliance.md` in the
|
|
1305
|
-
source repository.
|
|
1306
|
-
|
|
1307
|
-
## Terminology and glossary
|
|
1308
|
-
|
|
1309
|
-
Quick reference; the in-platform help drawer (press `?` on the
|
|
1310
|
-
dashboard) has the full versions with cross-links.
|
|
1311
|
-
|
|
1312
|
-
- **Action** — one normalized tool call recorded by an adapter. Action
|
|
1313
|
-
types are taxonomic and cross-client: `read_file`, `write_file`,
|
|
1314
|
-
`edit_file`, `run_command`, `search_text`, `search_files`,
|
|
1315
|
-
`web_search`, `web_fetch`, `mcp_call`, `spawn_subagent`,
|
|
1316
|
-
`todo_update`, `ask_user`, `task_complete`, `user_prompt`,
|
|
1317
|
-
`api_error`, `turn_aborted` (interrupted before completion —
|
|
1318
|
-
distinct from task_complete/success=false; v1.4.22+),
|
|
1319
|
-
`context_compacted` (upstream-emitted compaction marker, not
|
|
1320
|
-
searchable like file edits; v1.4.22+), `system_prompt`
|
|
1321
|
-
(system/developer/user-envelope content; v1.4.23+), `unknown`.
|
|
1322
|
-
- **API turn** — one HTTP request captured by the local proxy. Records
|
|
1323
|
-
one row in `api_turns` per request, with the upstream usage envelope
|
|
1324
|
-
intact.
|
|
1325
|
-
- **Cache 5m vs 1h tier** — Anthropic's prompt cache has two TTLs.
|
|
1326
|
-
Default is 5 minutes; `cache_control: {type: ephemeral, ttl: 3600}`
|
|
1327
|
-
extends to 1 hour at 2× the write cost. Reads bill the same rate
|
|
1328
|
-
regardless of tier.
|
|
1329
|
-
- **Compression event** — one individual compression decision (one
|
|
1330
|
-
per-type compress, or one drop) recorded post migration 010.
|
|
1331
|
-
- **Conversation compression** — pre-forward trimming of API request
|
|
1332
|
-
bodies. Pass 1 = per-content-type compression, Pass 2 = drop with
|
|
1333
|
-
marker. See [Compression mechanisms](#compression-mechanisms).
|
|
1334
|
-
- **Cross-platform tool calling** — every AI client connected via
|
|
1335
|
-
`observer init` can call the 25 MCP tools (21 always-on + 4
|
|
1336
|
-
conditional) against the unified
|
|
1337
|
-
database. So Cursor's `get_last_test_result` can return a `go test`
|
|
1338
|
-
Claude Code ran an hour earlier.
|
|
1339
|
-
- **Cross-thread reread** — the parent thread re-reads a file the
|
|
1340
|
-
sub-agent already saw (or vice versa) within the same session. Fix:
|
|
1341
|
-
pass content via the Agent tool's `prompt` parameter rather than
|
|
1342
|
-
letting the child re-read.
|
|
1343
|
-
- **Freshness state** — per-read tag from the freshness engine: `fresh`
|
|
1344
|
-
(first read in this session, OR re-read with same content),
|
|
1345
|
-
`stale` (re-read after change in same session), `missing` (file no
|
|
1346
|
-
longer exists), `modified-elsewhere` (file changed by something
|
|
1347
|
-
other than an observable AI action).
|
|
1348
|
-
- **Mechanism** — one of `json`, `code`, `logs`, `text`, `diff`,
|
|
1349
|
-
`html` (per-content-type compressor) or `drop` (low-importance
|
|
1350
|
-
message replaced by a marker).
|
|
1351
|
-
- **Pattern** — a derived behaviour: `command_pair` (X often
|
|
1352
|
-
followed by Y), `cross_tool_file` (file touched by multiple
|
|
1353
|
-
clients), `knowledge_snippet` (consistent topic-specific habit),
|
|
1354
|
-
`failure_correlation` (X often precedes a failure of Y),
|
|
1355
|
-
`session_summary`. Each has a decay-weighted confidence score 0-1.
|
|
1356
|
-
- **Project** — working-directory root that owns sessions and
|
|
1357
|
-
actions. Derived from cwd at session start; `/.git/worktrees/...`
|
|
1358
|
-
paths fold back to the working-tree root.
|
|
1359
|
-
- **Proxy vs JSONL** — proxy intercepts upstream HTTP calls (ground
|
|
1360
|
-
truth, reliability=high). JSONL parses the AI client's on-disk
|
|
1361
|
-
session log (works without configuring a base URL, but client
|
|
1362
|
-
echoes cumulative usage on every block, requiring dedup —
|
|
1363
|
-
reliability=unreliable for token counts on Claude Code).
|
|
1364
|
-
- **Reliability** — cost-engine confidence: `high` (upstream-
|
|
1365
|
-
reported), `medium` (computed from known pricing), `low` (some
|
|
1366
|
-
buckets estimated), `unreliable` (no pricing entry).
|
|
1367
|
-
- **Session** — one continuous AI-coding conversation in a single
|
|
1368
|
-
tool, scoped to one working directory. Has a stable ID (Claude
|
|
1369
|
-
Code's UUID, Codex's rollout ID, …).
|
|
1370
|
-
- **Sidechain** — actions emitted inside a sub-agent runtime spawned
|
|
1371
|
-
via the parent's `Agent` tool. Sub-agents share the parent's
|
|
1372
|
-
session_id; the `is_sidechain` column distinguishes them. The
|
|
1373
|
-
Discovery tab's CROSS-THREAD column counts stale rereads that
|
|
1374
|
-
crossed this boundary.
|
|
1375
|
-
- **Stale reread** — same-session re-read of a file whose content
|
|
1376
|
-
changed between reads. Cross-session reads are excluded (a fresh
|
|
1377
|
-
session has no memory of a prior session's read).
|
|
1378
|
-
- **Tool** — in this dashboard, "tool" means the *AI client*
|
|
1379
|
-
(claude-code, cursor, codex, cline, cline-cli, copilot, copilot-cli,
|
|
1380
|
-
opencode, openclaw, pi, antigravity, gemini-cli, hermes, kilo-code,
|
|
1381
|
-
kilo-code-cli), not the per-tool name (`read_file`,
|
|
1382
|
-
`run_command`). The latter is "Tool name" on the Actions tab.
|
|
1383
|
-
- **Tool-pair integrity** — Anthropic requires every `tool_result`
|
|
1384
|
-
block to have a corresponding `tool_use` block in a preceding
|
|
1385
|
-
message. The compression pipeline preserves both sides of every
|
|
1386
|
-
live pair to satisfy this constraint.
|
|
1387
|
-
|
|
1388
|
-
|
|
1389
|
-
## CLI reference
|
|
1390
|
-
|
|
1391
|
-
Every command supports `--help` for the full surface.
|
|
1392
|
-
|
|
1393
|
-
| Subcommand | Purpose |
|
|
1394
|
-
|------------------------------------|---------|
|
|
1395
|
-
| `observer init` | Register hooks + MCP server + durable proxy routes with installed AI clients (each side defaults on; opt out with `--skip-hooks` / `--skip-mcp` / `--skip-proxy-route`). With **zero flags on a terminal** it runs an interactive checklist instead: detects your tools, previews each pending config write, and asks consent one write at a time (MCP never pre-selected). Any flag or redirected stdio keeps the batch behaviour. |
|
|
1396
|
-
| `observer uninstall` | Reverse `observer init` |
|
|
1397
|
-
| `observer start` | Run watcher + dashboard + proxy in one process (recommended). Auto-opens the dashboard on interactive launches. Flags: `--dashboard-addr ADDR` (default `127.0.0.1:8081`; for a durable setting use `[dashboard].addr` in config or the `OBSERVER_DASHBOARD_ADDR` env var — precedence flag > env > config > default), `--no-dashboard` to skip the HTTP UI, `--no-open` to skip the browser. |
|
|
1398
|
-
| `observer claude [-- args…]` | Launch Claude Code routed through the proxy for that session only (no config writes; fresh Pro/Max OAuth token re-exported so the SDK can't bypass). `--verify` runs pre-flight checks without launching. |
|
|
1399
|
-
| `observer codex [-- args…]` | Launch Codex routed through the proxy for that session only (injects `openai_base_url` via argv; no config writes). |
|
|
1400
|
-
| `observer watch` | Long-running JSONL watcher only |
|
|
1401
|
-
| `observer dashboard --addr ADDR` | HTTP dashboard only. `--addr`/`--port` still win when passed; otherwise falls back to `OBSERVER_DASHBOARD_ADDR` > `[dashboard].addr` config > default. |
|
|
1402
|
-
| `observer proxy start` | Reverse proxy only |
|
|
1403
|
-
| `observer scan` | One-shot ingest of existing JSONL files (catch-up after install) |
|
|
1404
|
-
| `observer status` | DB stats + recent activity |
|
|
1405
|
-
| `observer doctor` | Diagnostic — checks paths, schemas, hook registration |
|
|
1406
|
-
| `observer tail` | Live tail of incoming events |
|
|
1407
|
-
| `observer cost` | Per-model cost summary CLI |
|
|
1408
|
-
| `observer score` | Compute quality_score / error_rate / redundancy_ratio for sessions |
|
|
1409
|
-
| `observer discover` | Stale rereads + repeated commands report (CLI version of the Discovery tab) |
|
|
1410
|
-
| `observer patterns` | Derive patterns from session history |
|
|
1411
|
-
| `observer learn` | Adapter for ingesting external JSONL exports |
|
|
1412
|
-
| `observer suggest` | Write high-confidence patterns into CLAUDE.md / AGENTS.md / .cursorrules |
|
|
1413
|
-
| `observer summarize` | Roll-up summary across sessions |
|
|
1414
|
-
| `observer export` | Export DB to xlsx / json |
|
|
1415
|
-
| `observer prune` | Manual retention pass (delete old data) |
|
|
1416
|
-
| `observer db stats\|vacuum\|backup` | Storage manager. `stats`: per-table size breakdown (index + FTS5 shadow bytes folded into the table they serve). `vacuum`: reclaim free pages, reports bytes freed (can report SQLITE_BUSY against a busy daemon — re-run in a quiet moment). `backup <path>`: online snapshot via SQLite `VACUUM INTO` — safe while the daemon runs, refuses to overwrite. Restore is manual by design: stop daemon, swap file, start. |
|
|
1417
|
-
| `observer db import <path>` | Merge another `observer.db` into this node's (a stranded install from another OS or home directory). Set-based, single-transaction, idempotent — re-running adds nothing twice; project identities remap by root path. `--dry-run` executes the same transaction and rolls it back, so its per-table counts are exact. Migrates the source schema first — point it at a copy. Node-local state (cache tracking, watcher cursors, advisor state) doesn't transfer. |
|
|
1418
|
-
| `observer backfill --is-sidechain` | Re-walk JSONL to populate `actions.is_sidechain` (added by migration 010) on pre-migration rows. |
|
|
1419
|
-
| `observer backfill --cache-tier` | Re-walk JSONL to populate `cache_creation_1h_tokens` (added by migration 008) on pre-migration rows. Run once after upgrading to v1.4.16+ to correct historical 1h-tier cache writes that were silently billed at the cheaper 5m rate. |
|
|
1420
|
-
| `observer backfill --message-id` | Re-walk JSONL to populate `message_id` on `actions` and `token_usage` (added by migration 012). Required by the per-message timeline view in the Sessions modal. |
|
|
1421
|
-
| `observer backfill --all` | Run every supported backfill in one invocation. Idempotent — safe to re-run. |
|
|
1422
|
-
| `observer reprice` | Re-price stored costs at the rate in force when each turn ran. Dry run by default; `--apply` writes, `--revert <run>` undoes a run, `--list` shows history, `--since` / `--until` / `--model` narrow it. Never overwrites a tool-reported cost. |
|
|
1423
|
-
| `observer project <id\|root>` | Per-project spend, AI lines (code vs comments), commits and prompt-to-commit status - the dashboard's Projects detail in the terminal. |
|
|
1424
|
-
| `observer shell-wrap status\|preview\|enable\|disable` | Opt-in command wrapping: PATH shims so typing `claude` runs `observer claude` (per tool, exact preview, byte-for-byte undo). |
|
|
1425
|
-
| `observer ide <id> [project-dir]` | Launch an IDE or desktop app the way the dashboard does and report whether its AI traffic can be routed through the proxy. |
|
|
1426
|
-
| `observer profile list\|show\|assign\|create\|delete\|set` | Compression profiles: inspect built-ins, reassign per traffic class or per tool (`assign tool:cline codex-safe`), create/edit custom profiles. Edits apply to new sessions hot. |
|
|
1427
|
-
| `observer config set <key> <value>` | Dotted-key config setter (`compression.conversation.enabled true`). `--project <root>` writes a per-repo override file instead. |
|
|
1428
|
-
| `observer advise` | Prescriptive cost/quality suggestions from captured activity (the Suggestions tab, in the CLI) |
|
|
1429
|
-
| `observer cache-health` | Prompt-cache engine health: grading gate, read:write consistency, cause concentration |
|
|
1430
|
-
| `observer metrics` | Prometheus-format metrics endpoint |
|
|
1431
|
-
| `observer serve` | MCP server (stdio JSON-RPC) — usually invoked by `observer init` registration |
|
|
1432
|
-
| `observer completion <shell>` | Generate shell completions (bash / zsh / fish / powershell) — e.g. `observer completion zsh > "${fpath[1]}/_observer"` |
|
|
1433
|
-
|
|
1434
|
-
|
|
1435
|
-
## Configuration
|
|
1436
62
|
|
|
1437
|
-
|
|
63
|
+
For provider-exact tokens, route your agent through the proxy: in the dashboard open Compression,
|
|
64
|
+
click your tool's status pill and choose **Route through the observer proxy** (it previews the
|
|
65
|
+
config change and writes only when you confirm), or run `observer claude` / `observer codex` for a
|
|
66
|
+
one-off proxied session. `observer init` additionally registers the opt-in MCP server.
|
|
1438
67
|
|
|
1439
|
-
|
|
1440
|
-
[paths]
|
|
1441
|
-
db_path = "~/.observer/observer.db"
|
|
1442
|
-
log_dir = "~/.observer/logs"
|
|
68
|
+
## What you get
|
|
1443
69
|
|
|
1444
|
-
|
|
1445
|
-
|
|
1446
|
-
|
|
1447
|
-
|
|
1448
|
-
|
|
70
|
+
- A local dashboard for sessions, cost, cache, security and live activity, filterable by tool and
|
|
71
|
+
project.
|
|
72
|
+
- Cost per session, model, project and tool, with cache read/write splits down to each API turn.
|
|
73
|
+
- An opt-in MCP server so your agents can query their own history across tools.
|
|
74
|
+
- Waste detection: stale re-reads, repeated commands and files several agents fight over.
|
|
75
|
+
- Dashboard terminals with multi-seat join and native resume.
|
|
76
|
+
- A CLI for everything: `observer usage`, `cost`, `predict`, `tail`, `statusline`.
|
|
1449
77
|
|
|
1450
|
-
|
|
1451
|
-
# Durable dashboard listen address as host:port. Empty/omitted = the built-in
|
|
1452
|
-
# 127.0.0.1:8081 default. Precedence: `observer start --dashboard-addr` flag >
|
|
1453
|
-
# OBSERVER_DASHBOARD_ADDR env var > this value > default. Binds at daemon start
|
|
1454
|
-
# (restart to apply). A non-loopback host still fails closed unless [remote] is
|
|
1455
|
-
# armed.
|
|
1456
|
-
addr = "127.0.0.1:8081"
|
|
78
|
+
## Privacy
|
|
1457
79
|
|
|
1458
|
-
|
|
1459
|
-
|
|
1460
|
-
|
|
1461
|
-
|
|
1462
|
-
preserve_last_n = 5
|
|
1463
|
-
compress_types = ["json", "logs", "code"] # default; add "text"/"diff"/"html" to opt in
|
|
80
|
+
No telemetry and no account. SuperBased stores paths, commands and short excerpts, scrubs secrets
|
|
81
|
+
before writing, and binds the proxy and dashboard to `127.0.0.1` by default. The proxy forwards your
|
|
82
|
+
own requests, unchanged, to the provider you already use. See
|
|
83
|
+
[PRIVACY.md](https://github.com/superbasedapp/observer/blob/main/PRIVACY.md).
|
|
1464
84
|
|
|
1465
|
-
|
|
1466
|
-
enabled = true
|
|
1467
|
-
# per-command filters configured under [compression.shell.filters]
|
|
1468
|
-
|
|
1469
|
-
[retention]
|
|
1470
|
-
prune_on_startup = true
|
|
1471
|
-
max_actions = 5_000_000
|
|
1472
|
-
max_age_days = 365
|
|
1473
|
-
|
|
1474
|
-
[pricing]
|
|
1475
|
-
# Per-model overrides if the baked-in pricing is wrong for you.
|
|
1476
|
-
# [pricing.models."claude-opus-4-7"]
|
|
1477
|
-
# input = 15
|
|
1478
|
-
# output = 75
|
|
1479
|
-
# cache_read = 1.5
|
|
1480
|
-
# cache_creation = 18.75
|
|
1481
|
-
```
|
|
85
|
+
## Learn more
|
|
1482
86
|
|
|
87
|
+
- [Documentation](https://superbased.app/docs) and [quickstart](https://superbased.app/docs/getting-started/quickstart)
|
|
88
|
+
- [Supported agents and per-tool setup](https://superbased.app/docs/track/overview)
|
|
89
|
+
- [How SuperBased compares](https://superbased.app/docs/compare/overview)
|
|
90
|
+
- [Source, issues and changelog](https://github.com/superbasedapp/observer)
|
|
1483
91
|
|
|
1484
92
|
## Troubleshooting
|
|
1485
93
|
|
|
1486
|
-
|
|
1487
|
-
|
|
1488
|
-
|
|
1489
|
-
|
|
1490
|
-
|
|
1491
|
-
|
|
1492
|
-
# 1) RECOMMENDED — point npm at a user-writable prefix.
|
|
1493
|
-
mkdir -p ~/.npm-global
|
|
1494
|
-
npm config set prefix '~/.npm-global'
|
|
1495
|
-
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
|
|
1496
|
-
source ~/.zshrc
|
|
1497
|
-
npm install -g @superbased/observer
|
|
1498
|
-
|
|
1499
|
-
# 2) Use a Node version manager — fnm / nvm install Node into your
|
|
1500
|
-
# home directory and dodge the permission issue entirely.
|
|
1501
|
-
brew install fnm
|
|
1502
|
-
fnm install --lts
|
|
1503
|
-
npm install -g @superbased/observer
|
|
1504
|
-
|
|
1505
|
-
# 3) sudo (works but you'll fight permissions on every update).
|
|
1506
|
-
sudo npm install -g @superbased/observer
|
|
1507
|
-
```
|
|
1508
|
-
|
|
1509
|
-
### `observer: command not found` after install
|
|
1510
|
-
|
|
1511
|
-
The shim binary is at `~/.npm-global/bin/observer` (or wherever your
|
|
1512
|
-
npm prefix points). Make sure that directory is on `$PATH`:
|
|
1513
|
-
|
|
1514
|
-
```bash
|
|
1515
|
-
echo $PATH | tr ':' '\n' | grep -E 'npm|node'
|
|
1516
|
-
# add the prefix's bin/ to PATH if missing — see fix above
|
|
1517
|
-
```
|
|
1518
|
-
|
|
1519
|
-
If you installed only a platform package (e.g. `@superbased/observer-darwin-x64`)
|
|
1520
|
-
without the main `@superbased/observer`, the shim doesn't get created
|
|
1521
|
-
— there's no `bin` field. Install the main package; npm picks up the
|
|
1522
|
-
right platform binary automatically via `optionalDependencies`.
|
|
1523
|
-
|
|
1524
|
-
### `observer init` says "no tools selected and none auto-detected"
|
|
1525
|
-
|
|
1526
|
-
Auto-detection looks for the AI clients' default session-log dirs
|
|
1527
|
-
(`~/.claude/projects/`, `~/.codex/sessions/`, `~/.cursor/`, etc.).
|
|
1528
|
-
On a fresh machine where no client has run yet, those dirs don't
|
|
1529
|
-
exist. Pass the flag explicitly:
|
|
1530
|
-
|
|
1531
|
-
```bash
|
|
1532
|
-
observer init --claude-code # or --codex / --cursor / --cline / --all
|
|
1533
|
-
```
|
|
1534
|
-
|
|
1535
|
-
This registers hooks regardless — the next time the client runs,
|
|
1536
|
-
its dirs get created and the watcher picks them up.
|
|
1537
|
-
|
|
1538
|
-
### Empty dashboard / "No proxy traffic"
|
|
1539
|
-
|
|
1540
|
-
Session/action data populates passively whenever `observer start` is
|
|
1541
|
-
running, but ground-truth cost / compression numbers require the
|
|
1542
|
-
proxy. Route your tool through it — the quickest way is the
|
|
1543
|
-
dashboard's Compression tab → **Proxy** banner → **Route through the
|
|
1544
|
-
observer proxy…** button; every other mechanism (wrappers, env vars,
|
|
1545
|
-
`observer init`) is listed under
|
|
1546
|
-
[Per-AI-client setup](#per-ai-client-setup).
|
|
1547
|
-
|
|
1548
|
-
Verify with `observer status | grep api_turns` — count should
|
|
1549
|
-
climb during AI-client activity.
|
|
1550
|
-
|
|
1551
|
-
### `observer --version` says `dev`
|
|
1552
|
-
|
|
1553
|
-
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.
|
|
1554
|
-
|
|
1555
|
-
### `tool_result block must have a corresponding tool_use block`
|
|
1556
|
-
|
|
1557
|
-
Anthropic 400. Means the conversation-compression pipeline dropped
|
|
1558
|
-
a `tool_use` while keeping its matching `tool_result`. Versions
|
|
1559
|
-
prior to 1.3.2 had this bug; upgrade. If you're on 1.3.2+ and still
|
|
1560
|
-
see it, file an issue with the conversation prefix.
|
|
1561
|
-
|
|
1562
|
-
### `tool use concurrency issues`
|
|
1563
|
-
|
|
1564
|
-
Anthropic 400 surfaced in Claude Code as this message. Means the
|
|
1565
|
-
parallel-tool-use case (multiple `tool_use` blocks in one assistant
|
|
1566
|
-
message) isn't paired correctly with the multi-block tool_result
|
|
1567
|
-
that follows. Versions prior to 1.3.2 had this bug; upgrade.
|
|
1568
|
-
|
|
1569
|
-
### Cross-thread numbers are 0
|
|
1570
|
-
|
|
1571
|
-
Pre-migration data was ingested without the `is_sidechain` flag.
|
|
1572
|
-
Run `observer backfill --is-sidechain` once to re-walk JSONL and
|
|
1573
|
-
populate the flag on existing rows.
|
|
1574
|
-
|
|
1575
|
-
### Migration error: `duplicate column name`
|
|
1576
|
-
|
|
1577
|
-
Race condition between concurrent daemon startups, fixed in 1.4.1.
|
|
1578
|
-
Upgrade. If you still see it, run daemons serially: `observer
|
|
1579
|
-
watch`, wait, then `observer dashboard`, then `observer proxy
|
|
1580
|
-
start` (or just use `observer start` which runs all three in one
|
|
1581
|
-
process — proxy + watcher + dashboard).
|
|
1582
|
-
|
|
1583
|
-
### `observer start` log says only `proxy + observer` — no `:8081`
|
|
1584
|
-
|
|
1585
|
-
You're on a pre-1.4.7 build. Earlier versions ran only proxy +
|
|
1586
|
-
watcher under `observer start`; the dashboard had to be started
|
|
1587
|
-
separately via `observer dashboard --addr 127.0.0.1:8081`. Upgrade
|
|
1588
|
-
to 1.4.7+ — the dashboard goroutine is now part of `observer start`
|
|
1589
|
-
and the log line confirms all three: `proxy <addr> + watcher +
|
|
1590
|
-
dashboard http://127.0.0.1:8081`. Pass `--no-dashboard` to opt out.
|
|
1591
|
-
|
|
1592
|
-
### "address already in use" on port 8820
|
|
1593
|
-
|
|
1594
|
-
Another `observer proxy start` or `observer start` is still running.
|
|
1595
|
-
Find it with `pgrep -af 'observer (proxy|start)'` and `kill <pid>`.
|
|
1596
|
-
On macOS:
|
|
1597
|
-
|
|
1598
|
-
```bash
|
|
1599
|
-
lsof -nP -iTCP:8820 -sTCP:LISTEN
|
|
1600
|
-
kill <pid>
|
|
1601
|
-
```
|
|
1602
|
-
|
|
1603
|
-
### Dashboard port already in use
|
|
1604
|
-
|
|
1605
|
-
```bash
|
|
1606
|
-
observer dashboard --addr 127.0.0.1:8082 # pick a different port
|
|
1607
|
-
# or
|
|
1608
|
-
[dashboard]
|
|
1609
|
-
port = 8082 # in config.toml
|
|
1610
|
-
```
|
|
1611
|
-
|
|
1612
|
-
|
|
1613
|
-
## Security and privacy
|
|
1614
|
-
|
|
1615
|
-
**Local-only. No telemetry. No remote anything.** The watcher, hook
|
|
1616
|
-
handler, dashboard, MCP server, and CLI never make an outbound network
|
|
1617
|
-
call on observer's behalf. The only code paths that touch the network
|
|
1618
|
-
are the optional API proxy (which forwards **your** requests unchanged
|
|
1619
|
-
to the AI provider you already use) and a handful of explicit opt-in
|
|
1620
|
-
features (message-summary LLM, codeintel MCP).
|
|
1621
|
-
|
|
1622
|
-
The full privacy statement — what observer stores, what it reads,
|
|
1623
|
-
what it never stores, the explicit list of outbound-network call sites
|
|
1624
|
-
gated behind config, and how to verify "no telemetry" yourself with
|
|
1625
|
-
`grep`, `strings`, and a network-namespaced shell — lives in
|
|
1626
|
-
[`PRIVACY.md`](https://github.com/superbasedapp/observer/blob/main/PRIVACY.md).
|
|
1627
|
-
|
|
1628
|
-
Operational shorthand:
|
|
1629
|
-
|
|
1630
|
-
- **Local-only HTTP.** The proxy and dashboard bind to `127.0.0.1`
|
|
1631
|
-
by default. Don't bind to `0.0.0.0` unless you've thought about
|
|
1632
|
-
it — there's no auth.
|
|
1633
|
-
- **Secrets scrubbing.** Tool inputs and outputs pass through
|
|
1634
|
-
`internal/scrub/` before persistence; review the regex set if your
|
|
1635
|
-
secrets follow non-default formats.
|
|
1636
|
-
- **Database.** `~/.observer/observer.db` is a SQLite file with the
|
|
1637
|
-
same security posture as your `~/.claude/` and `~/.codex/` session
|
|
1638
|
-
logs (which already hold the same content). Encrypt the disk if
|
|
1639
|
-
your threat model needs that.
|
|
1640
|
-
- **Full delete.** `rm -rf ~/.observer/` removes everything observer
|
|
1641
|
-
ever stored — no traces elsewhere on your system.
|
|
1642
|
-
|
|
1643
|
-
|
|
1644
|
-
## Source, contributing, license
|
|
94
|
+
- **`EACCES` on `npm install -g`:** point npm at a user prefix
|
|
95
|
+
(`npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to `PATH`) or use a Node version
|
|
96
|
+
manager such as fnm or nvm.
|
|
97
|
+
- **`observer: command not found`:** make sure your npm global `bin` directory is on `PATH`, and that
|
|
98
|
+
you installed `@superbased/observer` itself, not only a platform package.
|
|
99
|
+
- **Port 8820 or 8081 already in use:** another `observer start` is running; stop it first.
|
|
1645
100
|
|
|
1646
|
-
|
|
1647
|
-
- **Specification**: `superbased-final-spec-v2.md` in the repo
|
|
1648
|
-
- **Issues**: https://github.com/superbasedapp/observer/issues
|
|
1649
|
-
- **License**: [Apache 2.0](https://github.com/superbasedapp/observer/blob/main/LICENSE)
|
|
1650
|
-
- **Author**: Santosh Kathira <contact@superbased.app>
|
|
101
|
+
## License
|
|
1651
102
|
|
|
1652
|
-
This
|
|
1653
|
-
|
|
1654
|
-
`swc` / `@biomejs/biome`. The Go source lives in the main repo;
|
|
1655
|
-
binaries are cross-compiled per release tag via GitHub Actions and
|
|
1656
|
-
published as `@superbased/observer-<platform>-<arch>` per-platform
|
|
1657
|
-
packages.
|
|
103
|
+
Apache 2.0. This package is a small Node.js shim that runs the prebuilt binary from the matching
|
|
104
|
+
`@superbased/observer-<platform>-<arch>` package.
|