AI工具监控助手

Install

Pick whichever package manager fits your environment — npm and PyPI ship the same prebuilt binary from the same v* tag, version numbers kept in lock-step.

Via pip / uv / pipx (recommended for Python users)

pip install superbased-observer            # plain pip
uv tool install superbased-observer        # uv (isolated env, fastest)
pipx install superbased-observer           # pipx (isolated env)
observer --version

Wheels ship for manylinux2014_{x86_64,aarch64}, macosx_*_{x86_64,arm64}, and win_amd64. uv tool and pipx keep the install isolated from your project's Python env — generally what you want for a CLI tool.

Via go install (latest main, builds locally)

go install github.com/marmutapp/superbased-observer/cmd/observer@latest
observer --version

Verifying the install

observer doctor          # health checks: DB integrity, hook
                         # registration, MCP entries, pid bridge
observer status          # row counts + recent activity
observer tail            # live-stream captured actions

---

Build from source

git clone https://github.com/marmutapp/superbased-observer
cd superbased-observer
make build        # builds bin/observer + bin/antigravity-bridge.exe
make test         # full test suite (race detector enabled)
make all          # fmt + vet + lint + test + build

Requirements: Go 1.22+. No CGO. SQLite via modernc.org/sqlite (pure Go). golangci-lint optional for make lint. Dashboard source under web/ (React + TypeScript + Vite + Tailwind); the compiled bundle is committed to internal/intelligence/dashboard/webapp/dist/ so a contributor who only touches Go can make build without Node.

If you edit web/src/:

```bash

When done, rebuild the embedded bundle and commit

make web-build git add internal/intelligence/dashboard/webapp/dist web/dist ```

make web-build regenerates both web/dist and the embedded copy. Requires Node 22 LTS.

Linux x64 example — substitute your platform + version.

VERSION=v1.6.21 PLAT=linux-x64 curl -L -O https://github.com/marmutapp/superbased-observer/releases/download/$VERSION/observer-$VERSION-$PLAT.tar.gz curl -L -O https://github.com/marmutapp/superbased-observer/releases/download/$VERSION/SHA256SUMS shasum -a 256 -c SHA256SUMS --ignore-missing tar -xzf observer-$VERSION-$PLAT.tar.gz ./observer --version ```

The binary is pure Go — no CGO, no external runtime dependencies. SQLite storage is pure-Go via modernc.org/sqlite. Single static binary; scp it anywhere it runs. Same artifacts ship to npm and to the Releases page (build-once-ship-everywhere CI), so the npm and direct-download paths produce byte-identical binaries.

---

