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.
{
"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).
- Limits:
MAX_BUFFER_SIZE_BYTES = 10,485,760(10 MB),DEFAULT_CONNECT_TIMEOUT_MS = 15,DEFAULT_REQUEST_TIMEOUT_MS = 500(raised to600,000mswhile a session isPAUSED). - Fail-Safe Fallback: If no warm daemon replies within
15ms, the hook runsCircuitBreakerEngineand checks.ctlfiles directly in process with zero errors. - Standard JSON-RPC 2.0 Error Codes:
-32700(PARSE_ERROR),-32600(INVALID_REQUEST),-32601(METHOD_NOT_FOUND),-32602(INVALID_PARAMS), and-32603(INTERNAL_ERROR).