> ## Documentation Index > Fetch the complete documentation index at: https://docs.beacon.sh/llms.txt > Use this file to discover all available pages before exploring further. # Agent Harness Integration Model > How Beacon discovers, validates, and configures supported agent harnesses ## Integration model Beacon supports multiple [runtime surfaces](/concepts/core-concepts#runtime-surface) because each [agent harness](/runtimes) 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](/runtimes/claude-code) | Looks for the `claude` executable and Claude settings paths | | [Codex CLI](/runtimes/codex-cli) | Looks for the `codex` executable and `~/.codex/config.toml` | | [Gemini CLI](/runtimes/gemini-cli) | Looks for the `gemini` executable and `~/.gemini/settings.json` | | [GitHub Copilot CLI](/runtimes/github-copilot-cli) | Looks for the `copilot` executable or `~/.copilot/config.json`, then validates Copilot OTel environment variables | | [VS Code](/runtimes/vscode) | Looks for the `code` executable or VS Code user settings, then validates Copilot Chat OTel settings | | [Grok Build](/runtimes/grok-build) | Checks for Beacon's managed Grok hook file at `~/.grok/hooks/beacon-endpoint.json` or `./.grok/hooks/beacon-endpoint.json` | | [OpenCode](/runtimes/opencode) | Looks for the `opencode` executable or `~/.config/opencode`, then checks the managed Beacon plugin | | [Cline](/runtimes/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](/runtimes/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](/runtimes/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)](/runtimes/vercel-fx) | 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](/runtimes/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](/runtimes/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 `/.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](/runtimes/kiro) | Checks `/.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](/runtimes/openhands) | Checks `/.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](/runtimes/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](/runtimes/devin) | Looks for the `devin` executable, `~/.config/devin`, or `./.devin`, then checks Beacon hook configuration | | [Devin Desktop](/runtimes/devin-desktop) | Checks Cascade/Windsurf hook configuration at `~/.codeium/windsurf/hooks.json` or `./.windsurf/hooks.json` | | [Factory Droid](/runtimes/factory-droid) | Looks for the `droid` executable and validates `OTEL_TELEMETRY_ENDPOINT` in the effective launch environment | | [Cursor](/runtimes/cursor) | Looks for the Cursor binary or `~/.cursor`, then checks Beacon hook configuration | | [Claude Cowork](/runtimes/claude-cowork) | Treats it as an admin-configured OTLP source because telemetry is enabled in Claude organization settings | | [OpenClaw Gateway](/runtimes/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](/runtimes/claude-code) | Beacon points Claude Code at the local OTLP collector. Hook installation is separate through [`beacon endpoint hooks`](/cli/hooks). Historical transcripts can be backfilled with `beacon endpoint claude sync`. | | [Codex CLI](/runtimes/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. Historical sessions can be backfilled with `beacon endpoint codex sync`. | | [Gemini CLI](/runtimes/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](/runtimes/vscode) | 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](/runtimes/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](/runtimes/factory-droid) | Droid's OTLP endpoint remains under its launch environment, commonly managed through MDM or another customer-owned policy. Committed sessions can be backfilled with `beacon endpoint factory sync`. | | [OpenClaw Gateway](/runtimes/openclaw-gateway) | Configure OpenClaw with the `diagnostics-otel` plugin. Beacon prints local OTLP/HTTP setup guidance and validates observed events. Committed session files can be backfilled with `beacon endpoint integrations openclaw sessions sync`. | | [fx (Vercel Labs)](/runtimes/vercel-fx) | 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`](/cli/endpoint-fx). | | Hook-based runtimes | [Antigravity CLI](/runtimes/antigravity-cli), [Claude Code](/runtimes/claude-code), [Cline](/runtimes/cline), [Cursor](/runtimes/cursor), [Devin CLI](/runtimes/devin), [Devin Desktop](/runtimes/devin-desktop), [Factory](/runtimes/factory-droid), [Grok Build](/runtimes/grok-build), [goose](/runtimes/goose), [Hermes Agent](/runtimes/hermes-agent), [Kiro](/runtimes/kiro), [Muse Code](/runtimes/muse-code), [Oh My Pi](/runtimes/oh-my-pi), [OpenCode](/runtimes/opencode), [OpenHands](/runtimes/openhands), [Pi](/runtimes/pi), and [Qwen Code](/runtimes/qwen-code) hooks and managed plugins are installed separately with [`beacon endpoint hooks`](/cli/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](/runtimes/claude-code) | Local OTLP export, optional hooks, and poll of `~/.claude/projects` | OTLP and hooks are the live paths. `beacon endpoint claude sync` reads committed transcripts for backfill and marks those events `harness.collection_method=poll`. | | [Codex CLI](/runtimes/codex-cli) | Local OTLP logs, selective turn traces, SessionStart hook, and poll of `~/.codex/sessions` | Beacon writes structured Codex OTLP config, filters noisy internal spans, and joins OS-user context to per-turn usage. `beacon endpoint codex sync` backfills committed sessions as poll events. | | [Gemini CLI](/runtimes/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](/runtimes/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](/runtimes/vscode) | 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](/runtimes/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](/runtimes/grok-build) | Native hook payloads through `beacon-hooks`, plus poll of `~/.grok/sessions` | Beacon writes an owned Grok hook file and maps session, prompt, tool, command, file, and failed-tool events into endpoint events. `beacon endpoint grok sync` backfills committed sessions as poll events. | | [Hermes Agent](/runtimes/hermes-agent) | Shell hook payloads through `beacon-hooks`, plus poll of `~/.hermes/state.db` | Beacon merges user-level Hermes shell hooks and maps prompts, tools, commands, approvals, session lifecycle, and subagent stop metadata into endpoint events. `beacon endpoint hermes sync` backfills committed sessions as poll events. | | [OpenCode](/runtimes/opencode) | Managed local plugin through `beacon-hooks`, plus poll of OpenCode's local session store | Plugin invokes Beacon for chat, session, command, permission, diff, and error events where payloads are available. `beacon endpoint opencode sync` backfills committed sessions as poll events. | | [Cline](/runtimes/cline) | Managed local plugin through `beacon-hooks`, plus poll of Cline's local task/session stores | 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. `beacon endpoint cline sync` backfills committed tasks and sessions as poll events. | | [Pi](/runtimes/pi) | Managed local extension through `beacon-hooks`, plus poll of Pi's local session store | Pi has no hooks file and no OTLP export, so the TypeScript extension API is the live observation surface. Beacon's managed extension forwards session, prompt, tool, command, file, reasoning, and usage telemetry; `beacon endpoint pi sync` backfills committed sessions as poll events. | | [Oh My Pi](/runtimes/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](/runtimes/prime-agent) | Managed local extension through `beacon-hooks`, plus poll of Prime Agent's local session store | The other pi-mono fork, sharing Pi's event payload shapes and so Pi's mapper, but never Pi's identity: separate harness name, separate extension marker, separate install directory. Its persistent Python kernel cells are recorded as commands, and `beacon endpoint prime sync` backfills committed sessions and subagent artifacts as poll events. | | [fx (Vercel Labs)](/runtimes/vercel-fx) | 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](/runtimes/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](/runtimes/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](/runtimes/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](/runtimes/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](/runtimes/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](/runtimes/devin) | 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](/runtimes/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](/runtimes/factory-droid) | OTLP HTTP launch environment, optional hooks, and poll of `~/.factory/sessions` | Beacon validates Factory OTLP state but does not mutate shell profiles for Droid. `beacon endpoint factory sync` backfills committed sessions as poll events. | | [Cursor](/runtimes/cursor) | Native hook payloads through `beacon-hooks`, plus poll of Cursor's local session stores | Hooks emit session, prompt, tool, command, MCP-like, approval, reasoning, context, and file edit telemetry where Cursor exposes payloads. `beacon endpoint cursor sync` backfills committed Composer and agent-session records as poll events. | | [Claude Cowork](/runtimes/claude-cowork) | Admin-configured OTLP from Anthropic's service | Production Cowork telemetry should use a durable customer-managed HTTPS collector endpoint. | | [OpenClaw Gateway](/runtimes/openclaw-gateway) | Managed plugin, gateway-configured OTLP/HTTP export, and poll of committed session files | Beacon's plugin covers agent activity, Gateway diagnostics export covers traces and metrics, and `beacon endpoint integrations openclaw sessions sync` backfills committed session files as poll events. | | [Browser Extension](/runtimes/browser-extension) | Managed browser extension over local OTLP | A Chrome MV3 extension parses the [claude.ai](/runtimes/claude-web) and [chatgpt.com](/runtimes/chatgpt-web) 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](/runtimes/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](/runtimes/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](/runtimes/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](/runtimes/vscode) | 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](/runtimes/devin) | 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](/runtimes/devin-desktop) | Prompt submission, command execution, MCP tool use, file reads, and file writes where Cascade/Windsurf hook payloads are available. | | [Factory](/runtimes/factory-droid) | Session start and end, prompt submission, write/edit/create tool use, stop events, and related file activity where payloads are available. | | [Grok Build](/runtimes/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](/runtimes/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](/runtimes/opencode) | Chat messages, session events, command execution, permission activity, diffs, and errors where payloads are available. | | [Cline](/runtimes/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](/runtimes/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](/runtimes/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___` naming. | | [Muse Code](/runtimes/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](/runtimes/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](/runtimes/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](/runtimes/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](/runtimes/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. | 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. ## Related Follow runtime signals through collection, normalization, storage, and forwarding. Compare agent harness support and open runtime-specific details. Install, inspect, and uninstall runtime hook integrations.