Long-context tier example (Anthropic Sonnet 1M, gpt-5 >272K,

Patches ~/.claude/settings.json, ~/.cursor/hooks.json,

~/.claude.json, ~/.cursor/mcp.json, ~/.codex/config.toml.

observer init --all

Claude Code (Anthropic) — both env vars matter:

export ANTHROPIC_BASE_URL=http://localhost:8820 export ENABLE_TOOL_SEARCH=true # ← required; without it the proxy is a net loss

Settings — every config knob, editable

<p align="center"> <img src="docs/assets/screenshots/09-settings.png" alt="Settings tab" width="900"> </p>

Pricing overrides hot-reload (no daemon restart — cost.Engine swaps the pricing table atomically). 156 baked-in default models; "Override" prompts auto-fill from the default. Backfill mode panel spawns observer backfill as a child process with live output streamed back. Watcher / Freshness / Retention / Hooks / Proxy / Compression / Intelligence sections are schema-driven forms with inline help. Restart-required banner appears when a section is saved that the daemon binds at startup.

Configuration

Default location: ~/.observer/config.toml. Override with --config. A minimal config:

```toml [observer] db_path = "~/.observer/observer.db" log_level = "info"

[proxy] enabled = true port = 8820 anthropic_upstream = "https://api.anthropic.com" openai_upstream = "https://api.openai.com"

[intelligence] monthly_budget_usd = 100 # surfaces on Analysis tab; 0 hides

[compression.shell] enabled = true exclude_commands = ["curl", "playwright"]

[compression.indexing] enabled = true max_excerpt_bytes = 2048

[compression.conversation] enabled = false # opt-in; modifies request bodies in flight mode = "cache_aware" # "token" | "cache" | "cache_aware" — see "Choosing a compression mode" below target_ratio = 0.85 preserve_last_n = 5 compress_types = ["json", "logs", "code"]

API proxy — accurate tokens, compression, stash

The proxy is the home of three features that only exist when your AI client routes through it. None of them run on the watcher / `observer start` ingestion path — compression and stash live in the request path because that's the only place where bytes can be rewritten before they reach the upstream provider.

When you point your AI tool at http://localhost:8820, the proxy:

1. Forwards your request to your chosen upstream (Anthropic or OpenAI). The destination is the same provider URL your AI client would have called directly; no data leaves your machine that wasn't already going to that provider. Your API key is yours — the proxy reads it from the inflight headers, never stores it. 2. Records the exact token counts the provider returned (cache 5m vs 1h split, long-context tier triggers, reasoning tokens) into the api_turns table — more accurate than parsing the JSONL the AI tool wrote. 3. Compresses the conversation before forwarding (importance-scored, prefix-stable for cache alignment) — the biggest lever for keeping long sessions inside rate-limit windows. On by default as of v1.7.23 with the safe per-type set (compress_types = ["json","logs","code"]); opt out via [compression.conversation].enabled = false or compress_types = []. Compressed events land in the compression_events table and surface on the Compression dashboard tab. Empirical on Claude Code lumen rig (n=8, V7-22): −6.9% mean cost vs no-proxy, CV 7.6%, zero tail outliers. 4. Stashes large tool outputs the compressor hides, so the originals stay retrievable via the retrieve_stashed MCP tool (only registered when stash is configured). Off by default — stash markers break Anthropic's prefix cache (V7-25 n=1 measurement: +25% cost, cache_creation_input_tokens doubled). Operators who want stash on a workload should A/B before committing.

Three compression layers, each independently toggleable:

- Shell output filters — RTK-style truncation of large bash / git / go test / docker / kubectl / cargo / pytest outputs inline before they hit the LLM context. Runs on hook / observer run paths; does not require the proxy. - Tool output indexing — every tool call's output indexed into FTS5; large outputs trimmed to a 2KB excerpt cap so the index stays compact and search_past_outputs stays fast. Runs on the watcher path; does not require the proxy. - Conversation compression — proxy rewrites large tool_result blocks before forwarding upstream. Proxy-only — there is no non-proxy path for this layer, and the stash that backs retrieve_stashed is wired here too.

Trade-off if you skip the proxy: you still get full hook + JSONL ingestion, the dashboard, MCP (if registered), and shell+indexing compression. You lose proxy-grade token accuracy, conversation compression, and the stash. For rate-limited plans (Claude Teams 5h/7d windows), conversation compression is usually the difference between "finishes the task" and "hits the limit."

CLI reference

observer <command> --help for full flag listings.

---

Hot-reload dev loop (Vite serves :5173, proxies /api/* to observer)

./bin/observer dashboard --addr 127.0.0.1:8081 & cd web && npm install && npm run dev

Via VS Code (Marketplace or Open VSX)

code --install-extension superbased.superbased-observer

The VS Code extension bundles the observer binary, lifts the dashboard / sidebar / status bar / file decorations into the editor, and contributes a terminal profile that pre-exports the proxy env vars so AI CLIs launched from it route through observer automatically. Cursor, VSCodium, and Windsurf install the same VSIX via Open VSX.

After install, VS Code's Get Started page surfaces an in-editor walkthrough; the long-form user guide lives at docs/vscode-extension-user-guide.md and the command + settings reference is at docs/vscode-extension.md.

Choosing a compression mode (Anthropic vs Codex)

[compression.conversation].mode behaves differently per provider. Per-type tool_result compression runs in every mode; mode only changes how messages are dropped and whether an Anthropic cache_control marker is injected.

The shipped default is cache_aware (token is just the internal fallback when mode is empty). The cache/cache_aware strategies exist for Anthropic's content-hash prefix cache (cache_control is an Anthropic Messages API concept). OpenAI/Codex prompt caching is automatic and server-side — there is nothing to mark or tune, so the proxy's OpenAI path is mode-agnostic (the default cache_aware simply behaves like token there).

Pick one of three shipped recipes based on which model you're running:

"variant" in codex-variant means the -codex model variant, not a variant of the codex CLI — both codex recipes are for the codex CLI; the split is purely about which model family it's pointed at.

```toml