Getting Started
Guided Step-by-Step Tutorials
Each guide below walks through a real coding workflow from setup to check. Every command runs locally with zero network calls.
Tutorial 1: First Setup, Live HUD & Prompt Precheck
Goal: Set up Highbeam in a repo, preview the status bar, test a vague prompt before spending high-effort tokens, and print a savings receipt.
Set up the project and run health checks
Run the unified installer from your repo root. Then run doctor to make sure all checks pass.
$ npx highbeam-cli init --all-hosts
⚡ Highbeam (highbeam-cli v4.1.4) - Zero-Config Unified Installer
[PASS] Claude Code hooks merged into .claude/settings.json
[PASS] Antigravity workspace plugin verified
$ npx highbeam-cli doctor
[Highbeam Doctor] Status: HEALTHY
Preview the status bar and HTML HUD
Print a sample warm-cache session at 110 columns to test terminal colors. Next, write a local HTML preview panel.
$ npx ah-statusline --demo --columns 110
AH sonnet-5.5 [██▓▓▓▓▓▓▓▓▒█░░░░░░░░] 64.0k/200k (32%) · Cache 87.5% · 5m TTL 04:12 · Saved +$1.84
$ npx highbeam-cli panel --out ./horizon-preview.html
[Highbeam] Claude Code HUD written: /repo/horizon-preview.html
Verdict: NOMINAL (Warm Cache Active)
Next Action: Continue in current cache window
Check a draft prompt with #check or /precheck
In Google Antigravity chat, start a broad prompt with #check to score it before running. Flight Check rewrites the vague prompt to point at exact target files:
# Input in chat:
#check Fix the caching bug in the router
# Expected Scorecard Output:
╭─ Flight Check v3.1 ──────────────────────────────────────────────────────────╮
│ 1. PROMPT : [Score 42/100] Scope: UNANCHORED | Target: (none specified) │
│ 2. HORIZON: [Purity: 88% | Sludge: +$0.01/t | Tokens: 38k/200k | Quota: 91%] │
│ 3. ACTION : /model gemini-4-argon • /effort medium │
│ 4. REWRITE: "Inspect computeBreakEven in @src/core-isomorphic/economics/cacheGravity.mjs and run node --test test/economics_engine.test.mjs" │
╰──────────────────────────────────────────────────────────────────────────────╯
Bypass once: prefix with `!` • Lock model/effort: include `!lock`
Print a Git-ready savings receipt
Print a Markdown receipt ready to paste into pull request notes:
$ npx highbeam-cli receipt --markdown
Tutorial 2: Parallel Delegation on Git Worktrees with Scope Locks
Goal: Run two agents at once across Git worktrees without clobbering files or hitting silent merge clashes, backed by DET-20, DET-31, and Cost Radar.
Create a separate Git worktree for Worker B
When running parallel edits (like Antigravity's workspace: "share" mode), add a branch worktree so each agent builds and tests on its own:
git worktree add ../repo-auth-slice -b feat/auth-slice
git worktree list
Claim a Scope Lock Lease for Worker A
Lock src/core/pro_license.mjs for Worker A (`session-alpha`) via the scope_lock_claim MCP tool (or let PreToolUse claim it automatically). That writes to .agents/locks/active_scopes.json:
$ printf '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"scope_lock_claim","arguments":{"sessionId":"session-alpha","agentId":"claude-code","paths":["src/core/pro_license.mjs"],"ttlSeconds":900}}}\n' | npx highbeam-cli-mcp
Confirm DET-20 blocks clashing edits from Worker B
If Worker B (`session-beta`) tries to edit src/core/pro_license.mjs while `session-alpha` holds the lock, DET-20 stops the write before disk changes happen and prints a `git worktree` tip:
[DET-20 Multi-Agent Scope Collision] Blocked write to src/core/pro_license.mjs:
Active lease held by session "session-alpha" (claude-code, expires in 884s).
Work on disjoint files or isolate via git worktree.
Check worktree layout and merge safety with Cost Radar
While both worktrees run, DET-31 checks git merge-tree in memory to spot overlapping hunks early. Run cost-radar to view the swarm map:
$ npx highbeam-cli cost-radar --out ./swarm-radar.html --json
{
"ok": true,
"path": "/repo/swarm-radar.html",
"retention": "Cache Hit 91.2% (Warm)",
"drift": "Thinking Drift Nominal (loopTriggered=false)",
"swarm": "2 worktrees active (main, repo-auth-slice)"
}
Tutorial 3: Auditing Failed Runs, Stepping Execution & Surgical Pruning
Goal: Pause a stuck test loop, step through one tool call at a time, check recent chats for waste, and trim old tool outputs with a backup.
Pause and single-step a live agent chat
If an agent loops on failing tests (nearing the DET-04 3-strike limit), pause it from a second terminal with highbeam control:
# Suspend at the next PreToolUse boundary (writes ~/.ctxtop/runtime/default.ctl)
$ npx highbeam-cli control pause --session default
[Highbeam Control] State transitioned to PAUSED
# Allow exactly 1 tool call, then automatically return to PAUSED
$ npx highbeam-cli control step --session default
[Highbeam Control] State transitioned to STEP
# Resume normal execution once verified
$ npx highbeam-cli control resume --session default
[Highbeam Control] State transitioned to RUNNING
Check USTF v1 spans and run a Postmortem
View your latest call tree and scan your last 10 chats for CONTEXT_ROT_DECAY or VERIFICATION_CHURN:
$ npx highbeam-cli inspect --last
[Highbeam Inspect] Session "default" (claude-code)
Model: claude-sonnet-5-5 | Events: 24 | Spans: 11
Tokens: 92,400 (Uncached: 11,200, Cache: 81,200)
$ npx highbeam-cli postmortem --last 10
[Highbeam Postmortem] Analyzed 10 sessions (1.42M active tokens)
Clean Sessions: 7 | Churn: 2 | Rot: 1
Report: session_analysis_report.md
Preview and run offline Tool-Output Pruning
Run --prune-tools --dry-run first to see how many old uncached tool outputs can be trimmed. Then drop --dry-run to write a .bak backup and trim them:
$ npx highbeam-cli doctor --prune-tools --dry-run
✔ PASS Uncached Tail Surgeon Pruned 6 stale tool output(s), saved ~28400 tokens (dry-run)
$ npx highbeam-cli doctor --prune-tools
✔ PASS Uncached Tail Surgeon Pruned 6 stale tool output(s), saved ~28400 tokens
Tutorial 4: Zero-Loss Compaction & Cross-Model Spec Relay
Goal: Pack a deep 135k-token chat into a clean State Baton without wasting a warm cache, and build a short Cold Critic Packet for spec reviews.
Check your cache timer before compacting
Running /compact while 50k+ tokens are still warm inside a 5-minute window throws away cheap cache reads (HOLD_COMPACT). Check your timer first:
$ npx highbeam-cli receipt --simple
Build and check the State Baton (/handoff)
Run /handoff in chat or build the file from the CLI. Make sure all five items are set: a clear Next Action verb + file path, touched files, open Blockers, key Decisions, and a clean git status --porcelain:
$ npx highbeam-cli doctor --handoff
✔ PASS Handoff Distillation Generated handoff document at docs/HANDOFF_2026-11-12.md
Run /compact and flush TurnZeroGate
Wait until the cache timer hits 00:00 (or compact right away if you hit amputation_token_threshold). Copy the /compact command from #btnCompactPrimary in the HUD and run it in chat. Any rule edits held in PrefixCacheShield or TurnZeroGate write out cleanly during PostCompact with zero extra cache cost.
Sort multi-model spec reviews with /relay
When checking a spec with a second model, run /relay. It sorts outside notes into S0 (Blocker), S1 (Major Flaw), T (Testable Question checked by a <30-line local script), and Defer. Accepted fixes go straight into the spec file on disk instead of pasting huge replies in chat.