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:

  1. 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.
  2. 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).
  3. Cold Cache Rebuilds: Switching models mid-chat or editing AGENTS.md or CLAUDE.md while a prompt cache is warm breaks the cache prefix. Your next turn pays full 1.25x cache-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.

Parabolic U-Shaped Attention Recall Across 40 Context Cells 100% 60% 25% Primacy (0–30%, Anchors 1–6) Middle Trough / Distractor Zone (30–70%, Cells 7–28) Recency Tail (70–100%, Cells 29–40) Cell 1 (Turn 0 System + Rules) Stale Reads & Resolved Errors Cell 40 (Active Ceiling)
Core rules belong at the top (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:

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 (C*) & Horizon-Aware Break-Even (C_max)
# 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) ]

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:

Conductor vs. Executor Division of Labor

Highbeam fits naturally across both Google Antigravity and Claude Code:

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.