ctxtop 4.0.0 → 4.1.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/.antigravity-plugin/plugin.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHECKSUMS.sha256 +59 -42
- package/README.md +351 -330
- package/bin/ah-statusline.mjs +30 -0
- package/bin/ctxtop.mjs +330 -5
- package/config/default_flightcheck.json +19 -0
- package/config/modelCatalog.json +165 -0
- package/hooks/handlers/compact-lifecycle.mjs +323 -8
- package/hooks/handlers/config-change.mjs +402 -0
- package/hooks/handlers/hookIo.mjs +56 -0
- package/hooks/handlers/post-model-switch.mjs +111 -0
- package/hooks/handlers/post-tool-use.mjs +117 -16
- package/hooks/handlers/pre-model-switch.mjs +823 -24
- package/hooks/handlers/pre-tool-use.mjs +271 -4
- package/hooks/handlers/stop-gate.mjs +297 -11
- package/hooks/handlers/user-prompt-submit.mjs +224 -0
- package/hooks/hooks.json +50 -0
- package/hooks/post_tool_use.mjs +8 -0
- package/hooks/register.js +48 -9
- package/hooks/session_start.mjs +11 -1
- package/hooks/stop.mjs +11 -1
- package/package.json +11 -4
- package/packages/antigravity/package.json +1 -1
- package/packages/claude-code/package.json +1 -1
- package/packages/core/package.json +1 -1
- package/packages/engine-node/package.json +1 -1
- package/packages/mcp/package.json +1 -1
- package/packages/mcp/src/server.mjs +1 -1
- package/packages/pro/package.json +1 -1
- package/plugin.json +1 -1
- package/sidecars/horizon-daemon/server.mjs +38 -2
- package/skills/handoff/SKILL.md +8 -0
- package/src/adapters/antigravity/index.mjs +31 -1
- package/src/adapters/claude-code/index.mjs +40 -1
- package/src/cli/horizon_hud.mjs +254 -52
- package/src/config/modelCatalog.json +84 -0
- package/src/core/bucket_b_runtime.mjs +1200 -0
- package/src/core/constants.mjs +191 -4
- package/src/core/detectors_det01_to_16.mjs +54 -5
- package/src/core/doc_indexer.mjs +338 -0
- package/src/core/layer5_hygiene.mjs +118 -0
- package/src/core/parser.mjs +2 -1
- package/src/core/paths.mjs +3 -2
- package/src/core/rsl_clash_auditor.mjs +423 -0
- package/src/core/rsl_distiller.mjs +372 -0
- package/src/core/rsl_ledger.mjs +969 -0
- package/src/core/rsl_triage.mjs +909 -0
- package/src/core/session_auditor.mjs +658 -0
- package/src/core/shield_manager.mjs +1417 -0
- package/src/core/task_quota_router.mjs +1 -1
- package/src/core-isomorphic/coach/cacheGravityRouter.mjs +874 -47
- package/src/core-isomorphic/coach/resumeToolsetAuditor.mjs +321 -0
- package/src/core-isomorphic/coach/smartCompactAdvisor.mjs +305 -0
- package/src/core-isomorphic/coach/ttlWatchdog.mjs +13 -6
- package/src/core-isomorphic/config/anthropicModelCatalog.json +404 -1
- package/src/core-isomorphic/config/catalogLoader.mjs +546 -46
- package/src/core-isomorphic/config/horizonConfig.mjs +47 -1
- package/src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +266 -0
- package/src/core-isomorphic/economics/cacheGravity.mjs +18 -0
- package/src/core-isomorphic/economics/cliffBreaker.mjs +98 -12
- package/src/core-isomorphic/economics/driftLatency.mjs +114 -0
- package/src/core-isomorphic/guards/bucketBAlphaBeta.mjs +860 -0
- package/src/core-isomorphic/guards/bucketBGamma.mjs +442 -0
- package/src/core-isomorphic/guards/bucketBHeuristics.mjs +37 -0
- package/src/core-isomorphic/guards/circuitBreakers.mjs +191 -191
- package/src/core-isomorphic/guards/det01_03_shell_secret.mjs +154 -5
- package/src/core-isomorphic/guards/det04_12_thrash_rot.mjs +103 -11
- package/src/core-isomorphic/guards/det13_20_mcp_scope.mjs +311 -1
- package/src/core-isomorphic/guards/docIndexCore.mjs +446 -0
- package/src/core-isomorphic/guards/losslessPostSanitizer.mjs +16 -0
- package/src/core-isomorphic/guards/slopsquatGate.mjs +551 -0
- package/src/core-isomorphic/index.js +1 -0
- package/src/core-isomorphic/telemetry/telemetryBridge.mjs +36 -12
- package/src/core-isomorphic/ui/horizonPanelHtml.mjs +293 -237
- package/src/core-isomorphic/ui/modViews.mjs +35 -9
- package/src/diagnostics/claudeHookCapabilities.mjs +396 -0
- package/src/diagnostics/doctorEngine.mjs +95 -3
- package/src/engine-node/db/probe.mjs +234 -2
- package/src/engine-node/index.mjs +3 -0
- package/src/engine-node/sensors/blindspots.mjs +13 -6
- package/src/hooks/antigravity_rsl_hook.mjs +250 -0
- package/src/hooks/claude_rsl_hook.mjs +288 -0
- package/src/hooks/post_invocation.mjs +196 -4
- package/src/hooks/pre_invocation.mjs +732 -22
- package/src/hooks/session_start.mjs +39 -1
- package/src/utils/modelSwitchTelemetry.mjs +308 -0
- package/src/utils/sessionCalibration.mjs +657 -0
- package/src/webview/horizon_panel.html +1325 -317
package/README.md
CHANGED
|
@@ -1,330 +1,351 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
# Highbeam (ctxtop v4.0) — Active Context Surgeon, KV-Cache Shield & Token FinOps for Claude Code & Google Antigravity
|
|
4
|
-
|
|
5
|
-
**Local Context Window Profiler, KV-Cache TTL Monitor & Deterministic PreInvocation / PreToolUse Surgeon (`~0.18ms` Tier-1 In-Process / `~25–90ms` Tier-2 CLI Hook) for Claude Code & Google Antigravity**
|
|
6
|
-
|
|
7
|
-
[](#systems-architecture--zero-trust-security)
|
|
8
|
-
[](#deterministic-preinvocation-router--6-local-sensors)
|
|
9
|
-
[](#quick-start)
|
|
10
|
-
[](LICENSE)
|
|
11
|
-
[](#-installation--quick-start)
|
|
12
|
-
|
|
13
|
-
[**Live Interactive Demo**](https://gizzant.github.io/attention-horizon-antigravity/) • [**Quick Start**](#-installation--quick-start) • [**Cookbook & Recipes**](docs/COOKBOOK.md) • [**Systems Architecture**](#systems-architecture--zero-trust-security)
|
|
14
|
-
|
|
15
|
-
<br/>
|
|
16
|
-
|
|
17
|
-
<img src="assets/hero-demo.svg" alt="Highbeam 40-Cell ANSI HUD & PreInvocation Router" width="100%" />
|
|
18
|
-
|
|
19
|
-
</div>
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## ⚡ Installation & Quick Start
|
|
24
|
-
|
|
25
|
-
| **Google Antigravity** *(1-Line Install)* | **Claude Code** *(1-Line Install)* |
|
|
26
|
-
| :--- | :--- |
|
|
27
|
-
| ```bash
|
|
28
|
-
npx ctxtop init
|
|
29
|
-
``` | ```bash
|
|
30
|
-
npx ctxtop install --claude
|
|
31
|
-
``` |
|
|
32
|
-
| *Workspace-only*: `npx ctxtop init --workspace`<br/>*Health check*: `npx ctxtop doctor` | *StatusLine HUD*: `npx ah-statusline --demo`<br/>*In-chat pane*: `/horizon` · `/cost-radar` · `/handoff` |
|
|
33
|
-
|
|
34
|
-
### Your First 5 Minutes After Installing
|
|
35
|
-
|
|
36
|
-
#### 1. Google Antigravity Workflow
|
|
37
|
-
1. **Install hooks & sidecar**: Run `npx ctxtop init` in your project root (or globally).
|
|
38
|
-
2. **Open the Highbeam Sidepane**: Launch the local telemetry WebView (`npx ctxtop --serve` or via the Antigravity sidepane) to view real-time context health:
|
|
39
|
-
- **Simple View (Default)**: 4 glanceable zones—**Zone A** (Safe Headroom & Warm KV Cache TTL), **Zone B** (`DO / AVOID / HOLD` Model & Effort switch guidance), **Zone C** (Live automated interventions), and **Zone D** (Verified tokens/USD saved + 1-click `/compact`).
|
|
40
|
-
- **Advanced View (1-Click Toggle)**: Expands the **40-Cell Chrono-Positional Recall Grid** (`Primacy 0–30%`, `Mid-Trough 30–70%`, `Recency 70–100%`), top token consumer file table, `Off / Coach / Auto-Pilot` mode switcher, and the full `DET-01..32` guard log.
|
|
41
|
-
3. **Code normally**: Highbeam runs in **`COACH` mode** by default—automatically compressing verbose CLI test dumps via SQLite FTS5 and folding repeat file reads without interrupting your prompts.
|
|
42
|
-
|
|
43
|
-
#### 2. Claude Code Workflow
|
|
44
|
-
1. **Install plugin & hooks**: Run `npx ctxtop install --claude` to wire `.claude-plugin/plugin.json`, `hooks/hooks.json`, and the live terminal `statusLine`.
|
|
45
|
-
2. **Watch the Live Terminal `statusLine`**: At the bottom of your terminal, Highbeam renders an auto-adapting (`80 / 110 / 144` col) telemetry bar:
|
|
46
|
-
```text
|
|
47
|
-
AH [SCCCCCCC................] sonnet-5-5 64k/200k (32%) · Cache 88% (4m12s) · COACH · Saved $1.84
|
|
48
|
-
```
|
|
49
|
-
3. **Open the In-Chat Docked HUD**: Type `/horizon` in chat (or run `npx ah-claude panel` for the standalone HTML workbench) to inspect cache gravity, active guards, and reclaimable tokens.
|
|
50
|
-
|
|
51
|
-
---
|
|
52
|
-
|
|
53
|
-
## 🧭 Built-In Slash Skills & In-Chat Commands (Both Hosts)
|
|
54
|
-
|
|
55
|
-
All 6 slash skills are registered identically in both **Google Antigravity** (`plugin.json`) and **Claude Code** (`.claude-plugin/plugin.json`):
|
|
56
|
-
|
|
57
|
-
| Slash Command / Skill | When to Use It | What It Outputs |
|
|
58
|
-
| :--- | :--- | :--- |
|
|
59
|
-
| **`/horizon`** | Anytime during a coding session | Renders the live 40-cell Context Health HUD, KV-Cache TTL countdown, active `DO / AVOID / HOLD` guidance, and reclaimable clutter breakdown. |
|
|
60
|
-
| **`/precheck`** | Before sending a complex refactor prompt or switching models | Audits prompt specificity (6-dimension rubric), checks
|
|
61
|
-
| **`/handoff`** | Before running `/compact` or `/clear` at `>=75%` context fill | Distills active plan checkboxes, modified files, and unresolved `stderr` into a compressed `<1,000`-token checkpoint (`task.md` / `.handoff.md`). |
|
|
62
|
-
| **`/cost-radar`** | When reviewing session token burn or cache busts | Generates an interactive HTML/SVG timeline of prefix-cache retention, `DET-30` thinking drift loops, and subagent worktree topology. |
|
|
63
|
-
| **`/inspect`** | When diagnosing slow tools or subagent fan-out | Visualizes session trajectory call-tree spans, per-tool latencies, and token attribution as a standalone artifact. |
|
|
64
|
-
| **`/evolve`** | After correcting agent mistakes across a session | Audits `AGENTS.md` / `CLAUDE.md` Turn-0 prefix budget (`<=20k` tok) and synthesizes validated session instincts via 1-click diff approval. |
|
|
65
|
-
|
|
66
|
-
**Quick In-Chat Prompt Prefixes:**
|
|
67
|
-
- `! <prompt>` — Bypass `PreInvocation` checks for a single turn.
|
|
68
|
-
- `!lock <prompt>` — Freeze current reasoning effort tier and prefix state for the remainder of the session.
|
|
69
|
-
- `#check <prompt>` — Force an explicit pre-flight scorecard and concrete prompt rewrite suggestion.
|
|
70
|
-
|
|
71
|
-
---
|
|
72
|
-
|
|
73
|
-
## 🛡️ Verified Token Receipt: `+164.0k` Tokens Saved in One 4-Step Coding Loop
|
|
74
|
-
|
|
75
|
-
Most CLI trackers passively count tokens *after* your quota is already burned. Highbeam intercepts redundant reads, compresses noisy test dumps via local SQLite FTS5, and shields warm KV prefixes **before** they hit your billing meter:
|
|
76
|
-
|
|
77
|
-
<div align="center">
|
|
78
|
-
<img src="assets/zone_c_step3_shield_full.png" alt="Highbeam Zone C Active Protection & Verified Token Receipt (+164.0k tokens saved)" width="460" />
|
|
79
|
-
</div>
|
|
80
|
-
|
|
81
|
-
| Step in Coding Loop | Developer / Agent Action | Highbeam Active Intervention (Zone C) | Verified Savings |
|
|
82
|
-
| :--- | :--- | :--- | :---: |
|
|
83
|
-
| **1. Warm KV Cache + Repeat Read** | Agent re-reads an unmodified 800-line source file on a `100k` warm cache | **GUARD-4** intercepts the duplicate read (`AST signature stub`) and preserves the `95%` warm KV cache discount | **`+95.0k` tok** *(KV cache)*<br/>**`+800` tok** *(deduped read)* |
|
|
84
|
-
| **2. Failing Test Suite Dump** | `npm test` dumps `120+` lines of verbose stdout (`~11.4k` tokens) | **SQLite FTS5 BM25 Compressor** indexes raw stdout locally and injects only the 160-token failing assertion digest | **`+11.2k` tok** |
|
|
85
|
-
| **3. Mid-Session Rule Edit** | Agent updates `AGENTS.md` / `CLAUDE.md` while `60k` prefix is warm (`2m 55s` TTL left) | **PrefixCacheShield** queues the rule delta until TTL expiry or `/compact`, preventing a cold prefix rebuild | **`+57.0k` tok** |
|
|
86
|
-
| **Total Verified Session Receipt** | **4-Step Feature / Bugfix Loop** | **Zero context dilution · 100% critical error retention** | **`+164.0k` tok (`~$0.33`)** |
|
|
87
|
-
|
|
88
|
-
---
|
|
89
|
-
|
|
90
|
-
## 💡 Why Saved Tokens Multiply (`O(N²)` Turn Compounding, Quota Life & Model IQ)
|
|
91
|
-
|
|
92
|
-
In agentic coding, every turn re-sends the entire prior conversation history. A single `15,000`-token raw test dump on Turn 5 is not billed once—it is re-sent on Turns 6 through 25, burning **`300,000` cumulative tokens** (`15,000 × 20`).
|
|
93
|
-
|
|
94
|
-
1. **For Fixed-Subscription Users (`Claude Pro / Max`, `Antigravity OAuth Seats`) — Stop 2:00 PM Quota Lockouts & Context Rot**:
|
|
95
|
-
- Compressing noisy tool outputs and duplicate file reads on early turns prevents `O(N²)` history compounding, **stretching 5-hour sprint quotas by `30%–50%`**.
|
|
96
|
-
- Even more importantly, keeping your session below the **70% Safe Horizon** prevents **Context Rot** (middle-window attention decay where the model starts forgetting `AGENTS.md`/`CLAUDE.md` rules, hallucinating imports, and breaking working code).
|
|
97
|
-
2. **For Metered API & Enterprise Teams — Self-Expensing FinOps ROI**:
|
|
98
|
-
- Preventing just two accidental warm-cache busts per day (switching models mid-TTL or editing rule files on a `100k` warm prefix) plus FTS5 log compression saves **`$3–$12/day` (`$60–$240/month`) per active seat**.
|
|
99
|
-
3. **Daily Cockpit Decisions No Human Can Calculate in Their Head (Zone B)**:
|
|
100
|
-
- *"If I downshift from Opus/Argon to Sonnet/Flash right now, will I save quota or pay a 10x cold-prefill penalty?"* — Highbeam computes the
|
|
101
|
-
|
|
102
|
-
---
|
|
103
|
-
|
|
104
|
-
## ⚙️ What Runs Automatically (Zero-Friction `COACH` Default)
|
|
105
|
-
|
|
106
|
-
Highbeam defaults to **`COACH` mode**—performing lossless token surgery silently in the background while never blocking your chat prompt unless a true 3-strike identical failure loop or destructive git command occurs:
|
|
107
|
-
|
|
108
|
-
| Automated Feature | How It Works Under the Hood | Developer Experience |
|
|
109
|
-
| :--- | :--- | :--- |
|
|
110
|
-
| **1. SQLite FTS5 CLI & Test Output Compression** (`PostToolUse`) | Strips ANSI/progress noise, indexes full stdout in local SQLite FTS5 (`porter unicode61`), and injects only the compact failing assertion digest | **100% automatic** — saves `50%–90%` of test/build log tokens with zero lost stack traces |
|
|
111
|
-
| **2. Post-Edit Delta Diffs & 3rd-Read AST Stubs** (`GUARD-4` in `PreToolUse`) | When the agent re-reads a file after editing 5 lines (or reads the same unclipped file `>=3` times), returns a unified line diff or function-signature AST stub | **100% automatic** — cuts repeat-read token burn by `80%+` without interrupting the agent |
|
|
112
|
-
| **3. `PrefixCacheShield` Warm Rule Deferral** (`DET-09`) | Intercepts mid-session edits to `AGENTS.md` / `CLAUDE.md` while a
|
|
113
|
-
| **4. Live Model & Effort Switch Verdict** (`Zone B`) | Evaluates remaining KV cache TTL (`5m`/`1h`) and
|
|
114
|
-
| **5.
|
|
115
|
-
| **6. Git Hook-Bypass & Destructive Shell Guard** (`DET-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
#
|
|
190
|
-
node src/cli/
|
|
191
|
-
|
|
192
|
-
#
|
|
193
|
-
node src/cli/
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
```json
|
|
258
|
-
{
|
|
259
|
-
"
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# Highbeam (ctxtop v4.0) — Active Context Surgeon, KV-Cache Shield & Token FinOps for Claude Code & Google Antigravity
|
|
4
|
+
|
|
5
|
+
**Local Context Window Profiler, KV-Cache TTL Monitor & Deterministic PreInvocation / PreToolUse Surgeon (`~0.18ms` Tier-1 In-Process / `~25–90ms` Tier-2 CLI Hook) for Claude Code & Google Antigravity**
|
|
6
|
+
|
|
7
|
+
[](#systems-architecture--zero-trust-security)
|
|
8
|
+
[](#deterministic-preinvocation-router--6-local-sensors)
|
|
9
|
+
[](#quick-start)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](#-installation--quick-start)
|
|
12
|
+
|
|
13
|
+
[**Live Interactive Demo**](https://gizzant.github.io/attention-horizon-antigravity/) • [**Quick Start**](#-installation--quick-start) • [**Cookbook & Recipes**](docs/COOKBOOK.md) • [**Systems Architecture**](#systems-architecture--zero-trust-security)
|
|
14
|
+
|
|
15
|
+
<br/>
|
|
16
|
+
|
|
17
|
+
<img src="assets/hero-demo.svg" alt="Highbeam 40-Cell ANSI HUD & PreInvocation Router" width="100%" />
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## ⚡ Installation & Quick Start
|
|
24
|
+
|
|
25
|
+
| **Google Antigravity** *(1-Line Install)* | **Claude Code** *(1-Line Install)* |
|
|
26
|
+
| :--- | :--- |
|
|
27
|
+
| ```bash
|
|
28
|
+
npx ctxtop init
|
|
29
|
+
``` | ```bash
|
|
30
|
+
npx ctxtop install --claude
|
|
31
|
+
``` |
|
|
32
|
+
| *Workspace-only*: `npx ctxtop init --workspace`<br/>*Health check*: `npx ctxtop doctor` | *StatusLine HUD*: `npx ah-statusline --demo`<br/>*In-chat pane*: `/horizon` · `/cost-radar` · `/handoff` |
|
|
33
|
+
|
|
34
|
+
### Your First 5 Minutes After Installing
|
|
35
|
+
|
|
36
|
+
#### 1. Google Antigravity Workflow
|
|
37
|
+
1. **Install hooks & sidecar**: Run `npx ctxtop init` in your project root (or globally).
|
|
38
|
+
2. **Open the Highbeam Sidepane**: Launch the local telemetry WebView (`npx ctxtop --serve` or via the Antigravity sidepane) to view real-time context health:
|
|
39
|
+
- **Simple View (Default)**: 4 glanceable zones—**Zone A** (Safe Headroom & Warm KV Cache TTL), **Zone B** (`DO / AVOID / HOLD` Model & Effort switch guidance), **Zone C** (Live automated interventions), and **Zone D** (Verified tokens/USD saved + 1-click `/compact`).
|
|
40
|
+
- **Advanced View (1-Click Toggle)**: Expands the **40-Cell Chrono-Positional Recall Grid** (`Primacy 0–30%`, `Mid-Trough 30–70%`, `Recency 70–100%`), top token consumer file table, `Off / Coach / Auto-Pilot` mode switcher, and the full `DET-01..32` guard log.
|
|
41
|
+
3. **Code normally**: Highbeam runs in **`COACH` mode** by default—automatically compressing verbose CLI test dumps via SQLite FTS5 and folding repeat file reads without interrupting your prompts.
|
|
42
|
+
|
|
43
|
+
#### 2. Claude Code Workflow
|
|
44
|
+
1. **Install plugin & hooks**: Run `npx ctxtop install --claude` to wire `.claude-plugin/plugin.json`, `hooks/hooks.json`, and the live terminal `statusLine`.
|
|
45
|
+
2. **Watch the Live Terminal `statusLine`**: At the bottom of your terminal, Highbeam renders an auto-adapting (`80 / 110 / 144` col) telemetry bar:
|
|
46
|
+
```text
|
|
47
|
+
AH [SCCCCCCC................] sonnet-5-5 64k/200k (32%) · Cache 88% (4m12s) · COACH · Saved $1.84
|
|
48
|
+
```
|
|
49
|
+
3. **Open the In-Chat Docked HUD**: Type `/horizon` in chat (or run `npx ah-claude panel` for the standalone HTML workbench) to inspect cache gravity, active guards, and reclaimable tokens.
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## 🧭 Built-In Slash Skills & In-Chat Commands (Both Hosts)
|
|
54
|
+
|
|
55
|
+
All 6 slash skills are registered identically in both **Google Antigravity** (`plugin.json`) and **Claude Code** (`.claude-plugin/plugin.json`):
|
|
56
|
+
|
|
57
|
+
| Slash Command / Skill | When to Use It | What It Outputs |
|
|
58
|
+
| :--- | :--- | :--- |
|
|
59
|
+
| **`/horizon`** | Anytime during a coding session | Renders the live 40-cell Context Health HUD, KV-Cache TTL countdown, active `DO / AVOID / HOLD` guidance, and reclaimable clutter breakdown. |
|
|
60
|
+
| **`/precheck`** | Before sending a complex refactor prompt or switching models | Audits prompt specificity (6-dimension rubric), checks horizon-aware KV-cache break-even (`C_max` & warm-request payback), and recommends the optimal Model & Effort tier. |
|
|
61
|
+
| **`/handoff`** | Before running `/compact` or `/clear` at `>=75%` context fill | Distills active plan checkboxes, modified files, and unresolved `stderr` into a compressed `<1,000`-token checkpoint (`task.md` / `.handoff.md`). |
|
|
62
|
+
| **`/cost-radar`** | When reviewing session token burn or cache busts | Generates an interactive HTML/SVG timeline of prefix-cache retention, `DET-30` thinking drift loops, and subagent worktree topology. |
|
|
63
|
+
| **`/inspect`** | When diagnosing slow tools or subagent fan-out | Visualizes session trajectory call-tree spans, per-tool latencies, and token attribution as a standalone artifact. |
|
|
64
|
+
| **`/evolve`** | After correcting agent mistakes across a session | Audits `AGENTS.md` / `CLAUDE.md` Turn-0 prefix budget (`<=20k` tok) and synthesizes validated session instincts via 1-click diff approval. |
|
|
65
|
+
|
|
66
|
+
**Quick In-Chat Prompt Prefixes:**
|
|
67
|
+
- `! <prompt>` — Bypass `PreInvocation` checks for a single turn.
|
|
68
|
+
- `!lock <prompt>` — Freeze current reasoning effort tier and prefix state for the remainder of the session.
|
|
69
|
+
- `#check <prompt>` — Force an explicit pre-flight scorecard and concrete prompt rewrite suggestion.
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 🛡️ Verified Token Receipt: `+164.0k` Tokens Saved in One 4-Step Coding Loop
|
|
74
|
+
|
|
75
|
+
Most CLI trackers passively count tokens *after* your quota is already burned. Highbeam intercepts redundant reads, compresses noisy test dumps via local SQLite FTS5, and shields warm KV prefixes **before** they hit your billing meter:
|
|
76
|
+
|
|
77
|
+
<div align="center">
|
|
78
|
+
<img src="assets/zone_c_step3_shield_full.png" alt="Highbeam Zone C Active Protection & Verified Token Receipt (+164.0k tokens saved)" width="460" />
|
|
79
|
+
</div>
|
|
80
|
+
|
|
81
|
+
| Step in Coding Loop | Developer / Agent Action | Highbeam Active Intervention (Zone C) | Verified Savings |
|
|
82
|
+
| :--- | :--- | :--- | :---: |
|
|
83
|
+
| **1. Warm KV Cache + Repeat Read** | Agent re-reads an unmodified 800-line source file on a `100k` warm cache | **GUARD-4** intercepts the duplicate read (`AST signature stub`) and preserves the `95%` warm KV cache discount | **`+95.0k` tok** *(KV cache)*<br/>**`+800` tok** *(deduped read)* |
|
|
84
|
+
| **2. Failing Test Suite Dump** | `npm test` dumps `120+` lines of verbose stdout (`~11.4k` tokens) | **SQLite FTS5 BM25 Compressor** indexes raw stdout locally and injects only the 160-token failing assertion digest | **`+11.2k` tok** |
|
|
85
|
+
| **3. Mid-Session Rule Edit** | Agent updates `AGENTS.md` / `CLAUDE.md` while `60k` prefix is warm (`2m 55s` TTL left) | **PrefixCacheShield** queues the rule delta until TTL expiry or `/compact`, preventing a cold prefix rebuild | **`+57.0k` tok** |
|
|
86
|
+
| **Total Verified Session Receipt** | **4-Step Feature / Bugfix Loop** | **Zero context dilution · 100% critical error retention** | **`+164.0k` tok (`~$0.33`)** |
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## 💡 Why Saved Tokens Multiply (`O(N²)` Turn Compounding, Quota Life & Model IQ)
|
|
91
|
+
|
|
92
|
+
In agentic coding, every turn re-sends the entire prior conversation history. A single `15,000`-token raw test dump on Turn 5 is not billed once—it is re-sent on Turns 6 through 25, burning **`300,000` cumulative tokens** (`15,000 × 20`).
|
|
93
|
+
|
|
94
|
+
1. **For Fixed-Subscription Users (`Claude Pro / Max`, `Antigravity OAuth Seats`) — Stop 2:00 PM Quota Lockouts & Context Rot**:
|
|
95
|
+
- Compressing noisy tool outputs and duplicate file reads on early turns prevents `O(N²)` history compounding, **stretching 5-hour sprint quotas by `30%–50%`**.
|
|
96
|
+
- Even more importantly, keeping your session below the **70% Safe Horizon** prevents **Context Rot** (middle-window attention decay where the model starts forgetting `AGENTS.md`/`CLAUDE.md` rules, hallucinating imports, and breaking working code).
|
|
97
|
+
2. **For Metered API & Enterprise Teams — Self-Expensing FinOps ROI**:
|
|
98
|
+
- Preventing just two accidental warm-cache busts per day (switching models mid-TTL or editing rule files on a `100k` warm prefix) plus FTS5 log compression saves **`$3–$12/day` (`$60–$240/month`) per active seat**.
|
|
99
|
+
3. **Daily Cockpit Decisions No Human Can Calculate in Their Head (Zone B)**:
|
|
100
|
+
- *"If I downshift from Opus/Argon to Sonnet/Flash right now, will I save quota or pay a 10x cold-prefill penalty?"* — Highbeam computes the horizon-aware KV-cache break-even limit (`C_max`) and post-switch warm-request payback in real time and displays a 1-line verdict: **`Model: Hold (03:34) — switching busts warm cache · Effort: changing busts warm cache`**.
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## ⚙️ What Runs Automatically (Zero-Friction `COACH` Default)
|
|
105
|
+
|
|
106
|
+
Highbeam defaults to **`COACH` mode**—performing lossless token surgery silently in the background while never blocking your chat prompt unless a true 3-strike identical failure loop or destructive git command occurs:
|
|
107
|
+
|
|
108
|
+
| Automated Feature | How It Works Under the Hood | Developer Experience |
|
|
109
|
+
| :--- | :--- | :--- |
|
|
110
|
+
| **1. SQLite FTS5 CLI & Test Output Compression** (`PostToolUse`) | Strips ANSI/progress noise, indexes full stdout in local SQLite FTS5 (`porter unicode61`), and injects only the compact failing assertion digest | **100% automatic** — saves `50%–90%` of test/build log tokens with zero lost stack traces |
|
|
111
|
+
| **2. Post-Edit Delta Diffs & 3rd-Read AST Stubs** (`GUARD-4` in `PreToolUse`) | When the agent re-reads a file after editing 5 lines (or reads the same unclipped file `>=3` times), returns a unified line diff or function-signature AST stub | **100% automatic** — cuts repeat-read token burn by `80%+` without interrupting the agent |
|
|
112
|
+
| **3. `PrefixCacheShield` Warm Rule & Effort Deferral** (`DET-09`) | Intercepts mid-session edits to `AGENTS.md` / `CLAUDE.md` while a KV cache is warm, and checks `MODEL_EFFORT_CACHE_CAPABILITIES` on effort changes: defers on `4.6` models (`EF1_46` / article), stays silent on measured cache-preserving `claude-sonnet-5-5` (`r2_effort.csv`, `n = 3` with thinking expansion) and `claude-opus-5-5` (`currency_55.csv` `effort_only_55`, behaviour **unverified**), and warns with `"unverified for this model"` on untested models | **Model-aware cache protection** — prevents silent `4.6` / rule-file cold prefix rebuilds without false-positiving on `5.5` effort |
|
|
113
|
+
| **4. Live Model & Effort Switch Verdict** (`Zone B`) | Evaluates remaining KV cache TTL (`5m`/`1h`) and horizon break-even (`C_max` & warm-request payback) across `MODEL / HOLD / SWITCH / LOCK` states | **Instant visual guidance** — tells you when to hold vs. switch models or lower thinking effort |
|
|
114
|
+
| **5. Held Downshift & Boundary Lifecycle** (`SessionStart:compact` / `Stop`) | Surfaces held `pending_downshift` after compaction via `SessionStart:compact` `systemMessage` (`0` `/v1/messages` tokens leaked) without adding custom `PreCompact` or `SessionStart` preservation templates; optional task-boundary `/compact` advisor is gated **OFF by default** (`smartCompactBoundarySuggest: false`, boundary detector **unverified**) | **Post-compact downshift handoff** — reminds `/model <target>` once after compaction, when switching avoids full pre-compact rewrites |
|
|
115
|
+
| **6. Git Hook-Bypass & Destructive Shell Guard** (`DET-18` / `DET-19`) | Blocks `git commit --no-verify`, `-n`, `core.hooksPath` tampering, and unconfirmed `git reset --hard` | **Zero-config repo safety** — keeps frustrated agents from bypassing your pre-commit linters |
|
|
116
|
+
| **7. `PreModelSwitch` Warm KV-Cache Guard** (`DET-08`) | Evaluates KV-cache TTL (`5m`/`1h`), Stop-hook shrunk rolling-median `requestsPerTurn` (`R`, cold-start placeholder prior overridden once `>= 3` non-current, non-benchmark deduplicated sessions exist in `~/.claude/projects/**/*.jsonl`), Stop-hook rolling median prompt growth (`g` tok/turn, capped at `g = 0` until `n >= 5` observed turns and a stable regime; with `< 5` observed turns, the hook omits the net dollar figure and shows payback in requests first and turns in parentheses), horizon limit `C_max`, Stop-hook rolling output shrinkage, and warm-request payback (`AUTO_PILOT`). **Catalog-derived per-pair payback:** All break-even thresholds (`C*`, `C_max`), cold-write penalties, and warm-request paybacks (`~a / b` where `a = P_write,B - P_read,A` and `b = P_read,A - P_read,B`, less output credit and `R - 1` switch-turn reads) are derived at runtime from `anthropicModelCatalog.json` with no hard-coded constants. Unknown model IDs return explicit `unknownModel: true` with `null` USD fields, no price-based hold, a one-line unknown-price advisory, and a `ctxtop doctor` `WARN`. Under headless `claude -p`/SDK, `"ask"` becomes `blocked_by_hook`; override with `"DET-08": "warn"` or `expectedRemainingTurns`. | **Protects mid-session switches** — reports payback in post-switch warm requests (turns in parentheses), allows post-compaction splits cleanly, and never hallucinates fallback prices |
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Measured behaviour (Claude Code 2.1.325)
|
|
121
|
+
|
|
122
|
+
Empirical findings from the suite (every item cites its source file; unmeasured behaviors are labeled **unverified**):
|
|
123
|
+
|
|
124
|
+
- Editing `CLAUDE.md` before `--resume` does not invalidate the cache; the old and new versions both stay in context (`T6 CC-M`, `t6_layers.csv`).
|
|
125
|
+
- `--append-system-prompt` is ignored on `--resume` (`T6 CC-S`, `t6_layers.csv`).
|
|
126
|
+
- Changing MCP servers or the tool list on resume wipes the cache (`T6 CC-T`, `t6_layers.csv`).
|
|
127
|
+
- `PreCompact` instructions must be plain text on stdout; JSON is dropped (`Phase 0`, `$0` binary & mock-SSE audit; Highbeam emits zero custom `PreCompact` or `SessionStart` preservation templates since `summary_smart_compact.md` found `0/6` violations up to `28.10x` compression without them).
|
|
128
|
+
- Auto-memory added about `23.5%` to session cost in the smart-compact fixture (`n = 2 vs 2`, `summary_smart_compact.md`); this is a cost note, not a recommendation to disable it.
|
|
129
|
+
- On OpenRouter, `max_tokens: 0` still generates output; cache pre-warming with 0 output works on the direct API only (`Phase 0`, `T3b`).
|
|
130
|
+
- A 1-hour cache costs `2x` on writes and wins once a `5–60` minute pause occurs (`T3a`).
|
|
131
|
+
|
|
132
|
+
**SDK / `stream-json` host downshift pattern (`Item 4.2`):** Interactive hooks (`SessionStart:compact`, `PostCompact`) cannot set `mainLoopModel` (`Phase 0`). In interactive Claude Code, Highbeam emits a one-line `SessionStart:compact` `systemMessage` (`0` tokens injected into `/v1/messages`, verified at `$0` on `claude.exe@2.1.325`) naming `/model <target>`, and avoids invalid `PostCompact` `hookSpecificOutput`. In SDK or `stream-json` hosts, inspect stream frames for `compact_boundary` and call `set_model` on the host controller immediately afterward — never from inside a hook.
|
|
133
|
+
|
|
134
|
+
**Resume toolset visibility (`Item 6`):** On `claude.exe@2.1.325`, `SessionStart:resume` stdin supplies `context_tokens` and `prompt_cache_likely_expired` but does not expose `tools` or `mcp_servers` (and `deferred_tools_delta` is written to `.jsonl` after `SessionStart`). Highbeam therefore hashes observable config files (`.mcp.json`, `.claude/settings*.json`, `~/.claude.json`), CLI `--mcp-config`/`--tools` flags when provided, and optional host arrays, and warns when hashes differ on large non-expired resumes (`t6_layers.csv` `CC-T`).
|
|
135
|
+
|
|
136
|
+
**Unverified items explicitly labeled:** `claude-opus-5-5` effort-change behaviour (`currency_55.csv` verified cache preservation only; reasoning output change unverified), `DET-09` effort behaviour on non-`4.6`/non-`5.5` models (`"unverified for this model"`), and `evaluateTaskBoundaryTurn` compaction suggestions (`phase1_boundary_detector.csv`: `80.00%` precision on scripted plans, `0` organic boundaries; `smartCompactBoundarySuggest` defaults to `false` and suggests only with estimated `~2-minute` pause per `summary_smart_compact.md` H4/H7).
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## 🌱 Zero-Waste AI Engineering: FinOps + GreenOps (Scope 3 Compute Efficiency)
|
|
141
|
+
|
|
142
|
+
For systems engineers, re-sending a 40,000-token test log 15 times is the AI equivalent of a memory leak—it wastes datacenter GPU prefill cycles, increases time-to-first-token (TTFT) latency, and degrades reasoning quality.
|
|
143
|
+
|
|
144
|
+
For **Engineering Managers and Enterprise FinOps / Sustainability teams**, every `1,000,000` redundant frontier LLM tokens prevented avoids approximately **`~0.65 kWh` (`650 Wh`) of datacenter GPU prefill energy** (`~247g CO₂e` and associated cooling water). Highbeam's local **Corporate PDF 1.4 Expense Receipt** (`npx ctxtop receipt --pdf`) automatically reports both **Verified USD Saved (FinOps)** and **Estimated GPU Compute Energy Avoided (GreenOps / Scope 3)** with a cryptographic SHA-256 audit digest—giving teams a dual cost-and-sustainability justification with zero cloud telemetry.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Why Highbeam (`ctxtop`) Exists (vs. Cloud LLM Observability)
|
|
149
|
+
|
|
150
|
+
Cloud trace platforms (Langfuse, Helicone, Arize) require proxying API keys over the network and only observe HTTP request/response payloads. They have **zero visibility into the local filesystem, git working tree, IDE process table, or local SQLite/JSONL session stores**.
|
|
151
|
+
|
|
152
|
+
`ctxtop` is a zero-dependency local systems profiler built on Node.js built-ins (`node:sqlite`, `node:fs`, `node:http`). It correlates local session transcripts and SQLite databases with live disk state to catch concrete failure modes that cloud proxies cannot see:
|
|
153
|
+
|
|
154
|
+
| Failure Mode | Root Cause in Agentic Sessions | How `ctxtop` Detects & Remediates It Locally |
|
|
155
|
+
| :--- | :--- | :--- |
|
|
156
|
+
| **12.5x–80x Prompt Cache Tax & Overage TTL Cliffs** | Falling from a 1-hour prompt cache tier to a 5-minute overage/fallback tier, or mutating system/MCP blocks mid-session while holding `>50k` warm tokens, triggers an uncached prefix rebuild. | Tracks Dual-TTL windows (`1h` vs `5m` main + `5m` subagent), pinpoints the exact turn/component/byte offset of prefix mutations (`computePrefixMutationDiff`), and enforces a Cold-Session Cost Gate. |
|
|
157
|
+
| **Compaction Lobotomy & Post-Compact Re-Read Tax** | Autocompact at 80%–95% context wipes file line numbers, active `task.md` checklists, and unresolved `stderr`, forcing the agent to re-read the same unmodified files immediately after compaction. | Deterministically distills `.handoff.md` before compaction (`>=80%` saturation), tracks post-compaction re-reads of unmodified files, and synthesizes `<1,000`-token `[▶ RESUME HERE]` packs via SQLite FTS5 BM25 episodic memory. |
|
|
158
|
+
| **30GB–100GB Local IDE Storage Bloat (`state.vscdb`)** | Orphaned Cursor `bubbleId:*`, `checkpointId:*`, `messageRequestContext:*`, and unreferenced `agentKv:blob:*` rows accumulate in SQLite `cursorDiskKV` until disk space or `VACUUM` locks fail. | Audits and reclaims orphaned rows via streaming read-only SQLite export (`--gc-cursor` / `--storage-gc`) without requiring a 2x-disk-space in-place `VACUUM` lock, and recovers orphaned Antigravity `brain/` artifacts (`--recover-brain`). |
|
|
159
|
+
| **Stale File Overwrites (`DIRTY_SNAP`)** | Developer edits or runs `git pull` on a file the agent read 10 turns ago; the agent overwrites disk changes with its stale in-context snapshot. | Compares `fs.statSync(path).mtimeMs` on disk against the last `read_file` / `view_file` step timestamp in the JSONL transcript (`+1000ms` tolerance) and injects a pre-turn re-read guard. |
|
|
160
|
+
| **Unseen Call-Site Breakage (`UNSEEN_CALLERS`)** | Agent modifies an exported function signature without reading downstream callers in the repo. | Runs a bounded `<8ms` regex import scan (`import ... from`, `require()`, Python `from ... import`) across workspace files (up to 250 files) and flags callers absent from the active working set. |
|
|
161
|
+
| **Superseded Full-File Reads & Tool Sludge (`--prune-tools`)** | Agent reads the same 800-line file 6 times, runs unreferenced exploratory `grep` searches, or retains resolved test `stderr` traces, diluting middle-window recall. | Pairs `tool_use` and `tool_result` across Antigravity, Claude Code, and Cursor while pinning Turn 0 and the newest 6 turns; truncates stale tool outputs offline with an atomic `.pre_surgeon` backup. |
|
|
162
|
+
| **Turn-0 MCP Schema Bloat (`SCHEMA_TAX`)** | Eagerly loaded MCP servers inject 15k–40k tokens of JSON tool schemas on Turn 0 even when never invoked. | Computes per-server Token ROI (`calls / schemaTokens`, `IDLE_BLOAT_TAX`) and dynamic `deferred_tools_delta` expansion, flagging 0-call eager servers to switch to `"loading": "lazy"`. |
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## Multi-Harness v4.0 Wedge Capabilities
|
|
167
|
+
|
|
168
|
+
1. **Cross-Harness SQLite & Protobuf Trajectory Stitcher (`src/core/trajectory_stitcher.mjs`)**:
|
|
169
|
+
- **Google Antigravity (`[App]`, `[IDE]`, `[CLI]`)**: Zero-dependency protobuf wire-walker (`decodeProtobufWire`) inspects `conversations/<uuid>.db` (`steps` table binary `step_payload` and `metadata` blobs) in strict read-only mode to extract `file:///` workspace URIs and stitch with `transcript_full.jsonl` and `annotations/<uuid>.pbtxt`.
|
|
170
|
+
- **Claude Code**: Reconstructs the `uuid -> parentUuid` DAG up to the active `leafUuid`, isolating `/rewind` branches, `file-history-snapshot` restore points, and Turn-1 `cache_creation_input_tokens`.
|
|
171
|
+
- **Cursor**: Correlates `composerData:<id>`, `bubbleId:<id>:<bubble>`, `messageRequestContext`, and `agentKv:blob:*` (`requestId`) with `store.db` and timestamp-less `agent-transcripts/*.jsonl`.
|
|
172
|
+
2. **Subagent Worktree & File Collision Detector (`src/core/subagents.mjs`)**:
|
|
173
|
+
- Builds a parent-to-child subagent DAG, tracks independent 5-minute child cache TTLs, and flags `SUBAGENT_FILE_COLLISION` when `>= 2` concurrent subagent branches edit the same canonical file path.
|
|
174
|
+
3. **SQLite FTS5 Episodic Memory & Git Commit Token Ledger (`src/core/episodic_memory.mjs`, `src/core/git_ledger.mjs`)**:
|
|
175
|
+
- Indexes historical session decisions, modified files, and resolved bug signatures into a local SQLite FTS5 (`porter unicode61`) store (`~/.ctxtop/episodic_memory.sqlite`) for `<1,000`-token BM25 retrieval.
|
|
176
|
+
- Correlates `.git/logs/HEAD` commit timestamps against session windows to attribute input/output tokens, cache hit %, and USD cost per git commit.
|
|
177
|
+
4. **Zero-PII Sanitizer & Forensic Snapshot Exporter (`src/core/sanitizer.mjs`)**:
|
|
178
|
+
- Scrubs API keys (`sk-ant-*`, `sk-proj-*`, `AIza*`), GitHub PATs (`ghp_*`, `github_pat_*`), AWS keys, Bearer tokens, `.env` values, and OS home paths (`<USER_HOME>`) before exporting shareable forensic JSON snapshots.
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## Quick Start
|
|
183
|
+
|
|
184
|
+
### 1. Inspect Live Sessions, Prune Tool Sludge, or Run Storage GC
|
|
185
|
+
```bash
|
|
186
|
+
# Audit the last 5 local sessions for duplicate file reads, dead errors & MCP schema tax
|
|
187
|
+
node src/cli/postmortem.mjs --last 5
|
|
188
|
+
|
|
189
|
+
# Run environment & transcript health diagnostics (hooks, SQLite/JSONL confidence, 3-way mirror SHA-256)
|
|
190
|
+
node src/cli/doctor.mjs
|
|
191
|
+
|
|
192
|
+
# Run offline Prefix-Safe Tool-Output Surgeon on the active session transcript (with atomic backup)
|
|
193
|
+
node src/cli/doctor.mjs --prune-tools --dry-run
|
|
194
|
+
|
|
195
|
+
# Recover orphaned Antigravity brain/ directories or compact Cursor state.vscdb without VACUUM locks
|
|
196
|
+
node src/cli/doctor.mjs --recover-brain --gc-cursor --vscdb path/to/state.vscdb --dry-run
|
|
197
|
+
|
|
198
|
+
# Print the 40-cell ANSI status bar for the active session
|
|
199
|
+
node src/cli/horizon_hud.mjs --live
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### 2. Launch the Local Telemetry WebView (`127.0.0.1`)
|
|
203
|
+
```bash
|
|
204
|
+
# Start the loopback sidecar daemon and open the Tufte WebView
|
|
205
|
+
node sidecars/horizon-daemon/server.mjs
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### 3. Install Lifecycle Hooks & CLI `statusLine`
|
|
209
|
+
```bash
|
|
210
|
+
# Global install (~/.gemini/config/plugins/agy-horizon-flightcheck)
|
|
211
|
+
node src/cli/init.mjs init
|
|
212
|
+
|
|
213
|
+
# Workspace-local install (.agents/plugins/agy-horizon-flightcheck)
|
|
214
|
+
node src/cli/init.mjs init --workspace
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
> [!TIP]
|
|
218
|
+
> Looking for copy-paste recipes for Cursor 50GB storage reclamation, offline tool pruning, Antigravity brain recovery, or programmatic Node.js API snippets? See the [**`ctxtop` Cookbook & Recipes**](docs/COOKBOOK.md).
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## Systems Architecture & Zero-Trust Security
|
|
223
|
+
|
|
224
|
+
`ctxtop` is engineered for strict operational safety alongside live IDE/CLI database writers:
|
|
225
|
+
|
|
226
|
+
1. **Zero Outbound Network Connections**:
|
|
227
|
+
- **0 runtime `npm` dependencies** (`package.json` has no `dependencies` block).
|
|
228
|
+
- **0 external HTTP/HTTPS requests, telemetry beacons, or remote API calls**. All parsing, classification, and routing run 100% in-memory on the local machine.
|
|
229
|
+
- The local WebView daemon (`sidecars/horizon-daemon/server.mjs`) binds strictly to `127.0.0.1` (loopback only) and rejects cross-origin `Origin` or non-local `Host` headers (`HTTP 403`) to prevent DNS rebinding and drive-by localhost CSRF.
|
|
230
|
+
2. **Read-Only Database & Transcript Introspection (`SQLITE_OPEN_READONLY`)**:
|
|
231
|
+
- Every connection to Antigravity or Cursor SQLite databases (`conversations/<uuid>.db`, `conversation_summaries.db`, `state.vscdb`, `store.db`) is opened via Node's native `node:sqlite` `DatabaseSync` with `Object.freeze({ readOnly: true })` (`SQLITE_OPEN_READONLY`). `ctxtop` can never contend for write locks with an active IDE or CLI.
|
|
232
|
+
- Live JSONL transcripts (`transcript_full.jsonl` / `transcript.jsonl`) are read via `fs.openSync(filePath, 'r')` using byte-offset slicing (`O(Δbytes)` per turn), falling back to full re-parse only when a step-index regression (Undo/Rewind) is detected.
|
|
233
|
+
3. **Ring 1 Security, Concurrency & Context Hygiene Boundaries**:
|
|
234
|
+
- **`DET-19` Git Hook-Bypass Guard**: Intercepts `git` execution via `.agents/shims/` wrappers, strips `.agents/shims` from `PATH` to eliminate recursion, blocks verification evasion (`--no-verify`, standalone `-n`, `-amn`, `--no-gpg-sign`, `core.hooksPath`), and allows bypass strictly via a 60-second single-use cryptographic human nonce.
|
|
235
|
+
- **Zero-Token Subagent IPI Sanitizer**: Deterministically strips Unicode Tag characters, zero-width spaces, bidi overrides, HTML comments, and delimiter breakouts in `<1ms`, framing external research digests safely at prompt tails under `<untrusted_subagent_data>`.
|
|
236
|
+
- **Pre-Threshold ANSI Normalization (`DET-14b`)**: Strips ANSI escape sequences and collapses carriage returns (`\r`) before the 4,096-char threshold and SQLite FTS5 archival, featuring specialized noise profiles for `cargo test` and `npm install` with Critical Error-Line Recovery.
|
|
237
|
+
- **Concurrent Scope Lockfile (`DET-20`)**: Manages `.agents/locks/active_scopes.json` with atomic writes, auto-evicting dead PIDs and expired leases (>300s), while alerting on multi-agent file collisions with 1-click `git worktree add` commands.
|
|
238
|
+
4. **Locked v4.0 Edward Tufte UI Laws**:
|
|
239
|
+
- **Law 1 (Raw Physical Units Only)**: Displays `Tokens + %`, `Cache Hit %`, `Waste Tokens`, and `1h/5m TTL Countdown` side-by-side—never arbitrary `0–100` gamified scores.
|
|
240
|
+
- **Law 2 (40-Cell Hero + Top 3–5 Riskiest Cells)**: Surfaces the top 3–5 highest-risk context cells directly below the 40-cell flamegraph with exact file paths, attention recall %, and 1-click `[Re-Anchor / Prune]` actions.
|
|
241
|
+
- **Law 3 (Zero-Click Passive Workload Tag)**: Passively classifies sessions into `[Mode: Read-Heavy Audit]`, `[Mode: Multi-File Refactor]`, or `[Mode: Subagent Swarm]` from tool-call ratios.
|
|
242
|
+
- **Law 4 (Silent-When-Nominal Watchdog)**: Host RAM and orphan process counters remain completely hidden unless an anomaly (`orphanCount > 0` or `ZOMBIE_LEAK`) occurs.
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## 🔧 Configuration, Flight Modes & MCP Server (`@ctxtop/mcp`)
|
|
247
|
+
|
|
248
|
+
### 1. Customizing `.attention-horizon.json` (Flight Modes & Detector Overrides)
|
|
249
|
+
Highbeam works with zero configuration out of the box (`COACH` mode). To customize behavior per-repository or globally (`~/.attention-horizon.json`), use the CLI or create `.attention-horizon.json` in your workspace root:
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
# Set a detector to warn-only, block, or off via CLI
|
|
253
|
+
npx ctxtop config DET-08 warn
|
|
254
|
+
npx ctxtop config DET-19 block
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
```json
|
|
258
|
+
{
|
|
259
|
+
"flightMode": "COACH",
|
|
260
|
+
"turnZeroTokenBudget": 20000,
|
|
261
|
+
"detectors": {
|
|
262
|
+
"DET-06": "block",
|
|
263
|
+
"DET-07": "block",
|
|
264
|
+
"DET-08": "warn",
|
|
265
|
+
"DET-09": "block",
|
|
266
|
+
"DET-19": "block",
|
|
267
|
+
"DET-20": "warn"
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
```
|
|
271
|
+
- **`"COACH"` *(Default)***: Compresses CLI output (`DET-07`), folds repeat file reads (`GUARD-4`), and stages warm rule edits (`DET-09`) automatically while advising on model/cache switches without blocking normal flow.
|
|
272
|
+
- **`"AUTO_PILOT"`**: Enforces strict pre-turn & stop-gate verification locks (e.g., requiring tests to run after source edits before session completion).
|
|
273
|
+
- **`"SILENT"` / `"OFF"`**: Passive telemetry collection only.
|
|
274
|
+
|
|
275
|
+
### 2. Using Highbeam as an MCP Server (`ctxtop-mcp`)
|
|
276
|
+
Any MCP-compatible client (**Google Antigravity**, **Claude Code**, **Cursor**, **Windsurf**, or **Claude Desktop**) can query Highbeam's telemetry and KV-cache advisor via standard JSON-RPC stdio:
|
|
277
|
+
|
|
278
|
+
```json
|
|
279
|
+
{
|
|
280
|
+
"mcpServers": {
|
|
281
|
+
"highbeam": {
|
|
282
|
+
"command": "npx",
|
|
283
|
+
"args": ["-y", "ctxtop-mcp"]
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
```
|
|
288
|
+
Exposes 4 read-only MCP tools (`<5ms` response): `get_context_telemetry`, `check_cache_gravity`, `get_savings_receipt`, and `inspect_detectors`.
|
|
289
|
+
|
|
290
|
+
---
|
|
291
|
+
|
|
292
|
+
## Deterministic `PreInvocation` Router & 6 Local Sensors
|
|
293
|
+
|
|
294
|
+
When registered in `hooks.json`, `src/hooks/pre_invocation.mjs` evaluates incoming prompts across 8 deterministic router states (**Tier-1 In-Process Router Evaluation: `~0.18ms p95`** inside a warm V8 isolate; **Tier-2 Spawned CLI Hook End-to-End Wall Time: `~25–45ms` POSIX / `~40–90ms` Windows PowerShell** including Node process startup):
|
|
295
|
+
|
|
296
|
+
1. `ALLOW_SILENT`: Immediate pass-through (`{}`) on `!` bypass prefix or healthy turns.
|
|
297
|
+
2. `ALLOW_ACTIVE_SET`: Silent pass-through when referenced files are already warm in the last 5 turns.
|
|
298
|
+
3. `ALLOW_PLAN_OR_SUBAGENT`: Silent pass-through during `/plan` mode or subagent delegation.
|
|
299
|
+
4. `INJECT_CONTEXT_GUARD`: Appends a `systemMessage` warning when target files were modified externally on disk (`DIRTY_SNAP`), have unseen callers (`UNSEEN_CALLERS`), or touch deprecated paths (`LEGACY_POISON`).
|
|
300
|
+
5. `STEER_SUBAGENT`: Advises `invoke_subagent` when a broad exploratory prompt would pollute a warm `>30k`-token parent context window.
|
|
301
|
+
6. `HALT_HYGIENE_OR_SAFETY`: Halts execution (or warns in `advisory` mode) on context ceiling breach, 3-strike identical command error loops, or severe duplicate-read dilution.
|
|
302
|
+
7. `HALT_EFFORT_OR_QUOTA`: Warns when 5-hour/7-day quota falls below the configured floor (`10%`) or when `>600`-line single-shot file rewrites risk output stream truncation.
|
|
303
|
+
8. `HALT_REWRITE_SCORECARD`: Triggered via `#check` or vague cold-start prompts (`Turn <= 2`), outputting a 4-line prompt rewrite scorecard.
|
|
304
|
+
|
|
305
|
+
---
|
|
306
|
+
|
|
307
|
+
## CLI Commands & Forensic Postmortem
|
|
308
|
+
|
|
309
|
+
| Command | Description |
|
|
310
|
+
| :--- | :--- |
|
|
311
|
+
| `npx ctxtop init [--workspace]` | Installs Google Antigravity plugin manifests, lifecycle hooks, and sidecar configuration. |
|
|
312
|
+
| `npx ctxtop install --claude` | Installs Claude Code `.claude-plugin` manifest, Tier-1/Tier-2 hooks, and terminal `statusLine`. |
|
|
313
|
+
| `npx ctxtop doctor [--diagnostic]` | Validates hook registration, config overlays, dynamic model ceilings, 3-way WebView SHA-256 parity, and SQLite/JSONL health. |
|
|
314
|
+
| `npx ctxtop postmortem [--last N] [--json]` | Scans the last `N` local sessions, classifies root causes (`CONTEXT_ROT_DECAY`, `VERIFICATION_CHURN`, `SPEC_AMBIGUITY`, `CLEAN`), lists top duplicate-read files, and audits Turn-0 MCP schema overhead. |
|
|
315
|
+
| `npx ctxtop receipt [--markdown \| --pdf]` | Exports a SHA-256 verified FinOps + GreenOps token/USD savings receipt for the active workspace. |
|
|
316
|
+
| `npx ctxtop verify [--json]` | Verifies cryptographic SHA-256 integrity of all 149 release files against `CHECKSUMS.sha256`. |
|
|
317
|
+
| `npx ctxtop --roast` | Prints a terminal forensic summary of recent sessions with top duplicate-read file offenders and copy-pasteable remediations. |
|
|
318
|
+
| `npx ctxtop --serve` | Launches the local HTTP/SSE telemetry daemon (`127.0.0.1`) and interactive WebView (`/` Simple, `/advanced` Advanced). |
|
|
319
|
+
| `npx ctxtop --demo-animate` | Plays the 5-stage terminal crisis simulation across synthetic fixtures. |
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
## Verification & Benchmarks
|
|
324
|
+
|
|
325
|
+
Run the full zero-dependency test and verification suite (**1,050+ tests across 215+ suites**):
|
|
326
|
+
|
|
327
|
+
```bash
|
|
328
|
+
# Full Coach, UI, & 360° Capability-Proof suite (911+ tests across 183+ suites)
|
|
329
|
+
npm run test:coach
|
|
330
|
+
|
|
331
|
+
# Claude Code dual-tier Mod, CLI hooks, statusLine, and 5-category ledger suite (168 tests)
|
|
332
|
+
npm run test:claude
|
|
333
|
+
|
|
334
|
+
# Unit & Multi-Harness Wedge suite (89 tests across 31 suites)
|
|
335
|
+
npm run test:unit
|
|
336
|
+
|
|
337
|
+
# Architectural verification suite (Gates 0-6 & Phases 1-7: SQLite read-only locks, JSDOM UI, MCP audit)
|
|
338
|
+
npm run test:gates && npm run test:phases
|
|
339
|
+
|
|
340
|
+
# End-to-end context memory & live loopback daemon integration suite (7 layers)
|
|
341
|
+
npm run test:e2e
|
|
342
|
+
|
|
343
|
+
# Latency benchmark (200 iterations/path: Tier-1 ~3.0ms avg / <15ms SLA, Tier-2 CLI Hook, <45ms HUD)
|
|
344
|
+
npm run bench
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
---
|
|
348
|
+
|
|
349
|
+
## License
|
|
350
|
+
|
|
351
|
+
MIT © [Gizzant](https://github.com/Gizzant)
|