Skip to main content

​
Runtime overview

Beacon supports Cline through a managed local plugin that invokes beacon-hooks. Cline is not a single runtime. The same agent core runs as a VS Code extension, a JetBrains plugin, and a CLI, and Beacon’s plugin covers all of them: it is loaded by whichever host is running, so one install collects telemetry from every surface on that machine.

​
Prerequisites

Before enabling Cline telemetry, make sure:
  • Cline is installed in at least one host, or has a local config directory at ~/.cline.
  • beacon endpoint install has run so shared endpoint config and runtime log paths exist.
  • Beacon’s Cline plugin is installed, either by beacon endpoint install when it detects Cline or with beacon endpoint hooks install --harness cline.
  • Cline is restarted after plugin install or removal so new sessions load the updated plugin. In the IDE hosts this means reloading the window.

​
Collection paths

Beacon installs an owned Cline plugin at $CLINE_DIR/plugins/beacon.ts (default ~/.cline/plugins/beacon.ts) for user-level hooks or ./.cline/plugins/beacon.ts for project-level hooks. Cline auto-discovers plugin files in those directories, so no plugin registry command is required. That is also why the install works for the VS Code and JetBrains hosts, neither of which ships a cline executable. The plugin forwards beforeRun, beforeTool, afterTool, and afterRun hook payloads to Beacon’s hook adapter. It spawns the adapter directly with an argument vector rather than through a shell, so the same plugin works unchanged on macOS, Linux, and Windows. The integration is plugin-based. Cline’s own OpenTelemetry export is neither configured nor required by Beacon, and Cline’s hosted prompt-storage feature is not used. Beacon can also recover Cline activity from Cline’s committed local session stores:
Sync historical Cline sessions
The sync path reads data/tasks, tasks, data/sessions, and kanban/workspaces under $CLINE_DIR (default ~/.cline), plus Cline’s VS Code global-storage task directory. It is local and offline, emits events with harness.collection_method=poll, and is useful for historical sessions or sessions that ran before the Beacon plugin was installed. Use --print to inspect mapped events without writing the runtime log or advancing the cursor. Plugin install, discovery, inventory, and session sync honor CLINE_DIR as Cline does: when it is set, it replaces ~/.cline. The scheduled inventory job starts without your shell’s environment, so a per-user beacon endpoint install or repair writes the CLINE_DIR it resolved into the job’s launchd or systemd definition. If you change CLINE_DIR later, run beacon endpoint repair from a shell that has the new value. System-mode installs do not record it. Project-level .cline files are not affected.

​
Discovery and status

Beacon detects Cline through the $CLINE_DIR directory (default ~/.cline), treating a cline executable on PATH as an additional signal rather than the deciding one. A binary check alone would report “not detected” for the IDE hosts, which are the majority of installs. Use beacon endpoint hooks status --harness cline to inspect Cline plugin status. Status reports installed only when the plugin references the hook binary that is actually present, so a plugin left behind by a removed or relocated install is reported as not installed rather than as working telemetry. Use beacon endpoint cline status to inspect Cline session stores and how much of each discovered trace Beacon has already synced.

​
Install or configuration support

beacon endpoint install prepares shared endpoint config and runtime log paths, and installs the Cline plugin at user level when it detects Cline (or when you pass --harness cline). To install, refresh, or manage the plugin on its own, including at project level:
Install runtime hooks

​
Telemetry coverage

Cline addresses files relative to the workspace root. Beacon resolves those paths against the workspace before writing them, so a Cline file event is comparable with the same file seen through another runtime and matches threat rules written against absolute paths. A path that is already absolute is left alone, and a relative path with no resolvable workspace root stays relative rather than being joined to a guessed root. A cancelled task ends rather than fails. Cline fires its cancel hook for the cleanup that follows someone stopping or abandoning a task, so Beacon records session.ended at info severity with session.cancel_reason set, not session.error. Otherwise every deliberate stop would count as an incident in error rollups and alerting. A cancelled task still reports the tokens it spent. Cancels and failures reach Beacon two ways: the file-based hooks name them in the hook itself, and the plugin reports them as a status on its run-completion handler. Both are read, so the distinction holds on the surface Beacon installs. A run that reports no recognized outcome is recorded as a completion. Token usage is recorded at task end only. Beacon’s token rollups sum gen_ai.usage across events, so reporting the same tokens at a per-model-call boundary would double every Cline task’s totals. Cost is recorded only as Cline reports it. Beacon never writes a derived cost into an event; token reports keep their list-price estimate separate from the reported figure. The session sync path reads what Cline has already committed to disk. It can recover prompts, assistant messages, agent reasoning, tool calls/results, command/file/MCP-shaped tool activity, model ids, and token counts where the stored history carries them. It cannot hold or deny tool calls, and it does not imply that Beacon observed the event at runtime.

​
Data handling

Cline prompts, 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 that exceed the 64 KiB limit drop raw and retained content while preserving stable metadata and set field_truncated. The plugin flattens Cline’s live hook context before sending it, dropping functions and cyclic references, and forwards the remaining fields under raw.cline. It uses Cline’s task identifier for correlation and does not create file events without an agent-derived path.

​
Known gaps

  • Approval decisions are not recorded. Cline requires approval for actions by default, but the documented hook context does not carry the approval state, so Beacon does not synthesize an approval decision from a tool call. The forwarded payload is preserved, so approval telemetry can be added later without changing what is already collected.
  • No enforcement. Cline’s beforeTool hook can cancel a tool call, and Beacon’s plugin never does. Enforcement stays behind the optional, off-by-default policy provider seam (BEACON_POLICY_PROVIDER), which is not wired to Cline.

​
Deployment notes

Restart Cline, or reload the IDE window, after installing or removing hooks so new sessions pick up the updated plugin configuration. For local troubleshooting, set BEACON_CLINE_DEBUG=1 in the environment that launches Cline to emit best-effort plugin debug logs. The plugin has a bounded local subprocess timeout and remains fail-open, so telemetry failures do not interrupt Cline execution. Validate a system-mode installation after restarting Cline:

Supported agent harnesses

Return to the runtime support overview.

Hooks

Install, inspect, and uninstall runtime hook integrations.