Integration model
Beacon supports multiple runtime surfaces because each agent harness exposes telemetry differently. Supported harnesses use local OpenTelemetry configuration, admin- or gateway-configured OTLP export, hook adapters, or a combination of those paths.Discovery and status
beacon endpoint discover checks which supported agent harnesses are present and whether their telemetry is configured.
| Runtime | How Beacon discovers or validates it |
|---|---|
| Claude Code | Looks for the claude executable and Claude settings paths |
| Codex CLI | Looks for the codex executable and ~/.codex/config.toml |
| Gemini CLI | Looks for the gemini executable and ~/.gemini/settings.json |
| GitHub Copilot CLI | Looks for the copilot executable or ~/.copilot/config.json, then validates Copilot OTel environment variables |
| VS Code | Looks for the code executable or VS Code user settings, then validates Copilot Chat OTel settings |
| Grok Build | Checks for Beacon’s managed Grok hook file at ~/.grok/hooks/beacon-endpoint.json or ./.grok/hooks/beacon-endpoint.json |
| OpenCode | Looks for the opencode executable or ~/.config/opencode, then checks the managed Beacon plugin |
| Cline | Looks for ~/.cline, treating a cline executable as an extra signal because the VS Code and JetBrains hosts ship none, then checks the managed Beacon plugin |
| Pi | Looks for the pi executable, treating ~/.pi/agent as an extra signal because an npm or version-manager install is often off the inherited PATH, then checks for Beacon’s managed extension at ~/.pi/agent/extensions/beacon.ts |
| Oh My Pi | Looks for the omp executable, treating the resolved agent directory as an extra signal for the same reason as Pi, then checks for Beacon’s managed extension at ~/.omp/agent/extensions/beacon.ts |
| fx (Vercel Labs) | Looks for the fx executable, treating ~/.fx as an extra signal, then reports how much of the session store under ~/.fx/sessions a sweep has actually collected. There is no managed file to check, so collection progress is the only honest evidence telemetry is flowing |
| Muse Code | Checks Muse’s config directory ($XDG_CONFIG_HOME/muse, else ~/.config/muse) for Beacon’s managed hooks file and for the managed_hooks_path key in Muse’s own settings.json. Both are reported, because either one alone is a broken install that Muse says nothing about |
| goose | Looks for the goose executable, treating goose’s own config.yaml as an extra signal because the desktop app installs no binary on the inherited PATH, then checks both the plugin directory ($GOOSE_PATH_ROOT, else ~/.agents/plugins/beacon-endpoint/, and <repo>/.agents/plugins/beacon-endpoint/) and config.yaml for the OTLP endpoint. Both are reported because they are two different collection paths, and one installed without the other is half an integration |
| Kiro | Checks <repo>/.kiro/hooks/beacon-endpoint.json and the user-level file ($KIRO_HOME, else ~/.kiro) for Beacon’s hook commands. Both scopes are reported because Kiro merges hook files across scopes rather than resolving them by precedence, so both can be live at once |
| OpenHands | Checks <repo>/.openhands/hooks.json and the user-level file ($OH_PERSISTENCE_DIR, else ~/.openhands) for Beacon’s hook commands. Both scopes are reported, because OpenHands reads the first file it finds rather than merging them, so a repository file shadows the user one entirely |
| Qwen Code | Looks for the qwen executable, treating ~/.qwen as an extra signal because an npm or version-manager install is often off the inherited PATH, then checks ~/.qwen/settings.json for Beacon’s --platform qwen hook entries |
| Devin CLI | Looks for the devin executable, ~/.config/devin, or ./.devin, then checks Beacon hook configuration |
| Devin Desktop | Checks Cascade/Windsurf hook configuration at ~/.codeium/windsurf/hooks.json or ./.windsurf/hooks.json |
| Factory Droid | Looks for the droid executable and validates OTEL_TELEMETRY_ENDPOINT in the effective launch environment |
| Cursor | Looks for the Cursor binary or ~/.cursor, then checks Beacon hook configuration |
| Claude Cowork | Treats it as an admin-configured OTLP source because telemetry is enabled in Claude organization settings |
| OpenClaw Gateway | Validates observed OpenClaw-derived events in the runtime log after Gateway diagnostics are configured |
Install-time configuration
During install, Beacon configures the runtime surfaces it can safely manage:| Runtime or surface | Install-time behavior |
|---|---|
| Claude Code | Beacon points Claude Code at the local OTLP collector. Hook installation is separate through beacon endpoint hooks. |
| Codex CLI | Beacon points Codex CLI at the local OTLP collector, writes log and trace exporter tables to ~/.codex/config.toml, enables prompt logging, retains one usage-bearing turn span, and installs a metadata-only SessionStart identity hook. |
| Gemini CLI | Optional with --harness gemini. Beacon writes local OTLP settings to ~/.gemini/settings.json, sets target to local, uses OTLP gRPC, enables the collector, and removes outfile so telemetry flows to Beacon. |
| VS Code | Optional with --harness vscode. Beacon writes Copilot Chat OTel settings to VS Code user settings and points OTLP/HTTP to the local collector. |
| GitHub Copilot CLI | Copilot’s OTLP HTTP endpoint remains under MDM or customer-owned launch-environment policy. Beacon validates COPILOT_OTEL_ENABLED=true and a localhost OTLP endpoint but does not write Copilot configuration. |
| Factory Droid | Droid’s OTLP endpoint remains under its launch environment, commonly managed through MDM or another customer-owned policy. |
| OpenClaw Gateway | Configure OpenClaw with the diagnostics-otel plugin. Beacon prints local OTLP/HTTP setup guidance and validates observed events. |
| fx (Vercel Labs) | Nothing is installed or configured. fx has no hook file, plugin directory, or OTLP endpoint, so collection is an action: run or schedule beacon endpoint fx sync. |
| Hook-based runtimes | Antigravity CLI, Claude Code, Cline, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, goose, Hermes Agent, Kiro, Muse Code, Oh My Pi, OpenCode, OpenHands, Pi, and Qwen Code hooks and managed plugins are installed separately with beacon endpoint hooks, because hooks are per-user or per-project runtime configuration rather than base collector service configuration. |
Integration paths
| Runtime | Collection path | Notes |
|---|---|---|
| Claude Code | Local OTLP export plus optional hooks | Uses Claude settings to enable telemetry and point OTLP to localhost; Beacon decodes nested tool operands and separates API/session lifecycle from tool execution, while optional hooks add lifecycle, subagent, permission, and tool detail. |
| Codex CLI | Local OTLP logs and selective turn traces plus a SessionStart hook | Beacon writes structured Codex OTLP config, filters noisy internal spans, and joins OS-user context to per-turn usage. |
| Gemini CLI | Opt-in local OTLP logs, traces, and metrics | Beacon writes Gemini telemetry settings and maps Gemini prompts, tool calls, MCP activity, file operations, and approval events into endpoint events. |
| GitHub Copilot CLI | MDM-managed OTLP HTTP export | Beacon validates Copilot’s effective launch environment and maps Copilot spans into prompt, session, tool, and approval-like endpoint events. |
| VS Code | Copilot Chat OTel plus optional preview hooks | Beacon writes VS Code Copilot OTel settings and maps Copilot prompts, sessions, model metadata, and tool activity into endpoint events. Hooks are optional for extra lifecycle and cross-agent detail. |
| Antigravity CLI | Native hook payloads through beacon-hooks | Beacon writes a managed Antigravity hook block and maps prompt, pre-tool, post-tool, invocation, command, file edit, and diff telemetry into endpoint events. |
| Grok Build | Native hook payloads through beacon-hooks | Beacon writes an owned Grok hook file and maps session, prompt, tool, command, file, and failed-tool events into endpoint events. |
| Hermes Agent | Shell hook payloads through beacon-hooks | Beacon merges user-level Hermes shell hooks and maps prompts, tools, commands, approvals, session lifecycle, and subagent stop metadata into endpoint events. |
| OpenCode | Managed local plugin through beacon-hooks | Plugin invokes Beacon for chat, session, command, permission, diff, and error events where payloads are available. |
| Cline | Managed local plugin through beacon-hooks | One plugin covers the VS Code, JetBrains, and CLI hosts; it forwards run and tool hooks for prompt, task lifecycle, tool, command, file, MCP, and token telemetry. |
| Pi | Managed local extension through beacon-hooks | Pi has no hooks file and no OTLP export, so the TypeScript extension API is the only observation surface. Beacon’s managed extension subscribes to seven Pi event types and forwards session, prompt, tool, command, file, reasoning, and usage telemetry. |
| Oh My Pi | Managed local extension through beacon-hooks | A pi-mono fork that kept Pi’s event payload shapes, so the two share one mapper but never share identity: separate harness names, separate extension markers, separate install directories. Unlike Pi it exposes real operator approval decisions, which are recorded as observed approvals. |
| Prime Agent | Not yet collected | Another pi-mono fork with the same extension API. Harness identity and the plugin collection method ship today; the managed extension, discovery probe, and install target do not, so no Prime Agent events are collected yet. |
| fx (Vercel Labs) | Poll of fx’s own session store | fx exposes no third-party observation surface: its lifecycle hooks are compiled into the binary, it has no OpenTelemetry export, and its plugin story is MCP. Beacon reads the append-only session records under ~/.fx/sessions and marks every event harness.collection_method=poll, so a consumer knows nothing on this path could have been intercepted. |
| Muse Code | Native hook payloads through beacon-hooks | Beacon writes a managed hooks file it owns outright and points Muse’s own settings.json at it with the managed_hooks_path key, then maps session, prompt, tool, command, file, approval, subagent, and compaction events into endpoint events. Muse ships an OTLP export that cannot be pointed at a local collector, so hooks are the only collection path. |
| goose | Native hook payloads through beacon-hooks, plus goose’s own OTLP export | Beacon installs a plugin of its own into the .agents/plugins directory goose discovers, leaving every other plugin untouched, then maps session, prompt, tool, command, file and MCP events into endpoint events. goose populates no tool output on a hook, so the second path is not optional in practice: pointing goose’s OpenTelemetry export at the local collector is what carries token usage, model, provider and reasoning. goose classifies a blocking hook’s stdout, so Beacon answers PreToolUse and Stop with an explicit allow rather than the usual no-op object. |
| Kiro | Native hook payloads through beacon-hooks | Beacon writes one hook file of its own into the .kiro/hooks/ directory Kiro scans, leaving every other file in it untouched, then maps session, prompt, tool, command, file, MCP and agent-response events into endpoint events. Kiro’s hook contract is exit codes rather than response objects, so Beacon writes nothing to stdout: on the two events Kiro reads it for, stdout is added to the model’s context. |
| OpenHands | Native hook payloads through beacon-hooks | Beacon merges its six commands into the .openhands/hooks.json the runtime already reads, preserving hooks you wrote, then maps session, prompt, tool, command, file, and MCP events into endpoint events. File edits carry an exact diff, because OpenHands reports the file’s content before and after rather than the edit instruction. |
| Qwen Code | Native hook payloads through beacon-hooks | Beacon merges a managed hook block into Qwen’s own settings.json and maps session, prompt, tool, command, file, failed-tool, approval, and subagent events into endpoint events. Qwen Code is a Gemini CLI fork without Gemini’s OTLP export, so hooks are the only collection path. |
| Devin CLI | Native hook payloads through beacon-hooks | Hooks emit session, prompt, pre-tool, post-tool, permission request, stop, session-end, approval, and file telemetry where Devin CLI exposes payloads. |
| Devin Desktop | Cascade/Windsurf hook payloads through beacon-hooks | Hooks emit prompt, command, MCP tool, file read, and file write telemetry where Devin Desktop exposes Cascade/Windsurf payloads. |
| Factory Droid | OTLP HTTP launch environment plus optional hooks | Beacon validates Factory OTLP state but does not mutate shell profiles for Droid. |
| Cursor | Native hook payloads through beacon-hooks | Hooks emit session, prompt, tool, command, MCP-like, approval, and file edit telemetry where Cursor exposes payloads. |
| Claude Cowork | Admin-configured OTLP from Anthropic’s service | Production Cowork telemetry should use a durable customer-managed HTTPS collector endpoint. |
| OpenClaw Gateway | Gateway-configured OTLP/HTTP export | Beacon prints Gateway diagnostics settings and validates OpenClaw-derived events in the runtime log. |
| Browser Extension | Managed browser extension over local OTLP | A Chrome MV3 extension parses the claude.ai and chatgpt.com chat streams and posts OTLP GenAI logs to the local collector. Beta, installed unpacked rather than from the Chrome Web Store, and configured in the extension’s own options page rather than by beacon. |
Hook telemetry
Antigravity CLI, Claude Code, Cline, Cursor, Devin CLI, Devin Desktop, Factory, goose, Grok Build, Hermes Agent, Muse Code, Oh My Pi, OpenCode, OpenHands, Pi, Qwen Code, and optional VS Code hooks cover activity that is better represented as runtime events than generic OTLP spans.| Runtime | Hook telemetry |
|---|---|
| Antigravity CLI | Prompt submission, pre-tool and post-tool activity, invocation stop events, command activity, file edits, and diffs where payloads are available. |
| Claude Code | Session lifecycle, prompt submission, pre-tool and post-tool activity, failed tool calls, subagent start and stop, permission requests, and session-end events where payloads are available. |
| Cursor | Session lifecycle, prompt submission, tool invocation, shell command execution, MCP-like tool activity, approval decisions, and file edits where payloads are available. |
| VS Code | Preview only and may be disabled by organization policy. When enabled, hooks add lifecycle, prompt, pre-tool, post-tool, stop, and subagent detail across VS Code agent surfaces. |
| Devin CLI | Session lifecycle, prompt submission, pre-tool and post-tool activity, permission requests, stop events, session-end events, approvals, and file telemetry where payloads are available. |
| Devin Desktop | Prompt submission, command execution, MCP tool use, file reads, and file writes where Cascade/Windsurf hook payloads are available. |
| Factory | Session start and end, prompt submission, write/edit/create tool use, stop events, and related file activity where payloads are available. |
| Grok Build | Session lifecycle, prompt submission, pre-tool and post-tool activity, post-tool failures, stop events, session-end events, command execution, and file activity where payloads are available. Project-level hooks require /hooks-trust in Grok before they execute. |
| Hermes Agent | Session lifecycle, prompt submission, observed tool calls, post-tool command and file activity, approval request and response events, and subagent stop metadata where Hermes exposes payloads. Hermes hooks are user-level only. |
| OpenCode | Chat messages, session events, command execution, permission activity, diffs, and errors where payloads are available. |
| Cline | Prompt submission, task start and end, task errors, tool invocation and completion, command execution with exit code, file reads and edits with diffs, MCP tool activity, and task token usage. Approval decisions are not exposed by Cline’s hook payloads. |
| Pi | Session lifecycle, prompt submission, tool invocation and results, command execution including operator ! commands, file reads, creates, and edits with the unified patch, agent reasoning from assistant thinking parts, and token usage and cost. Approval decisions are not exposed by Pi’s extension API and are not synthesized. |
| Oh My Pi | Everything Pi reports, plus real operator approval decisions carrying the command or file being decided on, the session’s approval mode, and the tool call id. Commands include operator ! shell and $ Python prefixes, and MCP tool activity is resolved from Oh My Pi’s mcp__<server>_<tool> naming. |
| Muse Code | Session start, prompt submission, pre-tool and post-tool activity, permission requests, subagent start and stop, context compaction, stop events, command execution, and file activity. Hook timeouts are second values. User scope only: Muse’s project .muse/hooks.json is ignored by the shipping build. |
| goose | Session start and end, prompt submission, pre-tool and post-tool activity, post-tool failures, stop events, command lines, and file activity with diffs. Hook timeouts are second values. The two scopes replace each other rather than merging: goose deduplicates plugins by name with project scope first, so one install is one registration. |
| Kiro | Session start, prompt submission, pre-tool and post-tool activity, stop events with the agent’s final response, command execution with output, and file activity. Hook timeouts are second values, and 0 means no timeout rather than the default. One install covers the Kiro IDE and the Kiro CLI, because they are one harness reading one hooks directory; both scopes are live at once, because Kiro merges them. |
| OpenHands | Session start and end, prompt submission, pre-tool and post-tool activity, stop events, command execution with exit code and output, and file activity with exact before/after diffs. Hook timeouts are second values. Both scopes work, but project scope is the one every host reads: OpenHands takes the first hooks file it finds, and its agent server never consults the user-level one. |
| Qwen Code | Session lifecycle, prompt submission, pre-tool and post-tool activity, post-tool failures, permission requests, subagent start and stop, stop events, session-end events, command execution, and file activity where payloads are available. Hook timeouts are millisecond values, and project-level hooks require a trusted folder in Qwen. |
Related
Open Source Architecture
Follow runtime signals through collection, normalization, storage, and forwarding.
Agent harness integrations
Compare agent harness support and open runtime-specific details.
Hooks
Install, inspect, and uninstall runtime hook integrations.