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.
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 andah-statuslineintosettings.json.--mcp/--cursor/--windsurf: Adds theattention-horizonstdio server to.cursor/mcp.json(or~/.cursor/mcp.jsonwith--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.
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.
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: Outputschecks,claudeCapabilities(PreModelSwitch,PostModelSwitch,supportsAskDecision,PreEffortChange),hookDiagnostics, andmodelSwitchTelemetry.--prune-tools/--uncached-tail(alsoagy-horizon prune): Runs the Tool-Output Surgeon on the active JSONL log (or--transcript <path>). Saves a.bakbackup 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 indocs/.--recover-brain: Re-links Antigravity session folders after a profile move.--gc-cursor --vscdb <path>: Shrinks large Cursorstate.vscdbSQLite 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.
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.
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.
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.
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.
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.
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.
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:
# 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).
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.
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.
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:
src/shims/agy_cli_compressor.mjs: Strips ANSI escape codes and saves long command output to SQLite FTS5 usingAGY_CONVERSATION_ID.src/shims/agy_git_guard.mjs: Checks git and shell flags before execution to backDET-01.src/shims/ah_log_query.mjs: Fast FTS5 reader that searches saved log lines in.ctxtop/cache/artifacts_fts5.db.
| 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. |