Skip to main content

​
Runtime overview

Beacon supports Claude Code through local OpenTelemetry export to Beacon’s localhost collector, optional hook telemetry for richer lifecycle and tool activity, and local session-file sync for historical backfill.

​
Prerequisites

Before enabling Claude Code telemetry, make sure:
  • Claude Code is installed and available as the claude executable for the user or managed endpoint.
  • beacon endpoint install has run so the local collector, endpoint config, and runtime log path exist.
  • The install includes the claude harness, either through the default harness list or an explicit --harness claude value.
  • Your team has reviewed content handling and destination access for prompt telemetry.

​
Collection paths

Claude Code exports OTLP telemetry to the local Beacon collector. Beacon writes normalized endpoint events to the configured runtime JSONL log and makes them available in the local dashboard. For richer local telemetry, Beacon can also install Claude Code hooks with the same hook adapter used by other supported runtimes:
Install Claude Code hooks
User-level hooks are written to ~/.claude/settings.json. Project-level hooks are written to ./.claude/settings.json:
User-level hooks are written to ~/.claude/settings.json. Project-level hooks are written to ./.claude/settings.json
For backfill, Beacon can also read Claude Code’s committed JSONL session files under ~/.claude/projects:
Sync Claude Code session files
The sync path is local and offline. It appends mapped events to the runtime log with harness.collection_method=poll, so it can recover historical sessions or sessions that ran before hooks were installed, but it cannot hold, approve, deny, or delay tool calls. Use beacon endpoint claude sync --print to preview mapped events without writing the runtime log or advancing the cursor.

​
Claude Code Cloud Agents

Beacon also supports proof-of-concept telemetry capture from Claude Code cloud agents. The cloud setup path installs ephemeral Beacon hooks inside the Claude cloud sandbox, writes /tmp/beacon/runtime.jsonl, and uploads the session log to customer-managed Google Cloud Storage. Start with Claude Code Cloud Agents when you want to test Claude Code cloud agent telemetry without deploying Beacon Managed.
The self-serve GCS path passes a scoped service-account credential to the Claude Code cloud environment. Use it for evaluation and prototypes. For production enterprise deployments, use Beacon Managed or contact Beacon about secure forwarding in your own customer-managed infrastructure.

​
Discovery and status

Beacon detects Claude Code through the claude executable and Claude settings paths. Use beacon endpoint discover or beacon endpoint status to confirm that Claude Code is present and configured for local telemetry. Use beacon endpoint claude status to inspect local session files and how far the sync cursor has read.

​
Install or configuration support

beacon endpoint install configures Claude telemetry settings so Claude Code sends OTLP data to the local collector. It enables detailed tool logging so tool-result events include inputs such as Bash commands, file paths, URLs, search patterns, and MCP server/tool arguments. Claude bounds or truncates some input values; tool output content is not enabled by this setting. beacon endpoint hooks install --harness claude adds Beacon-managed Claude Code hooks while preserving existing Claude settings and non-Beacon hooks. beacon endpoint hooks uninstall --harness claude removes only Beacon-managed Claude hook entries.

​
Telemetry coverage

Claude Code hooks cover SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, SubagentStart, SubagentStop, PermissionRequest, and SessionEnd. Pre-tool matching includes common Claude tools such as Bash, Edit, Write, MultiEdit, Read, Glob, Grep, WebFetch, WebSearch, Agent, and mcp__.*.

​
Normalized OTLP events

Beacon maps Claude Code’s OTLP logs into canonical endpoint actions instead of treating every unrecognized record as a tool invocation:
  • user_prompt becomes prompt.submitted.
  • A successful or failed Bash tool_result becomes command.executed, with the decoded command in command.command and the reported duration in command.duration_ms.
  • Read results become file.read; Write, Edit, and NotebookEdit results become file.modified, with the decoded path in file.path.
  • Accepted and rejected tool_decision records become approval.allowed and approval.denied. Bash decisions also retain the full command when Claude provides it.
  • API requests, assistant responses, hooks, plugins, skills, compaction, and other ordinary lifecycle records become session activity. API and internal errors become session.error; refusals and permission-mode changes become session.status.
  • MCP server connection lifecycle records become mcp.connection, not mcp.tool_invoked.
Claude reports tool success and duration but does not provide an exact process exit status, so Beacon does not invent command.exit_code. The original OTLP attributes remain under raw.attributes, subject to the configured redaction and event-size controls. Future full-body claude_code.* lifecycle records default to session.activity until Beacon assigns a more specific mapping. Optional hook events are an additional telemetry source. A hook pre-tool observation can appear as tool.invoked; the completed OTLP tool_result is the record that supplies the canonical command or file action. Detailed tool inputs can contain sensitive command arguments, paths, URLs, search terms, and MCP request data. Beacon sends this telemetry only to the configured local collector during normal endpoint execution; apply the same access, retention, and redaction controls used for other retained prompt and tool data.

​
Session-file sync

beacon endpoint claude sync reads committed Claude Code transcripts after Claude has written them. The cursor is stored in Beacon endpoint state, not in Claude’s directory, and tracks files by line so scheduled runs do not re-append the same records. A partly written trailing record is left for the next sweep. Run beacon endpoint claude sync --watch, or schedule one-shot sweeps, if you want the poll path to stay current. The live OTLP and hook paths remain the real-time integrations; the poll path is for backfill and catch-up.

​
Deployment notes

For MDM deployments, use the signed and notarized macOS .pkg so endpoint events land in /var/log/beacon-agent/runtime.jsonl. The package installs the endpoint agent under /opt/beacon, creates system endpoint configuration, and loads the local collector LaunchDaemon. If a system collector is running while the CLI is reading the default per-user log, beacon endpoint status and the local dashboard surface a runtime-log source warning so you can tell where OTLP events are being written.

Supported agent harnesses

Return to the runtime support overview.

Agent harness integration model

See how Beacon discovers and configures supported runtimes.

Runtime hooks

Install, inspect, and uninstall Claude Code hook telemetry.