agent-beacon: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code and other coding agents working in this repository.

Project Scope

Beacon Endpoint Agent is a local-only endpoint telemetry agent for AI runtimes. The shipping code paths are:

• cli/beacon: public beacon CLI and endpoint runtime.
• cli/beacon-hooks: hook adapter invoked by Cursor and other supported runtimes.
• collector-builder: OpenTelemetry Collector distribution and Beacon JSONL exporter.
• packages/asymptote-sdk-js: TypeScript SDK for cloud agent telemetry that exports Beacon-compatible OpenTelemetry spans.
• browser-extension: optional MV3 collector (Chrome, plus a beta Firefox build target) that relays Claude.ai and ChatGPT chat telemetry into the local pipeline as OTLP.
• pkg/asymptoteobserve: shared Go library — event schema, harness-name normalization, provenance markers, token usage, and the threat-rules engine. Imported by the CLI, the hook adapter, and the collector exporter, so a change here reaches all three.
• plugins: TypeScript sources for the managed runtime plugins/extensions (opencode-beacon, cline-beacon, pi-beacon, omp-beacon, openclaw-beacon, prime-beacon, omo-beacon), each mirrored into an embedded copy under cli/beacon/internal/endpoint/hooks/assets/.
• agent-skills: publishable Agent Skills plugin for the traces-to-memory workflow (beacon-memory-recall, beacon-memory-distill, beacon-memory-promote), for authoring dashboard lenses (beacon-lens-create), for sharing the current session to beacon.sh (beacon-trace-share, which runs beacon share --current --harness <runtime> --json, keeps the default direct visibility and asks before public), and for continuing local sessions in another runtime (beacon-session-handoff, which uses detached CLI launch) with manifests for Claude Code, Agent Plugins (Codex, Copilot, VS Code, Kiro, Devin), Cursor, Kimi Code, and Gemini CLI. At the repo root, .claude-plugin/marketplace.json is read by most harnesses, .cursor-plugin/marketplace.json by Cursor, and package.json (pi.skills only) makes the repo a Pi/Prime Agent package; keep that root package.json free of dependencies and scripts. cli/beacon/cmd/agent_skills_test.go checks every beacon command and flag the skills name against the real command tree, so rename a command and update the skills together. The binary carries a copy of agent-skills/skills in cli/beacon/internal/agentskills/skills for onboarding and beacon skills install; a test keeps it identical, so copy it across whenever a skill changes.
• rules and spec/threat-rules: the open rule corpus and the Threat Rules format it conforms to. Every rule's taxonomy.beacon_category is its directory name, and the six embedded baseline rules in pkg/asymptoteobserve/rulestore/baseline are byte-identical copies of their corpus rules; conformance tests enforce both.
• spec/lenses: the Lenses format — single-file HTML views of one trace that the local dashboard runs in a sandboxed, network-less frame and feeds once through window.beacon.getTrace(). The contract types (LensManifestV1, LensDataV1) live in pkg/asymptoteobserve/lens.go, and lens_test.go pins the spec's examples and manifest schema to them. The dashboard builds the data in BuildLensData (/api/lens-data), lists lenses at /api/lenses, and serves each lens at /lenses/frame/<id> under the spec's CSP with lenses/prelude.js (which defines window.beacon) injected ahead of it; that route is the only one that may be framed. Built-in lenses are cli/beacon/internal/endpoint/dashboard/lenses/*.lens.html, and activity is byte-identical to the spec example (a test enforces it). The session page (static/session.html, initLensTabs in app.js) shows lenses as tabs fed by /api/lens-data?session=, which projects exactly the events that page lists; it is the host half of the protocol and closes a lens that errors, stalls, or navigates its own frame. Trust model (SPEC "Trust model"): the opaque origin, sandbox and CSP keep a lens from touching Beacon or the dashboard and block ordinary network APIs, but cannot fully prevent a lens from sending trace data out through browser features no CSP governs (WebRTC, resource hints, speculative loading), so an installed lens is code the person trusts with the trace data it is shown; never describe the sandbox as making exfiltration impossible. prelude.js removes the RTC* globals and guards the document (refuses creating, inserting or parsing in nested frames, <link> elements and <script type=speculationrules>, parsing markup in the real call's document and context and inserting exactly the checked nodes so <noscript>/foreign-content parser differentials cannot slip through, refuses document.write and execCommand("insertHTML"), and a mutation observer removes those from the file's own markup); that is best-effort hardening, not a boundary, and the hostile probe fixture in testdata/lens-e2e pins each covered path. Installed lenses live in the lens store (cli/beacon/internal/endpoint/lensstore, <BaseDir>/lenses/<id>.lens.html, 0600 under 0700), written only by beacon lenses add|remove (cli/beacon/cmd/lenses.go; add prints the trust warning and confirms on a TTY, and refuses without one or in CI unless --yes); the dashboard rescans it per request and never writes it, and a store lens can never shadow a built-in. asymptoteobserve.CheckLensFile is the one file check every installer, server and linter uses. User docs are docs/concepts/lenses.mdx and docs/cli/lenses.mdx; keep them in sync with the commands and built-in lenses. The authoring loop is beacon lenses spec (the spec carried in the binary as dashboard/lenses/SPEC.md, kept byte-identical to spec/lenses/SPEC.md by a test), beacon lenses data (the exact LensDataV1 for a session), beacon lenses lint (lensstore.Lint; built-ins must lint clean) and beacon lenses preview (the dashboard with Options.LensFiles, re-read per reload).
• beacon-sandbox: harness that runs a real Claude Code session in a disposable sandbox and checks what Beacon captured. See beacon-sandbox/AGENTS.md.
• packaging: macOS, Linux, and Windows packaging and deployment assets.
• terraform: customer-run Terraform modules for the cloud side of object storage forwarding. The base modules aws-s3 and gcs always create a new, dedicated bucket (never an existing one) and the writer every Mac's forwarder uses: the put-only beacon-endpoint-writer IAM user, or a beacon-endpoint-writer service account with objectCreator limited to the prefix by an IAM condition. The enterprise self-hosted path, where Asymptote reads that bucket through ClickHouse, is two separate modules that take the base module's bucket output: aws-s3-asymptote-reader (an asymptote-s3-reader IAM user, because ClickPipes on the GCP-hosted ClickHouse rejects IAM roles, plus an SQS queue and dead-letter queue per stream and the bucket notification, which it owns) and gcs-asymptote-reader (objectViewer for beacon-clickpipes-reader@asymptote-labs, a Pub/Sub topic, the notification and a subscription per stream with the managed path's settings). The queues exist because a ClickPipe without one reads in key order and skips objects that land behind its cursor, which Macs uploading on their own timers cause; their URLs and subscription paths are outputs for the provisioning script's --queue-url. Keep everything Asymptote-specific out of the base modules. No module creates keys unless asked (create_writer_access_key, create_writer_key, create_access_key), so no secret lands in state by default. Resource names and forwarder_settings match the packaged install-forwarder.sh helpers and the manual guides. docs.beacon.sh (docs/log-forwarding/{aws-s3,gcs}-terraform.mdx) documents the base modules only. The reader modules and the self-hosted setup are documented only on docs.asymptotelabs.ai (beacon-mdr docs/deployment/self-hosted-{s3,gcs}.mdx), so keep them out of docs/; /manage/configure-s3-data-connector redirects there. Both sites pin the modules to a release tag; keep them in sync with the variables.
• docs: the published documentation site (docs.asymptotelabs.ai).