Getting Started
Installation, Verification & Migration
Highbeam installs cleanly without touching your source code, adding npm dependencies, or asking for API keys. Every config update saves a local backup before writing.
Prerequisites & Runtime Requirements
- Node.js
>= 22.13.0: Needed on your systemPATHso host hooks can runnodedirectly. Check withnode --version. - SQLite, FTS5 Polyfill & Fallback: On the supported Node versions (
22.13+, with built-innode:sqlite),@ctxtop/engine-nodeopens session databases withSQLITE_OPEN_READONLYand enables local FTS5 log search. If a Node 22 build lacksSQLITE_ENABLE_FTS5,src/engine-node/db/probe.mjssupplies a drop-inUSING fts5(...)table andMATCHsnippet polyfill. Whennode:sqliteis absent (orCTXTOP_FORCE_NO_SQLITE=1is set), Highbeam falls back to read-only JSONL byte-offset reads. - Git (Optional, Recommended): Powers
DET-01git safety checks,DET-03lockfile drift checks,DET-31worktreegit merge-treeconflict checks, and Cost Radar worktree maps.
Clean Installation Across Surfaces
Run --dry-run first if you maintain custom hooks in settings.json or hooks.json.
1. Unified Dual-Host Installation
Use highbeam init --all-hosts to configure Google Antigravity, Claude Code, and supported MCP hosts (Cursor, Windsurf, Codex CLI, Gemini CLI) in one pass:
# Preview planned file paths without writing
npx highbeam-cli init --all-hosts --dry-run
# Perform non-destructive multi-host installation
npx highbeam-cli init --all-hosts
2. Google Antigravity Installation
Install Highbeam for one workspace (.agents/plugins/) or globally across all projects (~/.gemini/config/plugins/). You can also clone the repo for local work:
# Option A: Workspace plugin installation
npx highbeam-cli init --workspace
# Option B: Global user installation via highbeam-cli
npx highbeam-cli init --antigravity --global
# Option C: Local source checkout & 3-way mirror sync
git clone https://github.com/Gizzant/context-horizon.git
cd context-horizon
node scripts/sync_mirrors.mjs
node bin/ctxtop.mjs verify --json
3. Claude Code Installation (Lean vs. Full Hooks)
For Claude Code, npx highbeam-cli init --claude (project) or --global (all projects) merges hooks and the ah-statusline bar into .claude/settings.json (project scope) or ~/.claude/settings.json (--global). Your existing custom hooks stay untouched:
# Recommended: Lean hook profile in global ~/.claude/settings.json
npx highbeam-cli init --claude --global --lean-hooks
# Project-local full hook profile (.claude/settings.json)
npx ah-claude install --project --full-hooks
You can also load the plugin folder directly via .claude-plugin/plugin.json. That adds all six slash commands (/horizon, /cost-radar, /inspect, /handoff, /precheck, /evolve) and wires up hooks/hooks.json. During highbeam install or highbeam init --claude, inspectClaudeBinaryCapabilities() scans your Claude Code binary. It skips newer hooks like PostModelSwitch (omittedUnsupportedHooks) on older CLI builds so settings never break.
4. Cursor & Windsurf MCP Registration
Add @ctxtop/mcp to use Highbeam stats, C* switch checks, and multi-agent Scope Lock Leases in Cursor or Windsurf:
# Project-scoped .cursor/mcp.json
npx highbeam-cli init --mcp
# Global ~/.cursor/mcp.json
npx highbeam-cli init --mcp --global
Authentication & OAuth Seat Safety
Highbeam needs zero cloud login or API keys. It never asks for Anthropic, Google Cloud, or OpenAI keys because every rule and score runs locally in JavaScript.
Account & OAuth Seat Safety Protocol
Highbeam enforces three strict rules across its runtime and tests to prevent automated account lockouts. First, it never reads ~/.gemini/oauth_creds.json or Windows Credential Manager gemini:antigravity secrets (enforced by DET-02). Second, its tests never launch headless gemini or agy CLIs with "selectedAuthType": "oauth-personal". Third, its coaching rules steer agents to batch searches and edits into 1-2 tool calls per turn instead of parallel subagent bursts.
Verification & Health Diagnostics
After setup, run highbeam doctor and highbeam verify. They check every manifest, hook contract, Claude binary flag, model rate card, and file checksum. Pass --json to view full claudeCapabilities and scrubbed modelSwitchTelemetry (using one-way SHA-256 sess_<12hex> session hashes):
$ npx highbeam-cli doctor
[Highbeam Doctor] Status: HEALTHY
[PASS] node_version: Node.js v22.14.0 (requires >= 22.13.0)
[PASS] model_catalog: Loaded 28 Anthropic model rate cards (Haiku 5.5 100k cliff enabled)
[PASS] mod_entrypoint: hooks/register.js present at .../hooks/register.js
[PASS] hooks_manifest: hooks/hooks.json valid (nested hooks schema)
[PASS] plugin_manifest: .claude-plugin/plugin.json valid
[PASS] settings_status: Installed in ~/.claude/settings.json
[PASS] horizon_config: 20 Claude Code detector toggles configured (of 32 total; FlightMode=COACH, overrides=0)
[PASS] claude_pre_model_switch: Claude Code 2.1.x | PreModelSwitch=true | ask=true | PreEffortChange=false
[PASS] hook_diagnostics: 0 recent non-fatal error(s)
$ npx highbeam-cli verify
[Highbeam Verify] PASS - 148 release files verified against CHECKSUMS.sha256 (0 mismatches)
Need to file a bug report without sharing file paths, usernames, or prompts? Run npx highbeam-cli doctor --diagnostic to create a scrubbed report.
Safe Deduplication, Migration & Uninstallation
Upgrading from v3.x (`ga-visualizer` / `agy-horizon` IDs) or moving from project hooks to global hooks takes two quick steps:
- Legacy Config Migration:
migrateLegacyHorizonConfigmaps old v3 rule names to v4.0DET-01..DET-32IDs automatically. - Hook Deduplication: Run
npx highbeam-cli init --claude --dedupeto clean out duplicate or old Highbeam entries fromsettings.json. Your other third-party hooks stay intact. - Orphaned Antigravity Brain Recovery: After an Antigravity IDE profile move, run
npx highbeam-cli doctor --recover-brain --dry-runfirst. Then run it without--dry-runto relink orphaned brain folders.
Clean Uninstallation
# 1. Remove Highbeam hooks & statusLine from Claude Code settings
npx highbeam-cli uninstall --global
npx highbeam-cli uninstall --project
# 2. Optional: remove local telemetry caches and runtime control latches
rm -rf ~/.ctxtop ~/.attention-horizon .claude/cache/ah_live_state_*.json .attention-horizon.json