Skip to main content

​
Runtime overview

Beacon supports OpenCode through a managed local plugin that invokes beacon-hooks. Beacon can also read OpenCode’s committed local session store with beacon endpoint opencode sync. That poll path backfills historical or uninstrumented sessions, while the managed plugin remains the live path for hook-time events and approval telemetry.

​
Prerequisites

Before enabling OpenCode telemetry, make sure:
  • OpenCode is installed and available as the opencode executable or has a local config directory.
  • beacon endpoint install has run so shared endpoint config and runtime log paths exist.
  • Beacon’s OpenCode plugin is installed with beacon endpoint hooks install --harness opencode.
  • OpenCode is restarted after plugin install or removal so new sessions load the updated plugin.

​
Collection path

Beacon installs an owned OpenCode plugin at ~/.config/opencode/plugins/beacon.ts for user-level hooks or ./.opencode/plugins/beacon.ts for project-level hooks. The plugin forwards supported OpenCode hook payloads to Beacon’s hook adapter. The integration is plugin-based. OpenCode’s native OTLP export is neither configured nor required by Beacon. For backfill, beacon endpoint opencode sync reads OpenCode’s local opencode.db when present and falls back to the legacy storage/session, storage/message, storage/part, and storage/project tree. Those events are marked harness.collection_method=poll because Beacon reads committed records after the fact; nothing on that path can hold or deny a tool call.

​
Discovery and status

Beacon detects OpenCode through the opencode executable or ~/.config/opencode, then checks for Beacon plugin configuration. Use beacon endpoint hooks status --harness opencode to inspect OpenCode plugin status. Use beacon endpoint opencode status to inspect persisted session-store collection progress.

​
Install or configuration support

beacon endpoint install prepares shared endpoint config and runtime log paths. Install OpenCode hooks separately:
Install runtime hooks
Backfill committed local sessions

​
Telemetry coverage

​
Data handling

OpenCode prompts, completed assistant text and reasoning, tool arguments and results, commands, command output, paths, and diffs are retained in local or customer-controlled logs. Beacon applies local secret redaction and per-string limits before writing. Each content-bearing event includes a hash and byte count for the original value. Events over the 64 KiB limit drop raw and retained content, preserve stable metadata, and set field_truncated. The plugin uses OpenCode session, message, part, permission request, and tool call identifiers for correlation. The poll path uses OpenCode’s persisted session, message, part, and tool call identifiers. It does not create file events without an agent-derived path, so object-storage ingestion paths are not treated as files the agent touched.

​
Deployment notes

Restart OpenCode after installing or removing hooks so new sessions pick up the updated plugin configuration. For local troubleshooting, set BEACON_OPENCODE_DEBUG=1 in the environment that launches OpenCode to emit best-effort plugin debug logs. The adapter has a bounded local subprocess timeout and remains fail-open, so telemetry failures do not interrupt OpenCode execution. For historical collection or deployments where OpenCode did not load the plugin, run beacon endpoint opencode sync --print to preview mapped events, then beacon endpoint opencode sync to append them to the runtime log. Use --watch or a scheduler if you want the poll path to stay current. Validate a system-mode installation after restarting OpenCode:

Supported agent harnesses

Return to the runtime support overview.

Hooks

Install, inspect, and uninstall runtime hook integrations.

beacon endpoint opencode

Backfill OpenCode sessions from the local session store.