Foundations
Core Concepts & Mental Model
Highbeam treats each AI coding chat as a bounded working memory shaped by model attention and cache pricing. Four core ideas explain every warning, score, and guard in the tool.
Why Highbeam Exists
Long coding chats start failing quietly well before they hit a 200k or 1M token limit. Three common problems hurt code quality and drive up costs:
- Middle-of-Prompt Memory Drop: Model recall follows a U-shaped curve. Rules at Turn 0 (Primacy) and your newest tool outputs (Recency) stay sharp. Files and notes buried in the middle of a long chat are easy for the model to miss.
- Repeat File Reads & Log Bloat: Agents often re-read unchanged files or pull in huge test logs. That clutter pushes your early project rules toward the top edge where providers drop old tokens (a Context Truncation Crisis).
- Cold Cache Rebuilds: Switching models mid-chat or editing
AGENTS.mdorCLAUDE.mdwhile a prompt cache is warm breaks the cache prefix. Your next turn pays full1.25xcache-write prices across the whole history.
The 40-Cell Horizon Bar & U-Shaped Recall
Highbeam splits your active context limit into 40 time-ordered cells. Instead of one raw token count, the 40-Cell Horizon Bar shows what is in memory and where each item sits on the U-shaped recall curve.
AGENTS.md / CLAUDE.md) or the recent tail (ACTIVE_SET). Items stuck in the middle lose recall strength while still costing tokens every turn.
Dynamic 40-Cell Zoom Tiers
In Claude Code and shared UI views (src/core-isomorphic/ui/horizonGrid.mjs), the 40-cell bar scales across three zoom levels so both small and huge windows stay easy to read:
100kHaiku Cliff Ceiling (2,500tokens/cell): Used onclaude-haiku-5-5up to100,000input tokens so you can spot the100k5xprice step early.200kStandard Horizon (5,000tokens/cell): Default scale for normal coding chats up to180,000input tokens.1MExtended Context Auto-Zoom (25,000tokens/cell): Switches on automatically whentotal_input_tokens > 180,000on1M-window models likegemini-4-carbon,gemini-4-argon,claude-opus-5-5, andclaude-sonnet-5-5.
Cell Taxonomies by Host
Claude Code reports prompt-cache buckets from Anthropic stats. Google Antigravity tags step-by-step SQLite and JSONL session spans. Both map directly onto the 40-cell bar:
| Host Surface | Code / Category | Glyph | Physical Meaning |
|---|---|---|---|
| Claude Code | [S] System & MCP |
█ (#1A73E8) |
System prompt, CLAUDE.md rules, and eager MCP tool schemas loaded at Turn 0. |
| Claude Code | [C] Warm Cache |
▓ (#81C995) |
Saved history served from Anthropic's warm KV cache at 0.1x read rates. |
| Claude Code | [D] Distractor Debt |
▒ (#F538A0) |
Repeat file reads, untrimmed CLI logs, and fixed errors sitting in the middle of context. |
| Claude Code | [W] Cache Write Delta |
█ (#FA903E) |
New uncached tokens written to the cache at 1.25x (5m) or 2.0x (1h) write rates. |
| Antigravity | ANCHOR_CORE / ANCHOR_SCHEMA |
█ / ▒ |
System prompt, compaction summaries, AGENTS.md, task.md, and Turn-0 tool schemas. |
| Antigravity | MEMORY_KI / MEMORY_BLEED |
▓ |
Current project Knowledge Items versus foreign items pulled in from other workspaces. |
| Antigravity | ACTIVE_SET |
█ |
Clean files and commands from the last ~8 chat turns (16 steps). |
| Antigravity | STALE_DUP / DEAD_ERROR |
▒ / ▓ |
Repeat reads of unchanged files and old command errors already fixed by a later pass. |
| Antigravity | DIRTY_SNAP / LEGACY_POISON |
▒ |
In-chat file copies changed on disk since last read, or paths matching **/legacy/**, **/deprecated/**, or **/v1/**. |
KV-Cache Physics & Break-Even Math (C* & C_max)
Dropping from a large model like claude-opus-5-5 to a smaller model like claude-sonnet-5-5 sounds cheaper for quick edits. When a big prompt cache is warm, that move often costs more. Switching models (or changing reasoning effort while the cache is live) resets the warm KV cache. The new model then pays full cache-write prices for your entire chat history.
Highbeam's Cache Gravity Router (DET-08 in src/core-isomorphic/coach/cacheGravityRouter.mjs) checks both single-turn break-even C* (rule_v1) and multi-turn horizon break-even C_max (rule_v2) before a switch happens:
# Single-turn break-even (rule_v1)
C* = [ O * (P_out,curr - P_out,target) + Delta_uncached * (P_write,curr - P_write,target) ]
/ [ P_write,target - P_read,curr ]
# Horizon-aware break-even over H_post remaining turns and R API requests/turn (rule_v2)
C_max = [ O * (P_out,A - P_out,B) * (H_post + 1) ]
/ [ (P_write,B - P_read,A) - ((H_post + 1) * R - 1) * (P_read,A - P_read,B) ]
O: Expected output tokens per turn. On turns1-4, Empirical Bayes blends live output length towardoutputShrinkagePriorTokens(500tokens;outputShrinkageMinTurns: 5). From turn 5 on, it uses your Stop-hook 10-turn median incal_<sessionId>.json(or1,500if unset).H_post&R: Expected turns left and API calls per turn after switching. Both blend toward local Claude Code history in~/.attention-horizon/cache/ah_session_prior.json(orDEFAULT_RPT_SHRINKAGE_PRIOR = 2.0), capped byturnsUntilCompactand the 496-sessionEMPIRICAL_SESSION_API_CALL_PRIOR.P_out,P_read,P_write: Output, warm cache-read, and cold cache-write (1.25x5m or2.0x1h) prices per million tokens for the current (A) and target (B) models.- Payback & Unbounded
C_max: Highbeam reports exactpaybackWarmRequests,paybackTurns, andhorizonNetSavingsUSD(hiding noisy dollar estimates before Turn 5). If theC_maxbottom term is<= 0, warm-read savings on the cheaper model beat the cold-write hit overH_postturns (C_max = Infinity), so the switch goes right through. Tiny hits belowminSwitchPenaltyUSD($0.02) and unknown non-Anthropic models also pass without blocking.
Worked Engineering Example
Say you are on claude-opus-5-5 with 48,000 warm cached tokens and want to drop to claude-sonnet-5-5 for a quick edit (O = 1,500, Delta_uncached = 0). Single-turn catalog math gives C* = 6,522 tokens (and C* = 4,615 tokens from claude-opus-4-6 to claude-sonnet-4-6). If your chat is almost done (H_post < paybackTurns and 48,000 > C_max), Highbeam holds the switch until the cache cools or asks you to confirm. Moving up to a stronger model always has C* = 0 and is never blocked.
Dual-TTL Countdowns & The Haiku 100k Cliff
Two more cost guards run in the background at all times:
- Dual-TTL Countdown (
dualTtl.mjs): Watches both the 5-minute (300s) prompt-cache timer and the 1-hour (3,600s) billing block. The status bar turns amber at<= 45s, shows a keep-warm tip at<= 15s, saves the State Baton atT-10s, and suggests 1-hour caching if at least3.1%of your breaks last 5 to 60 minutes. - Haiku 100k 5x Cliff Breaker (
DET-12,cliffBreaker.mjs): Guards Haiku chats against the100,000-token5xprice jump. Prompts under90kpass quietly. At90k-98kyou get a soft compact tip,98k-100ktriggers a strong warning, and>= 100kstops the turn before billing spikes. Other models are exempt.
Conductor vs. Executor Division of Labor
Highbeam fits naturally across both Google Antigravity and Claude Code:
- Google Antigravity as Visual Conductor: Great for system planning, live side-panel HUD review (
127.0.0.1:62935), browser checks via/browser, multi-agent work via/swarm, and fast read-only repo lookups with Delegation Scout (@ah-flash-scout, capped under200tokens so your main chat stays lean). - Claude Code as Fast Terminal Executor: Great for terminal TDD loops, Git worktree slices, command-hook guardrails, and live one-line
ah-statuslinetracking in tmux or IDE terminals.
Both hosts share the same repo lock and log files. First, .agents/locks/active_scopes.json stops two agents from editing the same file at once (DET-20). Second, USTF v1 (~/.ctxtop/sessions/) stores logs from both tools in one format for highbeam inspect and highbeam postmortem.
Flight Modes & Enforcement Levels
Highbeam separates tracking from blocking with a Three-Layer Control Stack. Per-detector rules (default, off, warn, block) in .attention-horizon.json come first. Top-level Flight Modes (OFF, SILENT, COACH, AUTO_PILOT) sit next, alongside Antigravity's router hook_level (guard, advisory, off) in default_flightcheck.json.
| Mode / Level | Surface | Runtime Behavior |
|---|---|---|
OFF |
Claude Code & Isomorphic | Mutes habit tips and cache switch holds. Ring-0 safety guards (DET-01, DET-02, DET-18, DET-19) and custom overrides stay on. |
SILENT |
Claude Code & Isomorphic | Tracks live stats, updates ah-statusline, and logs Saved Quota Ledger totals without adding chat coaching notes. |
COACH Default |
Claude Code & Isomorphic | Runs default guard blocks, shows short 1-line tips on advisory rules, and queues warm-cache rule edits in PostCompactMutationQueue. |
AUTO_PILOT Pro |
Isomorphic & in-process module | Turns on HysteresisLock, auto 3rd-read AST stubs and delta-reads, active C* switch holds, and Antigravity guard mode (falls back to COACH without a Pro key). |
guard / advisory / off |
Antigravity hook_level |
Sets whether Antigravity's PreInvocation router stops turns with a 4-line scorecard (guard, with a 3-turn cooldown) or shows soft warnings (advisory). Context Truncation Crisis, DET-08, and DET-12 skip cooldowns. |
Full Enforcement Specification
See Flight Modes & Enforcement Levels → for the priority order chart, HysteresisLock unlock steps, PostCompactMutationQueue rules, one-turn chat prefixes (!, !lock, #check), and CLI overrides.