@superbased/observer 1.34.0 → 1.37.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 +121 -1627
- package/bin/observer.js +6 -2
- package/bin/postinstall.js +156 -0
- package/package.json +25 -19
- package/README.template.md +0 -335
package/bin/observer.js
CHANGED
|
@@ -32,13 +32,17 @@ function reportUnsupported(key) {
|
|
|
32
32
|
}
|
|
33
33
|
|
|
34
34
|
function reportMissingPackage(pkg) {
|
|
35
|
+
// On Windows name npm.cmd: PowerShell's default execution policy refuses
|
|
36
|
+
// the npm.ps1 shim a bare `npm` resolves to, and npm.cmd also runs in
|
|
37
|
+
// Command Prompt.
|
|
38
|
+
const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
|
|
35
39
|
process.stderr.write(
|
|
36
40
|
'@superbased/observer: optional dependency ' + pkg + ' is not installed.\n' +
|
|
37
41
|
'This usually means npm skipped optional dependencies during install.\n' +
|
|
38
42
|
'Retry with:\n' +
|
|
39
|
-
' npm install --include=optional @superbased/observer\n' +
|
|
43
|
+
' ' + npm + ' install --include=optional @superbased/observer\n' +
|
|
40
44
|
'or, if installed globally:\n' +
|
|
41
|
-
' npm install -g --include=optional @superbased/observer\n'
|
|
45
|
+
' ' + npm + ' install -g --include=optional @superbased/observer\n'
|
|
42
46
|
);
|
|
43
47
|
process.exit(1);
|
|
44
48
|
}
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// @superbased/observer postinstall: PRINT-ONLY (T-753).
|
|
3
|
+
//
|
|
4
|
+
// `npm install -g` over an older version swaps the platform package's
|
|
5
|
+
// directory underneath a running Observer daemon: the old process keeps
|
|
6
|
+
// running the deleted binary until it is restarted (the rc.3 roll found
|
|
7
|
+
// every npm node in that state). npm must never restart it: the daemon IS the
|
|
8
|
+
// proxy on :8820, and stopping it while an AI session routes through it
|
|
9
|
+
// breaks that session (docs/daemon-restart-runbook.md). So this script only
|
|
10
|
+
// looks (Linux: /proc/<pid>/exe of `observer start` processes running a
|
|
11
|
+
// replaced @superbased package binary, see below) and prints what to run. It
|
|
12
|
+
// never downloads, writes, signals or fails the install.
|
|
13
|
+
//
|
|
14
|
+
// npm 10 does NOT delete the old package directory before this script runs
|
|
15
|
+
// (T-756, seen on the rc.4 roll): reify renames it aside to a retired dot-dir
|
|
16
|
+
// (@superbased/.observer-linux-x64-<random>/), runs postinstall, and only
|
|
17
|
+
// then removes it. At this point the daemon's exe therefore reads the
|
|
18
|
+
// retired path WITHOUT "(deleted)". So a daemon is stale when its executable
|
|
19
|
+
// is an @superbased observer binary and any of these holds: the file was
|
|
20
|
+
// deleted, it lives under a retired dot-dir, or it is not the binary this
|
|
21
|
+
// install just put in place.
|
|
22
|
+
//
|
|
23
|
+
// npm 7 and later hide lifecycle-script output unless --foreground-scripts,
|
|
24
|
+
// so the note goes to the controlling terminal when there is one, else to
|
|
25
|
+
// stderr. OBSERVER_POSTINSTALL_PROC_ROOT points it at a fixture /proc and
|
|
26
|
+
// OBSERVER_POSTINSTALL_INSTALLED_BINARY names the installed binary
|
|
27
|
+
// (scripts/test-npm-postinstall.sh); they only change where it reads.
|
|
28
|
+
'use strict';
|
|
29
|
+
|
|
30
|
+
const fs = require('fs');
|
|
31
|
+
const path = require('path');
|
|
32
|
+
|
|
33
|
+
const DELETED = ' (deleted)';
|
|
34
|
+
|
|
35
|
+
// installedBinary is the real path of the platform binary this install put in
|
|
36
|
+
// place, or '' when it cannot be resolved (then only the deleted and
|
|
37
|
+
// retired-dir shapes count).
|
|
38
|
+
function installedBinary() {
|
|
39
|
+
const override = process.env.OBSERVER_POSTINSTALL_INSTALLED_BINARY;
|
|
40
|
+
if (override) return override;
|
|
41
|
+
try {
|
|
42
|
+
const pkg = '@superbased/observer-' + process.platform + '-' + process.arch;
|
|
43
|
+
return fs.realpathSync(require.resolve(pkg + '/bin/observer'));
|
|
44
|
+
} catch (_) {
|
|
45
|
+
return '';
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
// retiredDir reports whether bin sits under a directory npm renamed aside:
|
|
50
|
+
// a path segment after @superbased/ that starts with a dot.
|
|
51
|
+
function retiredDir(bin) {
|
|
52
|
+
const i = bin.indexOf('/@superbased/');
|
|
53
|
+
if (i < 0) return false;
|
|
54
|
+
return bin
|
|
55
|
+
.slice(i + '/@superbased/'.length)
|
|
56
|
+
.split('/')
|
|
57
|
+
.some((seg) => seg.startsWith('.'));
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// staleDaemons lists `observer start` processes whose executable is an
|
|
61
|
+
// @superbased package binary that this install replaced: deleted, under a
|
|
62
|
+
// retired dot-dir, or simply not the installed binary.
|
|
63
|
+
function staleDaemons(procRoot, installed) {
|
|
64
|
+
const out = [];
|
|
65
|
+
let entries = [];
|
|
66
|
+
try {
|
|
67
|
+
entries = fs.readdirSync(procRoot);
|
|
68
|
+
} catch (_) {
|
|
69
|
+
return out;
|
|
70
|
+
}
|
|
71
|
+
for (const pid of entries) {
|
|
72
|
+
if (!/^[0-9]+$/.test(pid)) continue;
|
|
73
|
+
let exe;
|
|
74
|
+
let cmdline;
|
|
75
|
+
try {
|
|
76
|
+
exe = fs.readlinkSync(path.join(procRoot, pid, 'exe'));
|
|
77
|
+
cmdline = fs.readFileSync(path.join(procRoot, pid, 'cmdline'), 'latin1').split('\0');
|
|
78
|
+
} catch (_) {
|
|
79
|
+
continue;
|
|
80
|
+
}
|
|
81
|
+
const deleted = exe.endsWith(DELETED);
|
|
82
|
+
const bin = deleted ? exe.slice(0, -DELETED.length) : exe;
|
|
83
|
+
if (!bin.includes('/@superbased/') || !path.basename(bin).startsWith('observer')) continue;
|
|
84
|
+
if (!cmdline.slice(1).includes('start')) continue;
|
|
85
|
+
if (!deleted && !retiredDir(bin) && !(installed && bin !== installed)) continue;
|
|
86
|
+
out.push(pid);
|
|
87
|
+
}
|
|
88
|
+
return out.sort((a, b) => Number(a) - Number(b));
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// underServiceUnit reports whether pid runs inside the observer systemd unit
|
|
92
|
+
// (its cgroup path names observer.service). U7: the hint names only the
|
|
93
|
+
// restart path that applies to the daemon(s) found.
|
|
94
|
+
function underServiceUnit(procRoot, pid) {
|
|
95
|
+
try {
|
|
96
|
+
const cg = fs.readFileSync(path.join(procRoot, pid, 'cgroup'), 'latin1');
|
|
97
|
+
return /\/observer\.service(\/|$|\n)/m.test(cg);
|
|
98
|
+
} catch (_) {
|
|
99
|
+
return false;
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
function note(pids, procRoot) {
|
|
104
|
+
const which = pids.length === 1 ? 'pid ' + pids[0] : 'pids ' + pids.join(', ');
|
|
105
|
+
const root = procRoot || '/proc';
|
|
106
|
+
const unit = pids.some((p) => underServiceUnit(root, p));
|
|
107
|
+
const plain = pids.some((p) => !underServiceUnit(root, p));
|
|
108
|
+
const lines = ['', '@superbased/observer: updated, but the running Observer daemon (' + which + ') still runs the previous binary.'];
|
|
109
|
+
if (unit) {
|
|
110
|
+
lines.push(
|
|
111
|
+
' It runs as the systemd service: run (as yourself, not with sudo) observer service upgrade',
|
|
112
|
+
' It restarts the daemon only when no proxy route or proxied session is live, and otherwise prints the safe order.'
|
|
113
|
+
);
|
|
114
|
+
}
|
|
115
|
+
if (plain) {
|
|
116
|
+
lines.push(
|
|
117
|
+
' It was started with `observer start`: when no AI session uses the proxy, turn the proxy route off,',
|
|
118
|
+
' stop that process (Ctrl-C in its terminal, or kill ' + which.replace(/^pids? /, '') + '), then run `observer start` again (docs/daemon-restart-runbook.md).'
|
|
119
|
+
);
|
|
120
|
+
}
|
|
121
|
+
lines.push(' npm restarts nothing.', '');
|
|
122
|
+
return lines.join('\n');
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
function emit(text) {
|
|
126
|
+
try {
|
|
127
|
+
const fd = fs.openSync('/dev/tty', 'w');
|
|
128
|
+
try {
|
|
129
|
+
fs.writeSync(fd, text);
|
|
130
|
+
} finally {
|
|
131
|
+
fs.closeSync(fd);
|
|
132
|
+
}
|
|
133
|
+
return;
|
|
134
|
+
} catch (_) {
|
|
135
|
+
// no controlling terminal
|
|
136
|
+
}
|
|
137
|
+
process.stderr.write(text);
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
function main() {
|
|
141
|
+
if (process.platform !== 'linux') return;
|
|
142
|
+
const root = process.env.OBSERVER_POSTINSTALL_PROC_ROOT || '/proc';
|
|
143
|
+
const pids = staleDaemons(root, installedBinary());
|
|
144
|
+
if (pids.length > 0) emit(note(pids, root));
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
if (require.main === module) {
|
|
148
|
+
try {
|
|
149
|
+
main();
|
|
150
|
+
} catch (_) {
|
|
151
|
+
// print-only: never fail an install
|
|
152
|
+
}
|
|
153
|
+
process.exit(0);
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
module.exports = { staleDaemons, note, retiredDir, installedBinary, underServiceUnit };
|
package/package.json
CHANGED
|
@@ -1,23 +1,28 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@superbased/observer",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.37.0",
|
|
4
|
+
"description": "Local-first AI coding agent observability: Claude Code token usage, Codex cost and Cursor spend across 50 adapters, provider-exact via a local proxy. No account needed.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ai",
|
|
7
7
|
"observability",
|
|
8
|
-
"
|
|
9
|
-
"
|
|
8
|
+
"ai-coding-agent",
|
|
9
|
+
"llm-observability",
|
|
10
10
|
"claude-code",
|
|
11
|
+
"claude-code-usage",
|
|
11
12
|
"codex",
|
|
12
13
|
"cursor",
|
|
14
|
+
"copilot",
|
|
15
|
+
"gemini-cli",
|
|
16
|
+
"anthropic",
|
|
17
|
+
"openai",
|
|
13
18
|
"mcp",
|
|
14
19
|
"tokens",
|
|
20
|
+
"token-usage",
|
|
15
21
|
"cost",
|
|
16
22
|
"cost-tracking",
|
|
17
|
-
"
|
|
18
|
-
"
|
|
19
|
-
"
|
|
20
|
-
"spend"
|
|
23
|
+
"prompt-caching",
|
|
24
|
+
"spend",
|
|
25
|
+
"local-first"
|
|
21
26
|
],
|
|
22
27
|
"homepage": "https://superbased.app/",
|
|
23
28
|
"repository": {
|
|
@@ -42,23 +47,24 @@
|
|
|
42
47
|
"LICENSE"
|
|
43
48
|
],
|
|
44
49
|
"optionalDependencies": {
|
|
45
|
-
"@superbased/observer-linux-x64": "1.
|
|
46
|
-
"@superbased/observer-linux-arm64": "1.
|
|
47
|
-
"@superbased/observer-darwin-x64": "1.
|
|
48
|
-
"@superbased/observer-darwin-arm64": "1.
|
|
49
|
-
"@superbased/observer-win32-x64": "1.
|
|
50
|
+
"@superbased/observer-linux-x64": "1.37.0",
|
|
51
|
+
"@superbased/observer-linux-arm64": "1.37.0",
|
|
52
|
+
"@superbased/observer-darwin-x64": "1.37.0",
|
|
53
|
+
"@superbased/observer-darwin-arm64": "1.37.0",
|
|
54
|
+
"@superbased/observer-win32-x64": "1.37.0"
|
|
50
55
|
},
|
|
51
56
|
"scripts": {
|
|
52
|
-
"test": "node bin/observer.js --version"
|
|
57
|
+
"test": "node bin/observer.js --version",
|
|
58
|
+
"postinstall": "node bin/postinstall.js"
|
|
53
59
|
},
|
|
54
60
|
"superbased": {
|
|
55
61
|
"announcement": {
|
|
56
|
-
"id": "
|
|
62
|
+
"id": "v1.37.0-macos13-codesec",
|
|
57
63
|
"severity": "notice",
|
|
58
|
-
"title": "v1.
|
|
59
|
-
"body": "
|
|
60
|
-
"url": "https://github.com/superbasedapp/observer/releases",
|
|
61
|
-
"expires_at": "2026-
|
|
64
|
+
"title": "v1.37.0 needs macOS 13 or later, and code security is now on",
|
|
65
|
+
"body": "This release needs macOS 13 Ventura or later. On macOS 12, stay on v1.36.0. Code security is now on by default in the developer and full editions, so an agent commit or push can ask you first. Run observer guard status to see it.",
|
|
66
|
+
"url": "https://github.com/superbasedapp/observer/releases/tag/v1.37.0",
|
|
67
|
+
"expires_at": "2026-12-30T00:00:00Z",
|
|
62
68
|
"source": "release"
|
|
63
69
|
}
|
|
64
70
|
}
|
package/README.template.md
DELETED
|
@@ -1,335 +0,0 @@
|
|
|
1
|
-
# @superbased/observer
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/@superbased/observer)
|
|
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/)
|
|
9
|
-
|
|
10
|
-
**Claude Code cost tracking. Cursor token usage. Codex spend.
|
|
11
|
-
AI coding agent observability — one local tool, proxy-accurate.**
|
|
12
|
-
SuperBased captures, normalizes, and analyzes every AI
|
|
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.
|
|
23
|
-
|
|
24
|
-
**One local binary.** SuperBased captures, normalizes, and analyzes
|
|
25
|
-
every AI coding tool call on your machine: proxy-accurate cost,
|
|
26
|
-
compression, cache tracking, and session handoff.
|
|
27
|
-
|
|
28
|
-
<p align="center">
|
|
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>
|
|
31
|
-
|
|
32
|
-
# Table of contents
|
|
33
|
-
|
|
34
|
-
- [Install](#install)
|
|
35
|
-
- [Five-minute quickstart](#five-minute-quickstart)
|
|
36
|
-
- [Zero-setup cost report: `observer usage`](#zero-setup-cost-report-observer-usage)
|
|
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)
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
## Install
|
|
54
|
-
|
|
55
|
-
**Use a global install** (`-g`) so the `observer` command is available
|
|
56
|
-
on your `$PATH` from any directory:
|
|
57
|
-
|
|
58
|
-
```bash
|
|
59
|
-
npm install -g @superbased/observer
|
|
60
|
-
observer --version
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
If you install locally (without `-g`) the binary lives at
|
|
64
|
-
`./node_modules/.bin/observer` and isn't on your `$PATH`. Run it
|
|
65
|
-
with `npx`:
|
|
66
|
-
|
|
67
|
-
```bash
|
|
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.
|
|
75
|
-
|
|
76
|
-
> **Python users:** `pip install superbased-observer` ships the
|
|
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.
|
|
81
|
-
|
|
82
|
-
Pre-built binaries ship for:
|
|
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
|
-
```
|
|
108
|
-
|
|
109
|
-
On a fresh machine with no SuperBased state yet, bare `npx
|
|
110
|
-
@superbased/observer` scans each detected AI tool's own local session
|
|
111
|
-
files into a throwaway temp database, prints one tool × model cost
|
|
112
|
-
table, and deletes the database again — no daemon, no config written,
|
|
113
|
-
no network call. See [Zero-setup cost report](#zero-setup-cost-report-observer-usage)
|
|
114
|
-
below for what it does and doesn't do.
|
|
115
|
-
|
|
116
|
-
**For the full local tool** — proxy-accurate tokens, live dashboard,
|
|
117
|
-
conversation compression, cache tracking:
|
|
118
|
-
|
|
119
|
-
```bash
|
|
120
|
-
# 1) Install.
|
|
121
|
-
npm install -g @superbased/observer
|
|
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
|
-
<!-- @@INCLUDE:docs/distribution/README-body.md@@ -->
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
## Troubleshooting
|
|
163
|
-
|
|
164
|
-
### `npm install -g` fails with `EACCES: permission denied`
|
|
165
|
-
|
|
166
|
-
Default npm puts globals under `/usr/local/lib/node_modules` which
|
|
167
|
-
Homebrew-managed Node owns as root on macOS. Three fixes; pick one:
|
|
168
|
-
|
|
169
|
-
```bash
|
|
170
|
-
# 1) RECOMMENDED — point npm at a user-writable prefix.
|
|
171
|
-
mkdir -p ~/.npm-global
|
|
172
|
-
npm config set prefix '~/.npm-global'
|
|
173
|
-
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
|
|
174
|
-
source ~/.zshrc
|
|
175
|
-
npm install -g @superbased/observer
|
|
176
|
-
|
|
177
|
-
# 2) Use a Node version manager — fnm / nvm install Node into your
|
|
178
|
-
# home directory and dodge the permission issue entirely.
|
|
179
|
-
brew install fnm
|
|
180
|
-
fnm install --lts
|
|
181
|
-
npm install -g @superbased/observer
|
|
182
|
-
|
|
183
|
-
# 3) sudo (works but you'll fight permissions on every update).
|
|
184
|
-
sudo npm install -g @superbased/observer
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
### `observer: command not found` after install
|
|
188
|
-
|
|
189
|
-
The shim binary is at `~/.npm-global/bin/observer` (or wherever your
|
|
190
|
-
npm prefix points). Make sure that directory is on `$PATH`:
|
|
191
|
-
|
|
192
|
-
```bash
|
|
193
|
-
echo $PATH | tr ':' '\n' | grep -E 'npm|node'
|
|
194
|
-
# add the prefix's bin/ to PATH if missing — see fix above
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
If you installed only a platform package (e.g. `@superbased/observer-darwin-x64`)
|
|
198
|
-
without the main `@superbased/observer`, the shim doesn't get created
|
|
199
|
-
— there's no `bin` field. Install the main package; npm picks up the
|
|
200
|
-
right platform binary automatically via `optionalDependencies`.
|
|
201
|
-
|
|
202
|
-
### `observer init` says "no tools selected and none auto-detected"
|
|
203
|
-
|
|
204
|
-
Auto-detection looks for the AI clients' default session-log dirs
|
|
205
|
-
(`~/.claude/projects/`, `~/.codex/sessions/`, `~/.cursor/`, etc.).
|
|
206
|
-
On a fresh machine where no client has run yet, those dirs don't
|
|
207
|
-
exist. Pass the flag explicitly:
|
|
208
|
-
|
|
209
|
-
```bash
|
|
210
|
-
observer init --claude-code # or --codex / --cursor / --cline / --all
|
|
211
|
-
```
|
|
212
|
-
|
|
213
|
-
This registers hooks regardless — the next time the client runs,
|
|
214
|
-
its dirs get created and the watcher picks them up.
|
|
215
|
-
|
|
216
|
-
### Empty dashboard / "No proxy traffic"
|
|
217
|
-
|
|
218
|
-
Session/action data populates passively whenever `observer start` is
|
|
219
|
-
running, but ground-truth cost / compression numbers require the
|
|
220
|
-
proxy. Route your tool through it — the quickest way is the
|
|
221
|
-
dashboard's Compression tab → **Proxy** banner → **Route through the
|
|
222
|
-
observer proxy…** button; every other mechanism (wrappers, env vars,
|
|
223
|
-
`observer init`) is listed under
|
|
224
|
-
[Per-AI-client setup](#per-ai-client-setup).
|
|
225
|
-
|
|
226
|
-
Verify with `observer status | grep api_turns` — count should
|
|
227
|
-
climb during AI-client activity.
|
|
228
|
-
|
|
229
|
-
### `observer --version` says `dev`
|
|
230
|
-
|
|
231
|
-
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.
|
|
232
|
-
|
|
233
|
-
### `tool_result block must have a corresponding tool_use block`
|
|
234
|
-
|
|
235
|
-
Anthropic 400. Means the conversation-compression pipeline dropped
|
|
236
|
-
a `tool_use` while keeping its matching `tool_result`. Versions
|
|
237
|
-
prior to 1.3.2 had this bug; upgrade. If you're on 1.3.2+ and still
|
|
238
|
-
see it, file an issue with the conversation prefix.
|
|
239
|
-
|
|
240
|
-
### `tool use concurrency issues`
|
|
241
|
-
|
|
242
|
-
Anthropic 400 surfaced in Claude Code as this message. Means the
|
|
243
|
-
parallel-tool-use case (multiple `tool_use` blocks in one assistant
|
|
244
|
-
message) isn't paired correctly with the multi-block tool_result
|
|
245
|
-
that follows. Versions prior to 1.3.2 had this bug; upgrade.
|
|
246
|
-
|
|
247
|
-
### Cross-thread numbers are 0
|
|
248
|
-
|
|
249
|
-
Pre-migration data was ingested without the `is_sidechain` flag.
|
|
250
|
-
Run `observer backfill --is-sidechain` once to re-walk JSONL and
|
|
251
|
-
populate the flag on existing rows.
|
|
252
|
-
|
|
253
|
-
### Migration error: `duplicate column name`
|
|
254
|
-
|
|
255
|
-
Race condition between concurrent daemon startups, fixed in 1.4.1.
|
|
256
|
-
Upgrade. If you still see it, run daemons serially: `observer
|
|
257
|
-
watch`, wait, then `observer dashboard`, then `observer proxy
|
|
258
|
-
start` (or just use `observer start` which runs all three in one
|
|
259
|
-
process — proxy + watcher + dashboard).
|
|
260
|
-
|
|
261
|
-
### `observer start` log says only `proxy + observer` — no `:8081`
|
|
262
|
-
|
|
263
|
-
You're on a pre-1.4.7 build. Earlier versions ran only proxy +
|
|
264
|
-
watcher under `observer start`; the dashboard had to be started
|
|
265
|
-
separately via `observer dashboard --addr 127.0.0.1:8081`. Upgrade
|
|
266
|
-
to 1.4.7+ — the dashboard goroutine is now part of `observer start`
|
|
267
|
-
and the log line confirms all three: `proxy <addr> + watcher +
|
|
268
|
-
dashboard http://127.0.0.1:8081`. Pass `--no-dashboard` to opt out.
|
|
269
|
-
|
|
270
|
-
### "address already in use" on port 8820
|
|
271
|
-
|
|
272
|
-
Another `observer proxy start` or `observer start` is still running.
|
|
273
|
-
Find it with `pgrep -af 'observer (proxy|start)'` and `kill <pid>`.
|
|
274
|
-
On macOS:
|
|
275
|
-
|
|
276
|
-
```bash
|
|
277
|
-
lsof -nP -iTCP:8820 -sTCP:LISTEN
|
|
278
|
-
kill <pid>
|
|
279
|
-
```
|
|
280
|
-
|
|
281
|
-
### Dashboard port already in use
|
|
282
|
-
|
|
283
|
-
```bash
|
|
284
|
-
observer dashboard --addr 127.0.0.1:8082 # pick a different port
|
|
285
|
-
# or
|
|
286
|
-
[dashboard]
|
|
287
|
-
port = 8082 # in config.toml
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
## Security and privacy
|
|
292
|
-
|
|
293
|
-
**Local-only. No telemetry. No remote anything.** The watcher, hook
|
|
294
|
-
handler, dashboard, MCP server, and CLI never make an outbound network
|
|
295
|
-
call on observer's behalf. The only code paths that touch the network
|
|
296
|
-
are the optional API proxy (which forwards **your** requests unchanged
|
|
297
|
-
to the AI provider you already use) and a handful of explicit opt-in
|
|
298
|
-
features (message-summary LLM, codeintel MCP).
|
|
299
|
-
|
|
300
|
-
The full privacy statement — what observer stores, what it reads,
|
|
301
|
-
what it never stores, the explicit list of outbound-network call sites
|
|
302
|
-
gated behind config, and how to verify "no telemetry" yourself with
|
|
303
|
-
`grep`, `strings`, and a network-namespaced shell — lives in
|
|
304
|
-
[`PRIVACY.md`](https://github.com/superbasedapp/observer/blob/main/PRIVACY.md).
|
|
305
|
-
|
|
306
|
-
Operational shorthand:
|
|
307
|
-
|
|
308
|
-
- **Local-only HTTP.** The proxy and dashboard bind to `127.0.0.1`
|
|
309
|
-
by default. Don't bind to `0.0.0.0` unless you've thought about
|
|
310
|
-
it — there's no auth.
|
|
311
|
-
- **Secrets scrubbing.** Tool inputs and outputs pass through
|
|
312
|
-
`internal/scrub/` before persistence; review the regex set if your
|
|
313
|
-
secrets follow non-default formats.
|
|
314
|
-
- **Database.** `~/.observer/observer.db` is a SQLite file with the
|
|
315
|
-
same security posture as your `~/.claude/` and `~/.codex/` session
|
|
316
|
-
logs (which already hold the same content). Encrypt the disk if
|
|
317
|
-
your threat model needs that.
|
|
318
|
-
- **Full delete.** `rm -rf ~/.observer/` removes everything observer
|
|
319
|
-
ever stored — no traces elsewhere on your system.
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
## Source, contributing, license
|
|
323
|
-
|
|
324
|
-
- **Source**: https://github.com/superbasedapp/observer
|
|
325
|
-
- **Specification**: `superbased-final-spec-v2.md` in the repo
|
|
326
|
-
- **Issues**: https://github.com/superbasedapp/observer/issues
|
|
327
|
-
- **License**: [Apache 2.0](https://github.com/superbasedapp/observer/blob/main/LICENSE)
|
|
328
|
-
- **Author**: Santosh Kathira <contact@superbased.app>
|
|
329
|
-
|
|
330
|
-
This npm package is a thin Node.js shim that resolves the right
|
|
331
|
-
pre-built binary at runtime and spawns it. Same shape as `esbuild` /
|
|
332
|
-
`swc` / `@biomejs/biome`. The Go source lives in the main repo;
|
|
333
|
-
binaries are cross-compiled per release tag via GitHub Actions and
|
|
334
|
-
published as `@superbased/observer-<platform>-<arch>` per-platform
|
|
335
|
-
packages.
|