The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
beacon
Public CLI for Beacon Endpoint Agent.
Build
make build
Common Commands
./beacon endpoint install
./beacon login
./beacon whoami
./beacon endpoint status --json
./beacon endpoint connect
./beacon endpoint disconnect
./beacon endpoint discover --json
./beacon endpoint repair
./beacon traces
./beacon endpoint dashboard
./beacon endpoint uninstall --keep-logs
./beacon logout
Endpoint commands use per-user paths by default so hook and OTLP telemetry share
~/.beacon/endpoint/logs/runtime.jsonl. Use --system for root-managed
deployment paths.
With no --harness flag, install and repair discover local runtimes and configure
every integration Beacon can safely install. Pass an exact comma-separated list
to override discovery, or --harness all to force every installable integration.
Add optional Splunk HEC forwarding during install or repair:
./beacon endpoint install \
--splunk-hec-endpoint https://splunk.example:8088/services/collector \
--splunk-hec-token "$SPLUNK_HEC_TOKEN" \
--splunk-index beacon
The local JSONL runtime log remains enabled when Splunk forwarding is configured.
Cloud Agent Telemetry
Use beacon cloud helpers to configure provider-managed cloud agent sandboxes.
Claude Code on the web and Cursor cloud agents can forward Beacon JSONL to
customer-managed GCS or S3:
./beacon cloud gcs setup \
--project "$GCP_PROJECT" \
--bucket "$BEACON_CLOUD_GCS_BUCKET" \
--prefix "$BEACON_CLOUD_GCS_PREFIX" \
--service-account beacon-cloud-trace-uploader \
--apply \
--print-env
Copy the printed BEACON_CLOUD_GCS_BUCKET,
BEACON_CLOUD_GCS_PREFIX, and BEACON_CLOUD_GCS_CREDENTIALS_B64
values into the cloud agent environment.
For S3, use beacon cloud s3 setup --apply --print-env and copy the printed
BEACON_CLOUD_S3_* and AWS credential values instead.
For both destinations, also set:
BEACON_ORIGIN=cloud
BEACON_RUN_PROVIDER=claude_code_web # or cursor_cloud
BEACON_RUN_EPHEMERAL=true
BEACON_CLOUD_USER_ID_HASH=<stable-user-or-test-id>
For Cursor Cloud Agents, keep the repository-owned setup in .cursor/:
.cursor/environment.json
.cursor/hooks.json
.cursor/install.sh
.cursor/start.sh
The install script builds the current branch by default, or downloads a release
when BEACON_VERSION is set. This repository commits its .cursor/hooks.json
(generated with beacon cloud cursor print-hooks) so cloud agents on any branch
test that branch's hooks. Other repositories don't need to commit anything: the
install script from beacon cloud cursor print-setup writes the hooks at Build
time and excludes them from git.
For Claude Code on the web, generate the setup script for a Beacon release and paste it into the provider's cloud setup field:
./beacon cloud claude-web print-setup --version vX.Y.Z
The setup script installs beacon-hooks into the cloud sandbox and uploads a
gzip-compressed /tmp/beacon/runtime.jsonl snapshot to object storage. Claude web writes
.claude/settings.local.json inside the sandbox clone. Cursor cloud uses
.cursor/environment.json to install Beacon and committed project-level
.cursor/hooks.json because Cursor cloud only runs repository project hooks.
<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-claude_code_web-<claude-session-id>.jsonl.gz
<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-cursor_cloud-<generated-or-explicit-run-id>.jsonl.gz
Cloud network access must allow the selected destination: both
oauth2.googleapis.com and storage.googleapis.com for GCS, or
s3.<region>.amazonaws.com for S3. Cursor cloud project hooks capture follow-up
prompts, tool activity, shell execution, file reads and edits, subagents, and
compaction after the writable environment becomes available. Early bootstrap
turns can precede project-hook activation. If you are testing unreleased Beacon
changes, build the feature branch in the setup script instead of using
print-setup --version.
Add optional Falcon LogScale HEC forwarding during install or repair:
./beacon endpoint repair \
--falcon-hec-endpoint "$LOGSCALE_URL/api/v1/ingest/hec" \
--falcon-hec-token "$LOGSCALE_INGEST_TOKEN" \
--falcon-source beacon-endpoint-agent \
--falcon-sourcetype json
Beacon sends LogScale HEC requests with Authorization: Bearer <ingest token>.
The HEC event value is the normalized Beacon event object with an ISO
@timestamp nested inside it for LogScale's built-in JSON parser. The optional
--falcon-index flag maps to a LogScale repository and is usually only needed
with organization or system multi-repository ingest tokens; repository-scoped
ingest tokens already select the target repository.
Dashboard
Use the full-screen terminal browser for a local trace list, search, event filters, and event details:
./beacon traces
The browser reads the same local runtime JSONL and trace index as the commands
under beacon endpoint traces. With redirected input or output it falls back to
a bounded tab-separated list, while endpoint traces list, search, and show
remain available for scripting and JSON output.
./beacon endpoint dashboard
./beacon endpoint dashboard --addr 127.0.0.1:8765
./beacon endpoint dashboard --open
The dashboard reads the configured runtime JSONL log and serves a local, read-only view on loopback. It has no external network dependency during normal use.
Use ./beacon token-usage for the same token data in the terminal. Claude Code
and supported Codex versions share the canonical gen_ai.usage schema; Codex
turn traces add per-session and per-model counts, and its metadata-only
SessionStart hook enables local OS-user rollups.
Use the search bar to find events by action, command, file path, MCP tool, approval decision, repository, session, or message. Quick filters surface high-severity events, failures, approvals, MCP activity, file changes, and events that may need review.
Agent Telemetry in CI
Use beacon ci exec to collect Claude Code or Codex OpenTelemetry for a single
CI command without installing a persistent endpoint service or changing local
developer configuration:
./beacon ci exec -- claude --print "Summarize this repository in one sentence"
For actions or workflows that launch an agent internally, use CI session mode:
./beacon ci start --harness claude,codex
# run one or more agent CI steps here
./beacon ci finish --min-events 1
Beacon starts the bundled beacon-otelcol in the foreground, writes a
job-scoped collector config under $RUNNER_TEMP/beacon, configures supported
agent harnesses to export OTLP to the local collector, validates that structured
Beacon events reached the runtime JSONL log, and writes normalized JSONL for
artifact upload or customer-managed forwarding.
ci exec injects telemetry only into its child process. ci start writes
session exports to $GITHUB_ENV when run through the composite action, which
lets later uses: actions inherit Claude Code environment variables or a
generated Codex CODEX_HOME.
Validate an existing CI artifact explicitly:
./beacon ci validate \
--log-path "$RUNNER_TEMP/beacon/runtime.jsonl" \
--min-events 1
Captured events carry the GitHub Actions run context (origin, run.provider,
run.repository, run.branch, run.run_id, run.run_attempt, run.workflow,
run.job, run.event_name, run.commit, run.actor, and run.pr_number on
pull-request events) so they can be correlated per-workflow and per-PR
downstream.
Upload the log from GitHub Actions for customer-controlled retention:
- name: Run Claude with Beacon telemetry
run: beacon ci exec -- claude --print "Summarize this repository"
- name: Upload Beacon telemetry
if: always()
uses: actions/upload-artifact@v4
with:
name: beacon-runtime-log-${{ github.job }}-${{ strategy.job-index }}
path: ${{ runner.temp }}/beacon/runtime.jsonl
Upload only the runtime.jsonl file (as above), not the whole
${{ runner.temp }}/beacon directory. When forwarding is configured, Beacon
keeps the SIEM token in the runner environment and writes only collector
environment references into otelcol.yaml; excluding the collector config from
artifacts still avoids exposing forwarding endpoints or local collector details.
The JSONL artifact is the universal CI export contract. Existing destination packs can consume the same file after it is downloaded or copied into the customer-managed forwarder path:
| Destination | CI export path |
|---|---|
| Wazuh | Download the artifact and tail it with the Wazuh localfile pack. |
| Elastic | Download the artifact and ingest it with Filebeat or Elastic Agent pack assets. |
| Datadog | Download the artifact and tail it with the Datadog Agent log collection pack. |
| Sumo Logic | Download the artifact for Vector-based forwarding, or use --upload when object storage is the handoff point. |
| Rapid7 | Download the artifact for Vector/webhook forwarding. |
| S3 | Use direct --upload s3 in CI, or upload/download the artifact manually. |
| CloudWatch Logs | Download the artifact and forward with the Vector CloudWatch pack. |
| GCS | Use direct --upload gcs in CI, or upload/download the artifact manually. |
| Sentinel | Download the artifact and ingest with the Azure Monitor Agent/DCR pack. |
| Splunk | Use direct --forward splunk, or ingest the JSONL artifact with an existing Splunk pipeline. |
| Falcon LogScale | Use direct --forward falcon, or ingest the JSONL artifact with an existing pipeline. |
Forwarding to a customer-managed SIEM
Because CI runners are ephemeral, the local JSONL is destroyed when the runner
is torn down. In addition to (or instead of) uploading an artifact, ci exec
can forward events from its ephemeral collector to a customer-managed Splunk or
CrowdStrike Falcon LogScale HEC endpoint before teardown:
export BEACON_CI_SPLUNK_HEC_TOKEN="$SPLUNK_HEC_TOKEN" # from CI secrets
beacon ci exec \
--forward splunk \
--forward-endpoint "https://splunk.example:8088/services/collector" \
-- claude --print "Summarize this repository"
- The token is read from the environment only
(
BEACON_CI_SPLUNK_HEC_TOKEN/BEACON_CI_FALCON_HEC_TOKEN) and is never accepted as a flag, so it does not appear in CI process listings. The endpoint may be passed via--forward-endpointorBEACON_CI_SPLUNK_HEC_ENDPOINT/BEACON_CI_FALCON_HEC_ENDPOINT. - Forwarding is best-effort: a SIEM delivery failure does not fail the job, and Beacon still writes the local JSONL.
- Beacon remains a local JSONL producer; egress goes only to infrastructure the customer already operates.
Uploading CI JSONL to object storage
For CI runners that should hand off telemetry through object storage, ci exec
can upload the completed runtime.jsonl after telemetry validation:
export BEACON_CI_S3_BUCKET="my-beacon-telemetry"
export BEACON_CI_S3_PREFIX="github-actions"
beacon ci exec --upload s3 -- claude --print "Summarize this repository"
export BEACON_CI_GCS_BUCKET="my-beacon-telemetry"
export BEACON_CI_GCS_PREFIX="github-actions"
beacon ci exec --upload gcs -- claude --print "Summarize this repository"
- S3 upload uses
aws s3 cpand the standard AWS credential provider chain. - GCS upload uses
gcloud storage cpwhen available, falling back togsutil cp. - Beacon strips common AWS and Google credential environment variables from the child agent process, while keeping them available to the post-run uploader.
- Each session uploads under its own folder,
<start time in Unix nanoseconds>-<8 random hex characters>, chosen when the session starts and reused byci finish. Keys are<prefix>/<repository>/<run_id>/<run_attempt>/<job>/<session>/runtime.jsonlin GitHub Actions and<prefix>/ci/<session>/runtime.jsonlelsewhere, so jobs, matrix legs and repeated sessions in one run never overwrite each other. Earlier versions wrote every session in a run to<prefix>/<repository>/<run_id>/<run_attempt>/runtime.jsonl.
By default ci exec fails the step when no Beacon events reach the runtime log,
which surfaces a broken telemetry pipeline. Pass --require-telemetry=false to
downgrade that to a warning when you do not want telemetry health to gate the
build.
GitHub Action
A composite action wraps binary resolution, ci exec, session
start/finish, and artifact upload. For a direct command, use the default
exec mode:
- name: Run Claude with Beacon telemetry
uses: asymptote-labs/agent-beacon@<tag>
with:
command: claude --print "Summarize the changes in this pull request"
The action downloads a pinned Beacon release and verifies it against the
release checksums.txt before running. When the action is invoked from a
version tag, that tag is used as the default Beacon CLI release; set version
explicitly or use binary-path when testing from a branch or local checkout,
or on air-gapped and self-hosted runners that already provide beacon and
beacon-otelcol. See
examples/github-actions/binary-path-telemetry.yml
for a complete reference workflow.
It uploads the runtime JSONL log as an artifact by default.
To wrap a third-party agent action, split the action into start and finish
steps:
- name: Start Beacon telemetry
uses: asymptote-labs/agent-beacon@<tag>
with:
mode: start
harnesses: claude,codex
- name: Run agent review action
uses: vendor/agent-review-action@main
- name: Finish Beacon telemetry
if: always()
uses: asymptote-labs/agent-beacon@<tag>
with:
mode: finish
min-events: "1"
For Codex-based actions that accept a custom home directory, pass the generated Codex home output:
- name: Start Beacon telemetry
id: beacon
uses: asymptote-labs/agent-beacon@<tag>
with:
mode: start
harnesses: codex
- uses: openai/codex-action@main
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
codex-home: ${{ steps.beacon.outputs.codex-home }}
prompt: "Review this pull request"
To forward to a customer-managed SIEM, set forward/forward-endpoint on
exec or start and provide the token through a job- or workflow-level
environment variable from a secret:
jobs:
claude-telemetry:
runs-on: ubuntu-latest
env:
BEACON_CI_SPLUNK_HEC_TOKEN: ${{ secrets.SPLUNK_HEC_TOKEN }}
steps:
- uses: asymptote-labs/agent-beacon@<tag>
with:
command: claude --print "Summarize this repository"
forward: splunk
forward-endpoint: https://splunk.example:8088/services/collector
To upload the completed JSONL artifact to object storage, configure cloud
credentials at the job level and set upload:
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ secrets.BEACON_TELEMETRY_ROLE_ARN }}
aws-region: us-east-1
- name: Run Claude with Beacon telemetry
uses: asymptote-labs/agent-beacon@<tag>
env:
BEACON_CI_S3_BUCKET: my-beacon-telemetry
BEACON_CI_S3_PREFIX: github-actions
with:
command: claude --print "Summarize this repository"
upload: s3
See examples/github-actions/claude-code-telemetry.yml,
examples/github-actions/claude-security-review-session.yml,
examples/github-actions/codex-action-session.yml,
examples/github-actions/s3-upload-telemetry.yml,
examples/github-actions/gcs-upload-telemetry.yml,
examples/github-actions/s3-gcs-upload-telemetry.yml,
examples/github-actions/splunk-forward-telemetry.yml,
examples/github-actions/falcon-forward-telemetry.yml,
and examples/github-actions/binary-path-telemetry.yml
for complete reference workflows.
Wazuh
./beacon endpoint wazuh print-config
./beacon endpoint wazuh install-pack --output ./beacon-wazuh
./beacon endpoint wazuh validate
Sumo Logic
./beacon endpoint sumo print-config
./beacon endpoint sumo install-pack --output ./beacon-sumo-pack
./beacon endpoint sumo validate
The Sumo pack keeps Beacon as a local JSONL producer and documents forwarding
runtime.jsonl into a customer-managed Sumo Hosted Collector HTTP Logs &
Metrics Source. Use a tailing forwarder for production so offsets are
checkpointed and the whole file is not repeatedly uploaded.
Rapid7 InsightIDR
./beacon endpoint rapid7 print-config
./beacon endpoint rapid7 install-pack --output ./beacon-rapid7-pack
./beacon endpoint rapid7 validate
The Rapid7 pack keeps Beacon as a local JSONL producer and documents forwarding
runtime.jsonl into a Rapid7 InsightIDR Custom Logs webhook as NDJSON. Store the
webhook URL in your customer-managed shipper or deployment tooling, not in
Beacon endpoint configuration.
AWS S3
./beacon endpoint s3 print-config
./beacon endpoint s3 install-pack --output ./beacon-s3-pack
./beacon endpoint s3 validate
The S3 pack keeps Beacon as a local JSONL producer and documents forwarding
runtime.jsonl and the sibling inventory_state.jsonl into separate
runtime/ and inventory/ S3 prefixes with a customer-managed Vector host
agent. Store AWS credentials, profiles, IAM roles, bucket policies, lifecycle
rules, and encryption settings in AWS, Vector, or deployment tooling, not in
Beacon endpoint configuration.
AWS CloudWatch Logs
./beacon endpoint cloudwatch print-config
./beacon endpoint cloudwatch install-pack --output ./beacon-cloudwatch-pack
./beacon endpoint cloudwatch validate
The AWS CloudWatch Logs pack keeps Beacon as a local JSONL producer and
documents forwarding runtime.jsonl into a CloudWatch Logs log group with a
customer-managed Vector host agent. Store AWS credentials, profiles, IAM roles,
log group retention, stream naming, and encryption settings in AWS, Vector, or
deployment tooling, not in Beacon endpoint configuration.
Google Cloud Storage
./beacon endpoint gcs print-config
./beacon endpoint gcs install-pack --output ./beacon-gcs-pack
./beacon endpoint gcs validate
The GCS pack keeps Beacon as a local JSONL producer and documents forwarding
runtime.jsonl and the sibling inventory_state.jsonl into separate
runtime/ and inventory/ folders below one root GCS prefix.
The macOS package includes
/opt/beacon/jamf/claude/gcs/{install-forwarder.sh,run-forwarder.sh,repair-hooks-and-forwarder.sh}
and runs bundled Vector as com.beacon.endpoint.gcs-forwarder. Vector 0.56
supports service-account JSON and GCE metadata credentials; on a normal Mac,
deliver the JSON through MDM or secret tooling to a root-owned path outside
Beacon-managed directories and reference it with
GOOGLE_APPLICATION_CREDENTIALS. Do not rely on interactive gcloud ADC or
Workload Identity Federation for the launchd service. An endpoint writer with
roles/storage.objectCreator cannot list or read objects, so use a separate
reader identity for validation.
Microsoft Sentinel
./beacon endpoint sentinel print-config
./beacon endpoint sentinel install-pack --output ./beacon-sentinel-pack
./beacon endpoint sentinel validate
The Sentinel pack keeps Beacon as a local JSONL producer and documents
forwarding runtime.jsonl through Azure Monitor Agent, a Data Collection Rule,
and a BeaconRuntime_CL custom Log Analytics table. Store Azure workspace,
DCR, endpoint, and credential details in Azure or customer-managed deployment
tooling, not in Beacon endpoint configuration.
Beacon Cloud
./beacon endpoint connect
./beacon endpoint status --json | jq .managed_ingest
./beacon endpoint disconnect
Beacon Cloud is the Beacon-hosted forwarding destination. User-mode connect
uses the signed-in account to authorize a separate device key; system mode keeps
browser approval. The account token is never given to Vector. Connect stores the
device key in a 0600 secrets file and runs Vector as the
com.beacon.endpoint.asymptote-forwarder (launchd) or
beacon-asymptote-forwarder.service (systemd) service. Beacon stays the local
JSONL producer and Vector does the network. Standard privacy forwards locally
sanitized retained content; --privacy-mode metadata-only strips retained text,
raw fields, diffs, inventory content, and MCP definitions locally before upload.
Runtime forwarding starts at the end of the existing runtime log, while inventory
starts at the beginning of inventory_state.jsonl to send the endpoint's current
inventory baseline. Revoking the device stops ingestion within about a minute.
Vector 0.50 or newer is required: /opt/beacon/bin/vector from
the signed package, the beacon-vector keg that brew install beacon pulls in on
macOS, any other Vector 0.50+ already on the machine, or the Linux package from
vector.dev. The Homebrew mirror is named beacon-vector rather than vector, and
keeps its binary in libexec, because Homebrew allows a single keg named vector
and a single bin/vector symlink: under its own name it installs alongside a Vector
from vectordotdev/brew instead of refusing to install at all.
The same pack is available for running Vector by hand:
./beacon endpoint asymptote print-config
./beacon endpoint asymptote install-pack --output ./beacon-asymptote-pack
./beacon endpoint asymptote validate
See https://docs.asymptotelabs.ai/log-forwarding/asymptote for the wire contract, what leaves the machine, and revocation.
Optional Integrations
./beacon endpoint hooks install --harness cursor
./beacon endpoint hooks status --harness cursor
./beacon endpoint hooks install --harness claude --level user
./beacon endpoint hooks status --harness claude
./beacon endpoint hooks install --harness opencode
./beacon endpoint hooks status --harness opencode
./beacon endpoint hooks install --harness grok
./beacon endpoint hooks status --harness grok
./beacon endpoint hooks install --harness muse
./beacon endpoint hooks status --harness muse
./beacon endpoint hooks install --harness openhands --level project
./beacon endpoint hooks status --harness openhands --level project
./beacon endpoint hooks install --harness kiro
./beacon endpoint hooks status --harness kiro
./beacon endpoint hooks install --harness dsh
./beacon endpoint hooks status --harness dsh
./beacon endpoint dsh status
./beacon endpoint dsh sync
./beacon endpoint hooks install --harness hermes
./beacon endpoint hooks status --harness hermes
./beacon endpoint hooks install --harness devin-cli --level project
./beacon endpoint hooks status --harness devin-cli --level project
./beacon endpoint hooks install --harness devin-desktop --level user
./beacon endpoint hooks status --harness devin-desktop --level user
./beacon endpoint install --harness claude,codex,devin-cli,devin-desktop
./beacon endpoint integrations claude-cowork setup --endpoint https://collector.example.com --open
./beacon endpoint integrations claude-cowork setup --ngrok --open
./beacon endpoint integrations claude-cowork validate --since 10m
./beacon endpoint integrations openclaw print-config
./beacon endpoint integrations openclaw status
./beacon endpoint integrations openclaw validate --since 10m
./beacon endpoint integrations vscode setup
./beacon endpoint integrations vscode status
./beacon endpoint integrations vscode validate --since 10m
./beacon endpoint hooks install --harness vscode --level project
The opencode integration installs Beacon's owned local plugin at
~/.config/opencode/plugins/beacon.ts. It captures prompts, completed assistant
text/reasoning, model usage, correlated tool input/results, commands, file,
web/MCP, approval, and lifecycle events through OpenCode's plugin hooks. Beacon
handles normalization, retention, redaction, event-size controls, and JSONL
output locally. For local troubleshooting, set BEACON_OPENCODE_DEBUG=1 in the
environment that launches opencode to emit best-effort plugin debug logs.
Claude Code supports two Beacon setup paths. beacon endpoint install --harness claude
configures Claude Code's local OpenTelemetry export to Beacon's collector.
beacon endpoint hooks install --harness claude writes command hooks into
~/.claude/settings.json or .claude/settings.json and sends normalized events
directly to the local runtime JSONL log. The hook path is useful when an
Anthropic organization policy blocks third-party telemetry export. Claude Code
hooks are intentionally not included in beacon endpoint hooks install --all in
this release; install them explicitly with --harness claude.
The Grok Build integration writes Beacon's owned local hook file at
~/.grok/hooks/beacon-endpoint.json for user-level installs or .grok/hooks/beacon-endpoint.json
for project-level installs. Project hooks require trusting the project in Grok
with /hooks-trust before they execute.
The Muse Code integration writes Beacon's owned managed hooks file at
$XDG_CONFIG_HOME/muse/beacon-endpoint-hooks.json (or ~/.config/muse/...) and
points Muse's own settings.json at it with the managed_hooks_path key. Both
halves are required: a hooks file nothing points at is never read, and a
managed_hooks_path with no file behind it registers nothing, so status checks
and prints both. Muse reads exactly one managed hooks file, so install refuses
rather than replacing a registration that is already somebody else's, and
uninstall clears the key only while it still names Beacon's file. User scope
only -- Muse's project .muse/hooks.json is ignored by the shipping build, so a
project install would report success and collect nothing.
The OpenHands integration merges Beacon's six hook commands into the
.openhands/hooks.json the runtime already reads, at <repo>/.openhands/hooks.json
for project-level installs or $OH_PERSISTENCE_DIR/~/.openhands/hooks.json for
user-level ones. Hooks you already have are preserved, including their matchers,
timeouts, and fields Beacon has no model for. Project scope is the one every host
reads: OpenHands takes the first hooks file it finds rather than merging the two,
so a repository file shadows the user-level one entirely, and the agent server
behind the CLI and the GUI never consults the user-level file at all. The file has
a closed schema that fails silently -- an unknown top-level key, a second spelling
of one event, or a top-level event added beside a legacy {"hooks": {...}} wrapper
all end with hooks not running and no error -- so install refuses a file that
already breaks one of those rather than reporting a success that collects nothing.
The Kiro integration writes one hook file of Beacon's own,
beacon-endpoint.json, into the .kiro/hooks/ directory Kiro scans -- at
<repo>/.kiro/hooks/ for project-level installs or $KIRO_HOME/~/.kiro/hooks/
for user-level ones. Kiro loads every .json file in that directory, so the
install is additive by construction: your own hook files are never read,
rewritten or deleted, and uninstall removes only the file Beacon wrote. Beacon
does claim that one filename -- a file at it holding a hook Beacon did not write
is refused rather than overwritten, with an error naming the hook. Both scopes
are live at once, because Kiro merges hook files across scopes rather than taking
the first it finds, so one install covers the Kiro IDE and the Kiro CLI and a
user-scope install keeps working inside a repository with hooks of its own.
Kiro's hook contract is exit codes rather than response objects, so Beacon writes
nothing to stdout there: on SessionStart and UserPromptSubmit Kiro adds a
hook's stdout to the model's context, and an observing hook has nothing to say to
the model. The one exception is the optional policy seam, whose deny is exit code
2 with the reason on stderr -- Kiro's documented way to block a tool call.
The DeepSeek Harness integration is the one install that takes two files,
because dsh reads no hooks file until something mounts a reader at it: the
harness composes itself from a plugin tree, and @deepseek-ai/dsh-hooks-claude-code
-- the Claude Code hook bridge DeepSeek publishes for every dsh release -- is not
in the default tree. So Beacon writes $DSH_HOME/beacon-endpoint-hooks.json, a
hooks file it owns outright, and adds one row to $DSH_HOME/cordis.patch.yml
mounting the bridge at it. $DSH_HOME defaults to ~/.dsh. The bridge does not
ship with the CLI, so it must be installed into each profile at exactly the dsh
version (dsh plugin --profile <name> add @deepseek-ai/dsh-hooks-claude-code@<v> @deepseek-ai/dsh-hook-protocol@<v>), and install refuses when nothing can load
it. The home-level patch
layer applies over every profile, so one install covers the CLI, Web, ACP and SDK
surfaces; there is no project scope, because the bridge's configPath is
process-level and a repository has nowhere to mount from, so --level project is
refused with that explanation rather than silently becoming a machine-wide
install.
Beacon also reads DeepSeek Harness' native committed session records from
$DSH_HOME/sessions with beacon endpoint dsh sync. That poll path is local
and offline; it backfills assistant text/reasoning, structured failed-tool
status, and token usage that the hook bridge does not expose. Hook install also
writes a Beacon-owned local skill at $DSH_HOME/skills/beacon-endpoint/SKILL.md
so dsh can check beacon endpoint dsh status and run a workspace-scoped sync
when asked.
The patch file is the user's own, and is edited as a document rather than
rewritten: parsed into a YAML node tree, one self-contained element appended or
removed, re-encoded from the same tree, so comments, quoting and !!js
expressions survive. Beacon refuses rather than rewriting a patch file it cannot
parse, one that is not a list of entries, or an insert element carrying its row
alongside rows it did not write. An uninstall that would leave the file empty
removes it instead: an empty or comments-only patch file fails dsh boot, while
an absent one is skipped cleanly. hooks status and endpoint inventory report
both files, because installed is the conjunction of the two -- a hooks file with
nothing mounted at it is a file nothing reads, and a mount pointing at a missing
hooks file registers nothing.
The Kimi Code integration registers in the [[hooks]] array of the runtime's
own $KIMI_CODE_HOME/config.toml (default ~/.kimi-code), which is the same
file that holds [providers.<name>].api_key in plain text. Beacon is a guest in
it, so it appends its entries to the end of the document and never re-serializes:
every byte above the block is left exactly as it was found, which is what keeps a
secret from being rewritten, re-quoted or reordered by a round trip. Appending is
sound rather than convenient -- an array-of-tables header at the end of a TOML
document opens a new table and cannot change what precedes it -- and every write
is parsed back and compared against the intended result before it replaces the
file, so a scanning or quoting mistake fails the install instead of damaging a
config. Beacon refuses a config.toml it cannot parse, because Kimi Code will not
start on one, and refuses one whose hooks key is an inline array, because TOML
forbids appending [[hooks]] after that; endpoint discover reports the second
case before an install meets it. There is no project scope: Kimi Code reads one
user-level config file, so --level project is refused with that explanation
rather than becoming a machine-wide install.
Detection and removal go by the hook command rather than by the comment Beacon
writes above its block, and that is a reachable case rather than caution: Kimi
Code's legacy migration from kimi-cli rewrites config.toml by serializing the
merged config, keeping the [[hooks]] entries and dropping every comment. Beacon
writes nothing to a Kimi Code hook's stdout, because on UserPromptSubmit a
hook's stdout is appended to the model's context -- the optional policy seam
denies with exit code 2 and the reason on stderr, which the runtime checks before
it parses stdout at all. Kimi Code is one of the few runtimes that reports real
operator approval decisions, over a PermissionRequest/PermissionResult pair;
a deny raised while answering the second cannot take effect, because that event
is observation-only, so the seam declines to raise one there rather than writing
denial telemetry for a call that was not denied.
The Hermes Agent integration writes shell-hook entries into
~/.hermes/config.yaml. Hermes prompts for first-use consent for each
(event, command) pair; for non-interactive gateway, cron, or CI runs, set
HERMES_ACCEPT_HOOKS=1, start Hermes with --accept-hooks, or configure
hooks_auto_accept: true in the Hermes config.
The Devin CLI integration writes Claude-compatible command hooks for Devin for
Terminal. devin remains a legacy alias for devin-cli. Project-level installs
use .devin/hooks.v1.json; user-level installs use
~/.config/devin/config.json under the hooks key. The hooks invoke Beacon's
local Go hook binary and write normalized prompt, tool, command, file, approval,
and session events to the configured runtime JSONL log.
Devin Desktop is exposed separately as devin-desktop and uses Devin
Desktop-compatible Cascade/Windsurf hooks. User-level installs write
~/.codeium/windsurf/hooks.json; project-level installs write
.windsurf/hooks.json, which may also affect Windsurf/Cascade in that
workspace. Beacon installs visibility-only hooks for prompt submission, file
writes, command execution, MCP tool use, and file reads; the hooks do not block
or enforce policy. After installation, generate a Devin Desktop event and check
the Beacon runtime log to validate that the Desktop app executed the hook file.
The main beacon endpoint install --harness ... path also handles hook-backed
Devin targets, so --harness claude,codex,devin-cli,devin-desktop configures
OTLP-backed Claude/Codex telemetry and Devin hook telemetry in one flow.
Claude Cowork monitoring is configured in the Claude admin console at
https://claude.ai/admin-settings/cowork. The OTLP endpoint must be reachable
by Claude Cowork, so use a durable public HTTPS Collector endpoint for ongoing
monitoring. The --ngrok mode is for short-lived local testing and prints an
authenticated tunnel URL plus the matching Authorization header.
Cowork uses the shared Claude normalizer for prompts, assistant responses,
approvals, commands, files, MCP activity, session lifecycle, model usage,
tokens, and runtime-reported cost. A Desktop-started task may still carry
origin=cloud when cowork.surface=remote; endpoint hostname and OS identify
the Beacon collector machine. Cowork may expose only an opaque user.id, which
Beacon preserves without inventing a display identity.
OpenClaw Gateway monitoring is configured in OpenClaw's local Gateway config
with the diagnostics-otel plugin enabled. Beacon prints a local OTLP/HTTP
configuration that points OpenClaw at the endpoint collector. OpenClaw does not
export raw prompt, response, tool, or system-prompt content unless
diagnostics.otel.captureContent.* is explicitly enabled.
VS Code Copilot monitoring is configured in VS Code settings and exports OTLP/HTTP to Beacon's local collector. For a first-time local setup, install the endpoint collector with the VS Code harness, reload VS Code, and validate recent activity:
./beacon endpoint install --user --harness vscode
./beacon endpoint integrations vscode validate --user --since 10m
VS Code hook support is optional and depends on the Chat: Use Hooks setting,
which may be managed by the organization. When enabled, project-level hooks use
.github/hooks/beacon.json:
cd /path/to/workspace
beacon endpoint hooks install --harness vscode --level project --user
OTel-derived events use harness.name=vscode_copilot; hook-derived events use
harness.name=vscode.
Test
go test ./...
go test -race ./internal/endpoint/...