Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

2.4 KB
Raw Blame

Agent instructions for agent-beacon

Beacon is a local-only endpoint telemetry agent for AI runtimes. Guidance for working in this repository lives in CONTRIBUTING.md (layout, workflow, validation) and CLAUDE.md (project scope, product posture, release process). Read those first for ordinary changes.

Verifying a change end to end

This repository ships a sandbox that runs a real Claude Code session against the Beacon under test and checks whether Beacon captured what happened. Use it when asked to verify that a change actually works, not just that it compiles and unit-tests pass.

Read beacon-sandbox/AGENTS.md before running any verification. It is the operating manual: prerequisites, which scenario to pick for which change, how to read a verdict, and the failure modes that look like Beacon bugs but are not.

Start with the prerequisite check, which is free and needs no sandbox:

cd beacon-sandbox && go run ./cmd/beacon-sandbox doctor

Two things to know before you run anything: a scenario costs real money (roughly $0.06 of sandbox plus a few cents of API), so tell the user before spending it; and the sandbox is Linux-only, so it cannot verify macOS-specific behavior.

Running the standard checks

Unit and integration tests for the shipping code, per CONTRIBUTING.md:

cd cli/beacon && go test ./...
cd cli/beacon && go test -race ./internal/endpoint/...
cd cli/beacon-hooks && go test ./...
cd collector-builder/exporter/beaconjsonexporter && go test ./...
cd pkg/asymptoteobserve && go test ./...
sh packaging/macos/test-endpoint-scripts.sh
sh packaging/macos/smoke-endpoint.sh

Each directory above is a separate Go module; run Go commands from inside the module you are changing.

The npm and bun subprojects are separate from the Go modules and are not covered by the commands above:

cd packages/asymptote-sdk-js && npm ci && npm test && npm run check
cd browser-extension && npm ci && npm run check && npm run test:unit
cd plugins/opencode-beacon && bun run check && bun test
cd plugins/cline-beacon && bun run check && bun test
cd plugins/pi-beacon && bun run check && bun test

The browser extension's Playwright replay e2e (npm test in browser-extension) needs openssl on PATH and a one-time npx playwright install chromium. It replays recorded SSE through the real extension in headless Chromium, so it is deterministic, needs no login, and costs nothing to run.