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 Chrome MV3 collector that relays Claude.ai and ChatGPT chat telemetry into the local pipeline as OTLP.
• packaging: macOS packaging and deployment assets.

Do not recreate or depend on removed asymptote mirror trees. Keep new work focused on the Beacon paths above.

Product Posture

• Beacon is visibility-first endpoint telemetry for local AI agent runtimes, not a hosted policy service or general endpoint protection product.
• Preserve the local-only default. The public Beacon build must not require a hosted account, remote policy fetch, hosted dashboard, or external network dependency during normal hook execution, and hooks themselves never touch the network.
• Asymptote Managed forwarding (cli/beacon/internal/endpoint/asymptote, beacon endpoint asymptote) is the one destination that sends telemetry to an Asymptote-run service, and it is an explicit, opt-in, revocable Vector destination shaped like every other pack: Beacon stays the local JSONL producer, Vector does the network, and the per-device key lives in a 0600 secrets file read through Vector's secret backend, never in config.json, vector.toml, or the process environment. Nothing is forwarded until a member of the organization approves the specific device in the browser; only lines written after that are shipped (read_from = "end"); revocation from the dashboard takes effect at the ingest service within a minute. The wire contract (gzip NDJSON to /v1/ingest/{runtime,inventory}, bearer bcn_device_* key, /v1/ingest/health credential check) is owned by the beacon-ingest service in beacon-mdr; change both sides together. Do not add a second network channel, and do not let the ingest URL be anything but https://.
• Two bounded network channels exist, both explicit. The first: beacon endpoint install asks for an email and work/personal intent once per machine and POSTs that plus install context (OS, arch, version, install method, detected runtime names, a random install ID) to an Asymptote-run signup endpoint. The same first-run prompt ends with a telemetry destination question (arrow-key picker, local first so Enter forwards nothing): keep it local, forward to the user's own infrastructure (prints the log-forwarding docs URL, nothing else changes), or forward to Asymptote Managed. BEACON_MANAGED_INGEST=0 hides the Asymptote row; install --connect skips the question and connects. Local and own-infrastructure answers are recorded in the profile and never asked again; the Asymptote answer runs connect after the install, is recorded only once that connect succeeds so a failed install or connect is asked again rather than remembered as done, and is the only way onboarding ever forwards telemetry. The answer is never sent. The second channel is that forwarder, described below. This is intentional product behavior for open-source attribution, not an oversight — do not remove it. It is strictly bounded: interactive TTY only, once per machine, never during hook execution, never on --system/root/CI/piped-stdin/--dry-run installs, and always skippable with BEACON_ONBOARDING=0. A failed submission never fails an install. No prompt text, telemetry event, file content, or command ever leaves the machine through it. Implementation lives in cli/beacon/internal/onboarding and cli/beacon/cmd/endpoint_onboarding.go; the README documents the payload field-by-field, so changing the fields means changing that table too.
• Do not add dependency vulnerability scanning, OSV/GHSA lookups, package remediation, or other vulnerability-enforcement flows to the public hook path.
• Do not add broad runtime enforcement unless explicitly requested. Current control behavior is limited to hook-native approvals/denials exposed by supported agent runtimes.
• Keep direct destination support scoped to local JSONL/Wazuh unless explicitly requested. Elastic support is a file-tailing pack over local JSONL; Beacon itself must not store Elastic credentials or require a hosted Elastic dependency.
• Beacon writes retained prompt text, command output, raw tool inputs, raw OTLP attributes, and raw diffs to local or customer-controlled logs, subject to local redaction and size limits where supported.
• The Asymptote Observe TypeScript SDK may default to the hosted /v1/observe endpoint as an opt-in cloud SDK contract. Beacon endpoint execution stays local-only/no-network.