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 |
| 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 structured OTLP exporter tables to ~/.codex/config.toml, sets log_user_prompt = false, and sends logs, traces, and metrics to the local collector. |
| 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. |
| Hook-based runtimes | Antigravity CLI, Claude Code, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, and OpenCode hooks 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; optional hooks add lifecycle, subagent, permission, and tool event detail. |
| Codex CLI | Local OTLP logs, traces, and metrics | Beacon writes structured Codex OTLP config and filters noisy internal transport spans. |
| 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. |
| 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. |
Hook telemetry
Antigravity CLI, Claude Code, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, OpenCode, 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. |
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.