Reference

CLI & Binaries Reference

Highbeam ships 12 CLI commands and 3 shell shims across four runtime targets. Every subcommand below matches the flags in bin/ctxtop.mjs, bin/ah-statusline.mjs, and src/cli/*.mjs.

Package Binaries & Entrypoints

Binary Name(s) Target Script Primary Purpose
highbeam, highbeam-cli, ctxtop, ah, attention-horizon, ah-claude, attention-horizon-claude ./bin/ctxtop.mjs Main CLI router. Handles setup, receipts, Cost Radar, settings, session control, log checks, and Pro keys.
ah-statusline ./bin/ah-statusline.mjs Claude Code statusLine stdin bridge. Draws 80, 110, or 144-column ANSI status bars.
attention-horizon-antigravity, ah-antigravity, agy-horizon, agy-horizon-flightcheck ./src/cli/init.mjs Antigravity CLI launcher. Runs the local WebView server (--serve), live terminal demos (--demo-animate), FTS5 shell wrapper (exec), and log search (log-search).
highbeam-mcp, ah-mcp, ctxtop-mcp ./packages/mcp/src/server.mjs Zero-dependency MCP JSON-RPC 2.0 stdio server for Cursor, Windsurf, Claude Code, and Antigravity.

Complete Subcommand Reference

highbeam init

Safely installs Highbeam across one or more host tools without overwriting your existing hooks.

Synopsis
highbeam init [--antigravity] [--claude] [--mcp | --cursor | --windsurf] [--all]
            [--global | -g | --workspace | --project]
            [--lean-hooks | --full-hooks] [--dry-run] [--dedupe] [--json]
  • --antigravity: Installs Google Antigravity plugin files, rules, skills, and sidecar hooks.
  • --claude: Merges Claude Code hooks and ah-statusline into settings.json.
  • --mcp / --cursor / --windsurf: Adds the attention-horizon stdio server to .cursor/mcp.json (or ~/.cursor/mcp.json with --global).
  • --all / -a: Sets up every host tool found on your machine in one pass.
  • --lean-hooks (default) vs. --full-hooks: Installs fast core hooks only, or enables every lifecycle hook.
  • --dry-run: Prints target paths and planned edits without writing to disk.
  • --dedupe: Cleans up duplicate Highbeam hooks from older installs while leaving your custom hooks alone.

highbeam install & highbeam uninstall

Adds or removes Highbeam in Claude Code settings.json and saves a timestamped backup first. It checks your Claude binary with inspectClaudeBinaryCapabilities(). If your CLI build lacks newer hooks like PostModelSwitch, it skips them and lists them in omittedUnsupportedHooks.

Synopsis
highbeam install [--global | -g | --project] [--lean-hooks | --full-hooks] [--json]
highbeam uninstall [--global | -g | --project] [--json]

Defaults to --project (<cwd>/.claude/settings.json) when you omit --global. uninstall leaves backups and local data in place and lists them under “Not removed”: settings.json.ah-backup.*, .claude/cache/artifacts, ~/.ctxtop (including the stable runtime copy in ~/.ctxtop/app), and Antigravity plugin folders. Delete them by hand if you want a clean slate.

highbeam doctor & highbeam prune

Checks host setup, Claude hook support (claudeCapabilities), privacy-safe switch stats (modelSwitchTelemetry), model lists, and hook error logs. It can also prune old tool logs and clean up disk bloat offline.

Synopsis
highbeam doctor [--diagnostic | --bug-report] [--json]
              [--prune-tools | --prune | --uncached-tail | --tail]
              [--transcript <path>] [--reap-orphans] [--handoff | --distill]
              [--storage-gc | --gc-cursor | --recover-brain] [--vscdb <path>] [--dry-run]
  • --diagnostic / --bug-report: Prints a Markdown (or --json) report with home folder paths stripped out.
  • --json: Outputs checks, claudeCapabilities (PreModelSwitch, PostModelSwitch, supportsAskDecision, PreEffortChange), hookDiagnostics, and modelSwitchTelemetry.
  • --prune-tools / --uncached-tail (also agy-horizon prune): Runs the Tool-Output Surgeon on the active JSONL log (or --transcript <path>). Saves a .bak backup first, then trims old uncached tool outputs.
  • --reap-orphans: Finds and stops stray language-server or test child processes.
  • --handoff / --distill: Writes a timestamped handoff Markdown file in docs/.
  • --recover-brain: Re-links Antigravity session folders after a profile move.
  • --gc-cursor --vscdb <path>: Shrinks large Cursor state.vscdb SQLite files by dropping orphan rows.
  • --dry-run: Previews log pruning or SQLite cleanup without changing any files.

highbeam verify (alias: verify-checksums)

Checks SHA-256 hashes (with normalized line endings) for every release file in CHECKSUMS.sha256. Exits 0 when all files match.

Synopsis
highbeam verify [--json]

highbeam receipt

Prints your estimated Tokens & USD Saved receipt as terminal text, Git Markdown, HTML, JSON, or a Pro SHA-256 PDF 1.4 file.

Synopsis
highbeam receipt [--simple | --4-rank | --advanced]
               [--markdown | --md | --git | --html | --pdf | --json]
               [--out <path>]

Note: Running --pdf on the Free tier exits with code 2. It shows your 30-day USD savings and explains how to start a local trial (highbeam license trial).

highbeam panel

Writes a standalone, offline Claude Code HTML panel snapshot. Saves to ~/.claude/attention-horizon/horizon_panel.html by default.

Synopsis
highbeam panel [--advanced] [--out <file.html>] [--json]

highbeam cost-radar (alias: radar)

Writes a script-free HTML/SVG timeline of turn-by-turn cache hits, thinking-token spikes, and Git worktree branches. Saves to ~/.claude/attention-horizon/cost_radar.html by default.

Synopsis
highbeam cost-radar [--out <file.html>] [--demo] [--share] [--json]

highbeam statusline & ah-statusline

Reads Claude Code's statusLine JSON from stdin (up to 1,500ms). Updates .claude/cache/ah_live_state_<sessionId>.json and prints a one-line ANSI bar.

Synopsis
ah-statusline [--demo] [--columns <N> | --cols <N>]

highbeam postmortem & highbeam roast

Scans recent local sessions and groups failures into clear types (CONTEXT_ROT_DECAY, VERIFICATION_CHURN, SPEC_AMBIGUITY, or CLEAN). It flags repeated file reads, checks Turn-0 MCP bloat, and prints an ASCII or Markdown summary.

Synopsis
highbeam postmortem [--last <N>] [--roast] [--demo] [--json]
highbeam roast [--demo] [--markdown | --md] [--json]

--last checks 15 sessions by default. Writes session_analysis_report.md and conversation_diagnostics.jsonl when writeFiles is on.

highbeam inspect

Converts any Claude Code snapshot, USTF v1 log, or Antigravity brain folder into a standard USTF v1 trace. Reports event counts, call trees, cached vs. uncached tokens, and USD cost.

Synopsis
highbeam inspect [<session-id> | --session <id> | --last] [--out <file.json>] [--json]

Antigravity Server, Demos & FTS5 Execution Wrappers

Run through agy-horizon (src/cli/init.mjs) or src/cli/horizon_hud.mjs:

Synopsis
# Start loopback HTTP/SSE daemon on 127.0.0.1:62935..62945
agy-horizon ui [--open | --no-open] [--demo]
highbeam --serve

# Run 5-stage synthetic terminal crisis showcase or emit Studio HTML widget
agy-horizon demo [--demo-animate] [--scenario <1..5>] [--harness <antigravity|claude-code>]
node src/cli/horizon_hud.mjs --emit-widget

# Execute a verbose shell command through the lossless FTS5 compressor (>4,096 chars archived)
agy-horizon exec <command...>

# Query archived FTS5 CLI logs by keyword across turns
agy-horizon log-search "<fts5-query>"

highbeam config

Lists, sets, or resets detector rules in .attention-horizon.json (project default) or ~/.attention-horizon/config.json (--global).

Synopsis
highbeam config [list] [--global | -g] [--json]
highbeam config set <DET-01..DET-20 | habit-slug> <default | off | warn | block> [--global | -g]
highbeam config reset [--global | -g]

highbeam control

Updates the 5-state session control file at ~/.ctxtop/runtime/<sessionId>.ctl and notifies any running Micro-IPC daemon via control.transition.

Synopsis
highbeam control <status | pause | resume | step | abort | rewind>
               [--session <id>] [--target <turn> | --turn <turn>]

Note: abort moves the session to the final ABORTED state. You must start a new session or delete the .ctl file to run tools again.

highbeam license (pro), tiers & team-pack

Manages offline Ed25519 Pro keys, 14-day local trials, and Grafana or Datadog OpenTelemetry packs.

Synopsis
highbeam tiers [--json]
highbeam license [status | tiers | trial | activate <ed25519-token> | deactivate] [--json]
highbeam mode [coach | auto | silent | off] [--project] [--json]
highbeam team-pack [--out <dir>] [--org "<Org Name>"] [--preview] [--json]

Execution Shims & Standard Exit Codes

Three standalone scripts in src/shims/ plug directly into shell workflows:

Exit Code Meaning Across CLI & Hook Binaries
0 Command succeeded, checksum or doctor checks passed, or a hook wrote a valid JSON decision (allow, deny, or ask) to stdout.
1 Bad CLI flag, missing target session, checksum mismatch, or failed doctor check.
2 Hard block in a Claude Code Tier-2 hook (message sent to stderr, empty stdout). Also returned when Free tier runs highbeam receipt --pdf or highbeam team-pack without --preview.