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.

Step 1 · Input & Expected Output
$ 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.

Step 2 · StatusLine & Panel Generation
$ 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:

Step 3 · Flight Check 4-Line Scorecard Output
# 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:

Step 4 · Verify Receipt
$ 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:

Step 1 · Create Feature Worktree
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:

Step 2 · Claim Lease via @ctxtop/mcp JSON-RPC
$ 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:

Step 3 · Expected PreToolUse Collision Block
[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:

Step 4 · Generate Swarm & Worktree Timeline
$ 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:

Step 1 · Pause, Step Once, and Resume
# 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:

Step 2 · Trajectory Inspection & Postmortem
$ 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:

Step 3 · Dry-Run & Live Surgical Prune
$ 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:

Step 1 · Inspect TTL & Saved Quota
$ 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:

Step 2 · Distill Handoff Document
$ 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.