Reference

MCP Server, HTTP Daemon & Micro-IPC API

Highbeam exposes three local-only APIs: a zero-dependency MCP stdio server for external AI editors, a local HTTP/SSE server for the WebView panel, and a fast Micro-IPC socket (<15ms) for warm hook calls.

1. MCP Stdio Server (@ctxtop/mcp)

Built in packages/mcp/src/server.mjs (commands highbeam-mcp, ah-mcp, and ctxtop-mcp, protocol 2024-11-05). The server reads both newline-delimited JSON-RPC 2.0 lines and LSP-style Content-Length: <bytes>\r\n\r\n frames over stdin and stdout.

.cursor/mcp.json Registration
{
  "mcpServers": {
    "attention-horizon": {
      "command": "npx",
      "args": ["-y", "highbeam-cli", "mcp"]
    }
  }
}

Exposed MCP Tools

Tool Name Input Parameters Response Payload
horizon_status cwd?: string, sessionId?: string (default "default") Returns { ok, cwd, sessionId, entitlement: { entitled, tier, source }, savedQuota, liveState } from local snapshots.
cache_gravity_check currentModel: string (req), targetModel: string (req), cachedTokens?: number, ttlRemainingSeconds?: number (240), remainingExpectedTurns?: number (1), expectedOutputTokens?: number (1500) Calculates the C* break-even token threshold. Tells the caller whether to stay on the warm model or switch now.
scope_lock_claim workspaceDir?: string, sessionId?: string, agentId?: string, paths?: string[], ttlSeconds?: number (900) Lists active file locks when paths is empty. Otherwise claims paths or reports lock conflicts in .agents/locks/active_scopes.json.
export_receipt_pdf cwd?: string, sessionId?: string, email?: string, outPath?: string, allowPreview?: boolean (false) Builds a SHA-256 verified PDF 1.4 expense receipt from your 30-day Saved Quota Ledger.
horizon_compress_cli rawOutput: string (req), command?: string, exitCode?: number (0), sessionId?: string, turnId?: string, forceCompress?: boolean (false), homeDir?: string, dbPath?: string Compresses verbose test, lint/build, git diff, or infra CLI outputs into <=25-line diagnostics while archiving raw text in local SQLite FTS5.
horizon_search_logs turnId?: string, keyword?: string, cwd?: string, homeDir?: string, dbPath?: string, limit?: number (10) Searches local FTS5-archived CLI tool logs and offloaded artifacts by keyword or turnId (read-only).
horizon_audit_sessions platform?: string (all|antigravity|claude|codex|gemini|cursor), days?: number (7), limit?: number (10), cwd?: string Runs a strictly read-only 5-host Sludge Tax & ROI audit across Antigravity, Claude Code, Codex CLI, Gemini CLI, and Cursor transcripts.

2. Loopback HTTP & SSE Daemon API

sidecars/horizon-daemon/server.mjs binds only to 127.0.0.1 on port 62935 (trying up to 62945 if busy). It rejects POST bodies over 4,096 bytes with HTTP 400 or 413.

Telemetry, Streaming & Export Routes (GET)

Method & Path Description
GET /, /index.html, /widget, /widget.html Serves the Highbeam WebView HTML panel.
GET /preload.js Serves the local sidecar WebView bridge script.
GET /api/health Returns daemon status, PID, active port, and schema version.
GET /api/state Returns the 40-cell memory grid, U-curve recall scores, active alerts, and token stats.
GET /api/stream Server-Sent Events (text/event-stream) stream that pushes live updates when logs change.
GET /api/cost-radar Returns live Cost Radar SVG charts plus cache, thinking-drift, and worktree stats.
GET /api/settings Reads saved window settings (safeLimitTokens, reminderAtPct, modelOverrides).
GET /api/memory/resume Searches SQLite FTS5 past-session memory to build a resume summary.
GET /api/receipt/export Exports savings receipts in PDF 1.4 (?format=pdf), HTML, or Markdown.

Hygiene, Rule Fencing & Router Action Routes (POST)

Method & Path Description
POST /api/settings Checks, clamps, and saves updated context window settings.
POST /api/prune & POST /api/surgeon Prunes stale context or runs the offline Tool-Output Surgeon after saving a .bak backup.
POST /api/tail/trim Scans read-only transcripts, stages uncached tail trims, and logs token savings.
POST /api/handoff & /api/handoff/generate Writes a verified handoff Markdown file to docs/HANDOFF_<timestamp>.md.
POST /api/rules/promote Moves key rules to the start or end of context. Waits if the prefix cache is still warm.
POST /api/rules/u-curve-optimize & /api/ushape/reorder Reorders rule blocks so top rules sit at the start and end where models recall them best.
POST /api/shield/flush Writes queued PrefixCacheShield rule edits to disk. Holds while cache is warm unless force: true.
POST /api/rsi/evolve, /api/instincts/promote, /api/rsi/queue-action Drafts domain skills, promotes tested habits, or approves and dismisses items in ReflectorQueue.
POST /api/router/mode, /api/router/actuate, /api/router/unlock-hysteresis Switches Flight Mode (COACH or AUTO_PILOT), applies model tips, or clears the switch cooldown lock.
POST /api/host/reap, /api/open-brain, /api/hooks/dampen Stops stray child processes, opens the session folder (skipped if HORIZON_TEST_NO_SPAWN=1), or installs hook dampers.
POST /api/checkpoint/evaporation-check, /api/export/sanitized, /api/savings/receipt, /api/license/activate, /api/action Checks rule survival after compaction, exports redacted logs, builds plain-English receipts, activates Pro keys, or runs UI actions.

3. Micro-IPC Socket Protocol (@ctxtop/engine-node)

Built in src/engine-node/ipc/protocol.mjs, client.mjs, and server.mjs. Micro-IPC lets short-lived CLI hooks hand checks off to a warm local daemon over a Unix socket (macOS/Linux) or Named Pipe (Windows, custom path via CTXTOP_IPC_PATH).