Runtime Integrations

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:

Claude Code and Codex CLI are pointed at the local OTLP collector.
Codex CLI receives structured OTLP exporter tables in ~/.codex/config.toml; Beacon also sets log_user_prompt = false and sends logs, traces, and metrics to the local collector.
Gemini CLI can be opted in 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 can be opted in 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’s OTLP HTTP endpoint stays 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’s OTLP endpoint stays under Droid’s launch environment, commonly managed through MDM or another customer-owned policy.
OpenClaw Gateway is configured in OpenClaw with the diagnostics-otel plugin; Beacon prints local OTLP/HTTP setup guidance and validates observed events.
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.

Antigravity CLI records prompt submission, pre-tool and post-tool activity, invocation stop events, command activity, file edits, and diffs where payloads are available.
Claude Code records 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 records session lifecycle, prompt submission, tool invocation, shell command execution, MCP-like tool activity, approval decisions, and file edits where payloads are available.
VS Code hooks are preview and may be disabled by organization policy. When enabled, they add lifecycle, prompt, pre-tool, post-tool, stop, and subagent detail across VS Code agent surfaces.
Devin CLI records 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 records prompt submission, command execution, MCP tool use, file reads, and file writes where Cascade/Windsurf hook payloads are available.
Factory records session start and end, prompt submission, write/edit/create tool use, stop events, and related file activity where payloads are available.
Grok Build records 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 records 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 records chat messages, session events, command execution, permission activity, diffs, and errors where payloads are available.

Hook events include metadata such as file path, operation, language, diff hash, and diff byte count. Raw diffs are subject to Beacon’s redaction, sanitization, truncation, and event-size limits before writing.

Beacon architecture

Return to the architecture overview.

Telemetry pipeline

Follow runtime signals through collection, normalization, storage, and forwarding.

Supported runtimes

Compare agent harness support and open runtime-specific details.

Hooks

Install, inspect, and uninstall runtime hook integrations.

​Integration Model

​Discovery and status

​Install-time configuration

​Integration paths

​Hook telemetry

​Related