@superbased/observer 1.36.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 +59 -12
- package/bin/observer.js +6 -2
- package/package.json +13 -14
- package/README.template.md +0 -51
package/README.md
CHANGED
|
@@ -1,16 +1,18 @@
|
|
|
1
1
|
# @superbased/observer
|
|
2
2
|
|
|
3
|
-
<img src="https://raw.githubusercontent.com/superbasedapp/observer/main/
|
|
3
|
+
<img src="https://raw.githubusercontent.com/superbasedapp/observer/main/docs/assets/mascot/obs-idle-light-512.png" alt="Obs, the SuperBased mascot: a small robot with a terminal prompt for a face and a cape" width="112" align="right">
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
<img src="https://raw.githubusercontent.com/superbasedapp/observer/main/docs/assets/brand/superbased-lockup-light.png" alt="SuperBased" height="32">
|
|
6
|
+
|
|
7
|
+
**Track what every AI coding agent costs. See the limit coming.** See what Claude Code, Codex,
|
|
8
|
+
Cursor and 37 more AI coding tools cost, per session and per model, from the tokens your provider
|
|
9
|
+
actually billed. Free, Apache-2.0, and it runs on your machine.
|
|
8
10
|
|
|
9
11
|
[](https://www.npmjs.com/package/@superbased/observer)
|
|
10
12
|
[](https://github.com/superbasedapp/observer/blob/main/LICENSE)
|
|
11
13
|
[](https://superbased.app/)
|
|
12
14
|
|
|
13
|
-

|
|
14
16
|
|
|
15
17
|
## Try it without installing
|
|
16
18
|
|
|
@@ -21,6 +23,8 @@ npx @superbased/observer
|
|
|
21
23
|
Reads the session logs your coding agents already keep on disk, prints a 30-day cost table by tool
|
|
22
24
|
and model, and deletes its temporary database on exit. No config, no network.
|
|
23
25
|
|
|
26
|
+
On Windows PowerShell, type `npx.cmd` and `npm.cmd` instead of `npx` and `npm` (or use Command Prompt): PowerShell's default execution policy blocks the `npx.ps1` and `npm.ps1` scripts.
|
|
27
|
+
|
|
24
28
|
## Install
|
|
25
29
|
|
|
26
30
|
```bash
|
|
@@ -28,7 +32,7 @@ npm install -g @superbased/observer
|
|
|
28
32
|
observer --version
|
|
29
33
|
```
|
|
30
34
|
|
|
31
|
-
Prebuilt binaries for Linux (x64, arm64), macOS (Intel, Apple Silicon) and Windows x64. npm fetches
|
|
35
|
+
Prebuilt binaries for Linux (x64, arm64), macOS 13 or later (Intel, Apple Silicon) and Windows x64. npm fetches
|
|
32
36
|
only the one for your machine; there is no compile step and no postinstall download. Also on
|
|
33
37
|
[PyPI](https://pypi.org/project/superbased-observer/) and the
|
|
34
38
|
[VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=superbased.superbased-observer)
|
|
@@ -41,10 +45,10 @@ and helps you control them.**
|
|
|
41
45
|
|
|
42
46
|
- **Provider-exact cost, not estimates.** An optional local proxy records the tokens your provider
|
|
43
47
|
returned: net input, 5-minute vs 1-hour cache writes, reasoning tokens and long-context repricing.
|
|
44
|
-
- **Every coding agent in one place.**
|
|
48
|
+
- **Every coding agent in one place.** 50 adapters normalize Claude Code, Codex, Cursor, GitHub
|
|
45
49
|
Copilot, Gemini CLI, Cline, Aider, Kiro, Devin, OpenCode, Junie and more into one local database.
|
|
46
|
-
- **Local-first, no account.** No
|
|
47
|
-
|
|
50
|
+
- **Local-first, no account.** No sign-in. Everything lives in one SQLite file under
|
|
51
|
+
`~/.observer/`, and your session content is never uploaded without your explicit consent.
|
|
48
52
|
- **Know the next bill before it lands.** Prompt-cache tracking with expiry warnings, a cost band
|
|
49
53
|
for your next message, and a 5-hour and weekly limit gauge for proxied sessions.
|
|
50
54
|
- **Guardrails on your own agents.** Built-in and custom rules for destructive commands, secrets
|
|
@@ -52,8 +56,12 @@ and helps you control them.**
|
|
|
52
56
|
- **Your agents as terminals.** Launch agent CLIs from the dashboard, join a running session from a
|
|
53
57
|
paired device over your Tailscale tailnet, and hand a session from one tool to another.
|
|
54
58
|
|
|
59
|
+

|
|
60
|
+
|
|
55
61
|
## Get started
|
|
56
62
|
|
|
63
|
+
<img src="https://raw.githubusercontent.com/superbasedapp/observer/main/docs/assets/mascot/obs-celebrate-light-small.png" alt="" width="54" align="right">
|
|
64
|
+
|
|
57
65
|
```bash
|
|
58
66
|
observer start # proxy + watcher + dashboard; opens http://localhost:8081
|
|
59
67
|
observer scan # backfill history from the session logs already on disk
|
|
@@ -65,6 +73,13 @@ click your tool's status pill and choose **Route through the observer proxy** (i
|
|
|
65
73
|
config change and writes only when you confirm), or run `observer claude` / `observer codex` for a
|
|
66
74
|
one-off proxied session. `observer init` additionally registers the opt-in MCP server.
|
|
67
75
|
|
|
76
|
+
Prefer a plain download? [superbased.app/download](https://superbased.app/download) has the
|
|
77
|
+
Windows setup program, macOS and Linux downloads and every version, with SHA-256 checksums.
|
|
78
|
+
|
|
79
|
+
**macOS needs version 13 Ventura or later.** Observer is built with Go 1.27, which no longer runs
|
|
80
|
+
on macOS 12 Monterey. On macOS 12, stay on v1.36.0 or upgrade macOS first. v1.36.0 was meant to
|
|
81
|
+
carry an advance notice of this and did not. Linux and Windows are not affected.
|
|
82
|
+
|
|
68
83
|
## What you get
|
|
69
84
|
|
|
70
85
|
- A local dashboard for sessions, cost, cache, security and live activity, filterable by tool and
|
|
@@ -75,11 +90,39 @@ one-off proxied session. `observer init` additionally registers the opt-in MCP s
|
|
|
75
90
|
- Dashboard terminals with multi-seat join and native resume.
|
|
76
91
|
- A CLI for everything: `observer usage`, `cost`, `predict`, `tail`, `statusline`.
|
|
77
92
|
|
|
93
|
+
<table>
|
|
94
|
+
<tr>
|
|
95
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/superbasedapp/observer/main/docs/assets/screenshots/sessions.png" alt="Sessions page: one row per coding-agent session with tool, model, start time, elapsed time, actions and cost, plus tag totals" width="430"><br><sub><b>Sessions:</b> every session from every agent, with cost and tags.</sub></td>
|
|
96
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/superbasedapp/observer/main/docs/assets/screenshots/cache.png" alt="Cache page: live prompt caches with time left before they expire, cache ratio, reads and writes, and provider coverage" width="430"><br><sub><b>Cache:</b> which prompt caches are warm and when they go cold.</sub></td>
|
|
97
|
+
</tr>
|
|
98
|
+
</table>
|
|
99
|
+
|
|
100
|
+

|
|
101
|
+
|
|
102
|
+
## Inside a session
|
|
103
|
+
|
|
104
|
+
Click any session to open its detail view. Four of its tabs:
|
|
105
|
+
|
|
106
|
+
<table>
|
|
107
|
+
<tr>
|
|
108
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/superbasedapp/observer/main/docs/assets/screenshots/session-detail.png" alt="Session detail, Overview tab: total cost, actions, elapsed time and tokens, the action breakdown, token buckets by billing tier and the cost per model" width="430"><br><sub><b>Overview:</b> cost, tokens by billing tier and the models used.</sub></td>
|
|
109
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/superbasedapp/observer/main/docs/assets/screenshots/session-messages.png" alt="Session detail, Messages tab: every message in the session with time, role, model, tool calls and cost" width="430"><br><sub><b>Messages:</b> each message with its model, tool calls and cost.</sub></td>
|
|
110
|
+
</tr>
|
|
111
|
+
<tr>
|
|
112
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/superbasedapp/observer/main/docs/assets/screenshots/session-cost-and-limits-tab.png" alt="Session detail, Cost and limits tab: low, typical and high cost for the next message and the 5-hour and weekly limit" width="430"><br><sub><b>Cost & limits:</b> what the next message will cost and how much of your limit is left.</sub></td>
|
|
113
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/superbasedapp/observer/main/docs/assets/screenshots/session-cache-tab.png" alt="Session detail, Cache tab: the session's live cache and when it expires, cache hits, writes, rewrites and the read to write ratio" width="430"><br><sub><b>Cache:</b> the session's live cache, hits, writes and rewrites.</sub></td>
|
|
114
|
+
</tr>
|
|
115
|
+
</table>
|
|
116
|
+
|
|
78
117
|
## Privacy
|
|
79
118
|
|
|
80
|
-
No
|
|
81
|
-
|
|
82
|
-
|
|
119
|
+
No account needed. Today the default install sends us no usage statistics, analytics or crash
|
|
120
|
+
reports, and your session content is never uploaded without your explicit consent. SuperBased stores
|
|
121
|
+
paths, commands and short excerpts, scrubs secrets before writing, and binds the proxy and dashboard
|
|
122
|
+
to `127.0.0.1` by default. The proxy forwards your own requests, unchanged, to the provider you
|
|
123
|
+
already use. By default SuperBased also makes a few small requests of its own that carry none of
|
|
124
|
+
your data, such as a daily download of the public model price table from superbased.app (turn it
|
|
125
|
+
off with `[pricing.feed] enabled = false`). See
|
|
83
126
|
[PRIVACY.md](https://github.com/superbasedapp/observer/blob/main/PRIVACY.md).
|
|
84
127
|
|
|
85
128
|
## Learn more
|
|
@@ -94,6 +137,10 @@ own requests, unchanged, to the provider you already use. See
|
|
|
94
137
|
- **`EACCES` on `npm install -g`:** point npm at a user prefix
|
|
95
138
|
(`npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to `PATH`) or use a Node version
|
|
96
139
|
manager such as fnm or nvm.
|
|
140
|
+
- **`running scripts is disabled on this system` in PowerShell:** On Windows PowerShell, type
|
|
141
|
+
`npx.cmd` and `npm.cmd` instead of `npx` and `npm` (or use Command Prompt): PowerShell's default
|
|
142
|
+
execution policy blocks the `npx.ps1` and `npm.ps1` scripts. Changing the policy with
|
|
143
|
+
`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` also works, but is not required.
|
|
97
144
|
- **`observer: command not found`:** make sure your npm global `bin` directory is on `PATH`, and that
|
|
98
145
|
you installed `@superbased/observer` itself, not only a platform package.
|
|
99
146
|
- **Port 8820 or 8081 already in use:** another `observer start` is running; stop it first.
|
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
|
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@superbased/observer",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "Local-first AI coding agent observability: Claude Code token usage, Codex cost and Cursor spend across
|
|
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",
|
|
@@ -22,8 +22,7 @@
|
|
|
22
22
|
"cost-tracking",
|
|
23
23
|
"prompt-caching",
|
|
24
24
|
"spend",
|
|
25
|
-
"local-first"
|
|
26
|
-
"no-telemetry"
|
|
25
|
+
"local-first"
|
|
27
26
|
],
|
|
28
27
|
"homepage": "https://superbased.app/",
|
|
29
28
|
"repository": {
|
|
@@ -48,11 +47,11 @@
|
|
|
48
47
|
"LICENSE"
|
|
49
48
|
],
|
|
50
49
|
"optionalDependencies": {
|
|
51
|
-
"@superbased/observer-linux-x64": "1.
|
|
52
|
-
"@superbased/observer-linux-arm64": "1.
|
|
53
|
-
"@superbased/observer-darwin-x64": "1.
|
|
54
|
-
"@superbased/observer-darwin-arm64": "1.
|
|
55
|
-
"@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"
|
|
56
55
|
},
|
|
57
56
|
"scripts": {
|
|
58
57
|
"test": "node bin/observer.js --version",
|
|
@@ -60,12 +59,12 @@
|
|
|
60
59
|
},
|
|
61
60
|
"superbased": {
|
|
62
61
|
"announcement": {
|
|
63
|
-
"id": "
|
|
62
|
+
"id": "v1.37.0-macos13-codesec",
|
|
64
63
|
"severity": "notice",
|
|
65
|
-
"title": "v1.
|
|
66
|
-
"body": "
|
|
67
|
-
"url": "https://github.com/superbasedapp/observer/releases",
|
|
68
|
-
"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",
|
|
69
68
|
"source": "release"
|
|
70
69
|
}
|
|
71
70
|
}
|
package/README.template.md
DELETED
|
@@ -1,51 +0,0 @@
|
|
|
1
|
-
# @superbased/observer
|
|
2
|
-
|
|
3
|
-
<img src="https://raw.githubusercontent.com/superbasedapp/observer/main/vscode/media/logo-dark.png" alt="SuperBased logo" height="56">
|
|
4
|
-
|
|
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.
|
|
8
|
-
|
|
9
|
-
[](https://www.npmjs.com/package/@superbased/observer)
|
|
10
|
-
[](https://github.com/superbasedapp/observer/blob/main/LICENSE)
|
|
11
|
-
[](https://superbased.app/)
|
|
12
|
-
|
|
13
|
-

|
|
14
|
-
|
|
15
|
-
## Try it without installing
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
npx @superbased/observer
|
|
19
|
-
```
|
|
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.
|
|
23
|
-
|
|
24
|
-
## Install
|
|
25
|
-
|
|
26
|
-
```bash
|
|
27
|
-
npm install -g @superbased/observer
|
|
28
|
-
observer --version
|
|
29
|
-
```
|
|
30
|
-
|
|
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.
|
|
36
|
-
|
|
37
|
-
<!-- @@INCLUDE:docs/distribution/README-body.md@@ -->
|
|
38
|
-
|
|
39
|
-
## Troubleshooting
|
|
40
|
-
|
|
41
|
-
- **`EACCES` on `npm install -g`:** point npm at a user prefix
|
|
42
|
-
(`npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to `PATH`) or use a Node version
|
|
43
|
-
manager such as fnm or nvm.
|
|
44
|
-
- **`observer: command not found`:** make sure your npm global `bin` directory is on `PATH`, and that
|
|
45
|
-
you installed `@superbased/observer` itself, not only a platform package.
|
|
46
|
-
- **Port 8820 or 8081 already in use:** another `observer start` is running; stop it first.
|
|
47
|
-
|
|
48
|
-
## License
|
|
49
|
-
|
|
50
|
-
Apache 2.0. This package is a small Node.js shim that runs the prebuilt binary from the matching
|
|
51
|
-
`@superbased/observer-<platform>-<arch>` package.
|