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

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 and Run Unified Installer
# 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:

Google Antigravity Setup Options
# 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:

Claude Code Project vs. Global Installation
# 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:

Register @ctxtop/mcp in .cursor/mcp.json
# 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):

Verify Contracts & Release Checksums
$ 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:

Clean Uninstallation

Remove Hooks and Optional Local Caches
# 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