Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.asymptotelabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Beacon Architecture

Beacon runs on the endpoint and keeps the normal telemetry path local. Supported AI runtimes emit activity through either OpenTelemetry or native hook payloads. Beacon collects those signals, normalizes them into endpoint events, and writes one JSON object per line to the local runtime log. Beacon endpoint architecture showing AI runtimes sending local OTLP or hook telemetry into Beacon collection and normalization, then writing endpoint JSONL for local dashboard, Wazuh, and customer-managed forwarding.

​
Architecture layers

  1. Runtime surfaces: Claude Code, Codex CLI, Cursor, and Claude Cowork expose different telemetry surfaces. Beacon uses the strongest surface available for each runtime instead of forcing every tool through one adapter.
  2. Local collection: Claude Code and Codex CLI export OTLP to localhost. Cursor invokes the embedded beacon-hooks adapter. Claude Cowork is configured from Anthropic admin settings and validated by Beacon.
  3. Normalization: OTLP logs, traces, metrics, resource attributes, and hook payloads are mapped into the Beacon endpoint schema with consistent action names, severity, endpoint identity, harness context, session context, tool metadata, command metadata, file metadata, MCP-like tool metadata, approval metadata, and content-retention metadata.
  4. Local outputs: Beacon writes runtime.jsonl, serves a loopback-only dashboard over that file, and provides Wazuh localfile/rule content. Other destinations can consume the same JSONL through customer-managed forwarding.

​
Runtime discovery and configuration

beacon endpoint discover inspects the local machine for supported AI runtimes and their telemetry state. Claude Code is detected through the claude executable and Claude settings paths. Codex CLI is detected through the codex executable and ~/.codex/config.toml. Cursor is detected through the Cursor binary or ~/.cursor, then checked for Beacon hook configuration. Claude Cowork is treated as an admin-configured OTLP source because its telemetry is enabled in Claude organization settings. During install, Beacon configures Claude Code and Codex CLI to send OTLP to the local collector. Cursor hook telemetry is installed separately with beacon endpoint hooks, because hooks are managed through Cursor configuration rather than OTLP runtime settings.

​
Local collection

Beacon writes an OpenTelemetry Collector configuration with localhost receivers:
ReceiverDefault endpoint
OTLP gRPC127.0.0.1:4317
OTLP HTTP127.0.0.1:4318
On macOS, the collector is managed with launchd in user mode or system mode. The generated collector pipeline receives logs, traces, and metrics, batches them, applies memory limits, and exports normalized Beacon events through the beaconjson exporter. Packaged deployments can use the Beacon collector distribution; local installs can point at an otelcol or otelcol-contrib binary with --collector.

​
Hook telemetry

Cursor hooks cover activity that is better represented as runtime events than generic OTLP spans. Where Cursor exposes payloads, Beacon records session lifecycle, prompt submission, tool invocation, shell command execution, MCP-like tool activity, approval decisions, and file edits. Hook events are metadata-first. For file edits, Beacon stores file path, operation, language, diff hash, and diff byte count. Raw diffs are included only when content retention is explicitly configured away from the default metadata mode.

Endpoint agent

Install, repair, inspect, and uninstall the local endpoint agent.

Endpoint event schema

Review normalized Beacon JSONL event fields.