beacon endpoint hooks

Command Overview

Beacon can install hook-based endpoint telemetry for supported agent harnesses. The hook adapter emits local Beacon endpoint events for sessions, prompt submission, tool use, command execution, MCP-like tool activity, approval decisions, permissions, diffs, and file edits where each runtime exposes those hook payloads.

Command syntax

beacon endpoint hooks [command]

Commands

beacon endpoint hooks install

Install endpoint hooks for supported hook runtimes.

beacon endpoint hooks status

Show endpoint hook integration status.

beacon endpoint hooks uninstall

Remove Beacon hook entries while preserving non-Beacon hooks.

Paths

Runtime	User-level config	Project-level config	Hook binary	Runtime log
Antigravity CLI	`~/.gemini/config/hooks.json`	`./.agents/hooks.json`	`~/.beacon/endpoint/hooks/beacon-hooks`	`~/.beacon/endpoint/logs/runtime.jsonl`
Claude Code	`~/.claude/settings.json`	`./.claude/settings.json`	`~/.beacon/endpoint/hooks/beacon-hooks`	`~/.beacon/endpoint/logs/runtime.jsonl`
Cursor	`~/.cursor/hooks.json`	`./.cursor/hooks.json`	`~/.beacon/endpoint/hooks/beacon-hooks`	`~/.beacon/endpoint/logs/runtime.jsonl`
Devin CLI	`~/.config/devin/config.json`	`./.devin/hooks.v1.json`	`~/.beacon/endpoint/hooks/beacon-hooks`	`~/.beacon/endpoint/logs/runtime.jsonl`
Devin Desktop	`~/.codeium/windsurf/hooks.json`	`./.windsurf/hooks.json`	`~/.beacon/endpoint/hooks/beacon-hooks`	`~/.beacon/endpoint/logs/runtime.jsonl`
Factory Droid	`~/.factory/settings.json`	`./.factory/settings.json`	`~/.beacon/endpoint/hooks/beacon-hooks`	`~/.beacon/endpoint/logs/runtime.jsonl`
Grok Build	`~/.grok/hooks/beacon-endpoint.json`	`./.grok/hooks/beacon-endpoint.json`	`~/.beacon/endpoint/hooks/beacon-hooks`	`~/.beacon/endpoint/logs/runtime.jsonl`
Hermes Agent	`~/.hermes/config.yaml`	Not supported	`~/.beacon/endpoint/hooks/beacon-hooks`	`~/.beacon/endpoint/logs/runtime.jsonl`
OpenCode	`~/.config/opencode/plugins/beacon.ts`	`./.opencode/plugins/beacon.ts`	`~/.beacon/endpoint/hooks/beacon-hooks`	`~/.beacon/endpoint/logs/runtime.jsonl`

In system mode, the hook binary is written under /Library/Application Support/Beacon/Endpoint/hooks/ and the default runtime log is /var/log/beacon-agent/runtime.jsonl.

Flags

Flag	Description
`--harness <list>`	Comma-separated hook harnesses, such as `antigravity`, `claude`, `cursor`, `devin-cli`, `devin-desktop`, `factory`, `grok`, `hermes`, `opencode`, or `antigravity,claude,cursor,devin-cli,devin-desktop,factory,grok,hermes,opencode`. `devin` remains a legacy alias for `devin-cli`; `hermes-agent` maps to `hermes`. Defaults to `cursor`
`--level <level>`	Hook install level: `user` or `project`
`--user`	Use per-user endpoint paths. Enabled by default
`--system`	Use system endpoint paths and launch daemon
`--log-path <path>`	Runtime JSONL log path
`--json`	Print status as JSON. Status only
`--all`	Target or show all supported hook harnesses
`--dry-run`	Print planned install or uninstall actions without changing hook files. Install and uninstall only

Restart Antigravity CLI, Claude Code, Cursor, Devin CLI, Devin Desktop, Factory Droid, Grok Build, Hermes Agent, or OpenCode after installing or removing hooks so the updated hook configuration is picked up by new sessions.

Beacon validates the embedded beacon-hooks binary before writing hook configuration. If install fails with an architecture validation error, upgrade Beacon or reinstall the platform-specific release archive for the host, then run the hook install command again.

beacon endpoint hooks install

beacon endpoint hooks install installs hook-based Beacon telemetry for supported harnesses.

Install runtime hooks

beacon endpoint hooks install --harness cursor

The hook adapter records local endpoint events for sessions, prompt submission, tool use, command execution, MCP-like tool activity, approval decisions, permissions, diffs, and file edits where the selected runtime exposes those hook payloads. Antigravity hooks cover PreInvocation, UserPromptSubmit, PreToolUse, PostToolUse, PostInvocation, and Stop. Claude Code hooks cover SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, SubagentStart, SubagentStop, PermissionRequest, and SessionEnd. Devin CLI hooks cover SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop, and SessionEnd. Devin Desktop hooks use Cascade/Windsurf payloads for prompt submission, file writes, command execution, MCP tool use, and file reads. Factory hooks cover SessionStart, UserPromptSubmit, PostToolUse for write/edit/create operations, Stop, and SessionEnd. Grok Build hooks cover SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, and SessionEnd. Hermes Agent hooks cover session lifecycle, pre_llm_call, pre_tool_call, post_tool_call, approval request and response, and subagent stop events. OpenCode hooks use Beacon’s managed local plugin to forward chat.message, session, command, permission, diff, and error events.

Examples

Install Cursor hooks at the user level:

Install Cursor hooks at the user level

beacon endpoint hooks install --harness cursor

Install Antigravity hooks at the user level:

Install Antigravity hooks at the user level

beacon endpoint hooks install --harness antigravity

Install Claude Code hooks at the user level:

Install Claude Code hooks at the user level

beacon endpoint hooks install --harness claude

Install Antigravity hooks at the project level:

Install Antigravity hooks at the project level

beacon endpoint hooks install --harness antigravity --level project

Install Cursor hooks at the project level:

Install Cursor hooks at the project level

beacon endpoint hooks install --harness cursor --level project

Install Devin CLI hooks at the user level:

Install Devin CLI hooks at the user level

beacon endpoint hooks install --harness devin-cli

Install Devin CLI hooks at the project level:

Install Devin CLI hooks at the project level

beacon endpoint hooks install --harness devin-cli --level project

Install Devin Desktop hooks at the user level:

Install Devin Desktop hooks at the user level

beacon endpoint hooks install --harness devin-desktop

Install Devin Desktop hooks at the project level:

Install Devin Desktop hooks at the project level

beacon endpoint hooks install --harness devin-desktop --level project

Install Factory hooks at the user level:

Install Factory hooks at the user level

beacon endpoint hooks install --harness factory

Install OpenCode hooks at the user level:

Install OpenCode hooks at the user level

beacon endpoint hooks install --harness opencode

Install Grok Build hooks at the user level:

Install Grok Build hooks at the user level

beacon endpoint hooks install --harness grok

Install Hermes Agent hooks at the user level:

Install Hermes Agent hooks at the user level

beacon endpoint hooks install --harness hermes

Install Grok Build hooks at the project level:

Install Grok Build hooks at the project level

beacon endpoint hooks install --harness grok --level project

Project-level Grok Build hooks require /hooks-trust in Grok before they execute. Hermes Agent hooks support user-level config only. beacon endpoint hooks install --harness hermes --level project returns an error instead of writing project files. Install all supported hook integrations:

Install all supported hook integrations

beacon endpoint hooks install --all

When --all is used with --level project, Beacon skips Hermes Agent because Hermes shell hooks are user-level only. Install Antigravity, Claude Code, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, and OpenCode hooks with the same runtime log:

Install Antigravity, Claude Code, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, and OpenCode hooks with the same runtime log

beacon endpoint hooks install --harness antigravity,claude,cursor,devin-cli,devin-desktop,factory,grok,hermes,opencode

Use a custom runtime log:

Use a custom runtime log

beacon endpoint hooks install \
  --harness cursor \
  --log-path /path/to/runtime.jsonl

beacon endpoint hooks status

beacon endpoint hooks status checks whether Beacon hook integrations are installed for the selected harnesses.

Check hook status

beacon endpoint hooks status --harness cursor

Examples

Check Cursor hook status:

Check Cursor hook status

beacon endpoint hooks status --harness cursor

Check Antigravity hook status:

Check Antigravity hook status

beacon endpoint hooks status --harness antigravity

Check Claude Code hook status:

Check Claude Code hook status

beacon endpoint hooks status --harness claude

Check Factory hook status:

Check Factory hook status

beacon endpoint hooks status --harness factory

Check Devin CLI hook status:

Check Devin CLI hook status

beacon endpoint hooks status --harness devin-cli

Check Devin Desktop hook status:

Check Devin Desktop hook status

beacon endpoint hooks status --harness devin-desktop

Check OpenCode plugin status:

Check OpenCode plugin status

beacon endpoint hooks status --harness opencode

Check Grok Build hook status:

Check Grok Build hook status

beacon endpoint hooks status --harness grok

Check Hermes Agent hook status:

Check Hermes Agent hook status

beacon endpoint hooks status --harness hermes

Print hook status as JSON:

Print hook status as JSON

beacon endpoint hooks status --harness cursor --json

Show every supported hook integration:

Show every supported hook integration

beacon endpoint hooks status --all

Check project-level hooks:

Check project-level hooks

beacon endpoint hooks status --harness cursor --level project

beacon endpoint hooks uninstall

beacon endpoint hooks uninstall removes Beacon hook entries for supported harnesses. Existing non-Beacon hooks are preserved.

Remove runtime hooks

beacon endpoint hooks uninstall --harness cursor

Examples

Remove user-level Cursor hooks:

Remove user-level Cursor hooks

beacon endpoint hooks uninstall --harness cursor

Remove user-level Antigravity hooks:

Remove user-level Antigravity hooks

beacon endpoint hooks uninstall --harness antigravity

Remove user-level Claude Code hooks:

Remove user-level Claude Code hooks

beacon endpoint hooks uninstall --harness claude

Remove project-level Antigravity hooks:

Remove project-level Antigravity hooks

beacon endpoint hooks uninstall --harness antigravity --level project

Remove project-level Cursor hooks:

Remove project-level Cursor hooks

beacon endpoint hooks uninstall --harness cursor --level project

Remove user-level Devin CLI hooks:

Remove user-level Devin CLI hooks

beacon endpoint hooks uninstall --harness devin-cli

Remove project-level Devin CLI hooks:

Remove project-level Devin CLI hooks

beacon endpoint hooks uninstall --harness devin-cli --level project

Remove user-level Devin Desktop hooks:

Remove user-level Devin Desktop hooks

beacon endpoint hooks uninstall --harness devin-desktop

Remove project-level Devin Desktop hooks:

Remove project-level Devin Desktop hooks

beacon endpoint hooks uninstall --harness devin-desktop --level project

Remove user-level Factory hooks:

Remove user-level Factory hooks

beacon endpoint hooks uninstall --harness factory

Remove user-level OpenCode hooks:

Remove user-level OpenCode hooks

beacon endpoint hooks uninstall --harness opencode

Remove user-level Grok Build hooks:

Remove user-level Grok Build hooks

beacon endpoint hooks uninstall --harness grok

Remove user-level Hermes Agent hooks:

Remove user-level Hermes Agent hooks

beacon endpoint hooks uninstall --harness hermes

Remove project-level Grok Build hooks:

Remove project-level Grok Build hooks

beacon endpoint hooks uninstall --harness grok --level project

Antigravity troubleshooting

Beacon writes Antigravity user-level hooks to ~/.gemini/config/hooks.json. Project-level installs write ./.agents/hooks.json. Beacon owns only the beacon-endpoint hook block and leaves other Antigravity hook blocks in place. If Antigravity telemetry is missing, check the selected level, confirm the hook file contains commands with --platform antigravity, and restart Antigravity so new sessions pick up the updated hook configuration.

Grok Build troubleshooting

Beacon writes Grok Build user-level hooks to ~/.grok/hooks/beacon-endpoint.json. Project-level installs write ./.grok/hooks/beacon-endpoint.json and require /hooks-trust in Grok before those hooks execute. Beacon owns only the beacon-endpoint.json hook file and leaves other Grok hook files in place. If Grok telemetry is missing, check the selected level, confirm the hook file contains commands with --platform grok, run /hooks-trust for project-level hooks, and restart Grok so new sessions pick up the updated hook configuration.

Hermes Agent troubleshooting

Beacon merges Hermes Agent hooks into ~/.hermes/config.yaml. Hermes hooks are user-level only; project-level install, status, or uninstall requests return a clear error. Beacon preserves existing Hermes settings and non-Beacon hooks, and replaces only Beacon-managed commands with BEACON_ENDPOINT_MODE=1 and --platform hermes. If Hermes telemetry is missing, confirm ~/.hermes/config.yaml contains commands with --platform hermes, restart Hermes, and verify hook consent. 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.

OpenCode troubleshooting

Beacon installs an owned OpenCode plugin at ~/.config/opencode/plugins/beacon.ts for user-level hooks or ./.opencode/plugins/beacon.ts for project-level hooks. The plugin is a thin local adapter: it forwards supported OpenCode hook payloads to Beacon’s Go hook binary, and Beacon handles normalization, redaction, retention, and JSONL output. For local troubleshooting, set BEACON_OPENCODE_DEBUG=1 in the environment that launches OpenCode to emit best-effort plugin debug logs. Beacon telemetry should not interrupt OpenCode execution if the hook command fails.

Devin troubleshooting

Beacon writes Devin CLI user-level hooks under the hooks key in ~/.config/devin/config.json. Devin CLI project-level installs write the standalone hook map to ./.devin/hooks.v1.json. The legacy devin harness name maps to devin-cli. Beacon writes Devin Desktop user-level hooks to ~/.codeium/windsurf/hooks.json. Project-level installs write .windsurf/hooks.json, which may also affect Windsurf/Cascade in that workspace. Install and uninstall preserve unrelated settings and non-Beacon hook commands. If Devin CLI hook telemetry is missing, check the selected level, confirm the hook file contains commands with --platform devin-cli, and restart Devin CLI so new sessions pick up the updated hook configuration. If Devin Desktop telemetry is missing, confirm the hook file contains commands with --platform devin-desktop, generate a Desktop event, and then check the Beacon runtime log.

Core Concepts

Review hook, harness, endpoint event, and runtime log terminology.

Agent harness integrations

Compare hook and OTLP support across Beacon runtimes.

​Command Overview

​Commands

beacon endpoint hooks install

beacon endpoint hooks status

beacon endpoint hooks uninstall

​Paths

​Flags

​beacon endpoint hooks install

​Examples

​beacon endpoint hooks status

​Examples

​beacon endpoint hooks uninstall

​Examples

​Antigravity troubleshooting

​Grok Build troubleshooting

​Hermes Agent troubleshooting

​OpenCode troubleshooting

​Devin troubleshooting

​Related

Core Concepts

Agent harness integrations

Command Overview

Commands

Paths

Flags

beacon endpoint hooks install

Examples

beacon endpoint hooks status

Examples

beacon endpoint hooks uninstall

Examples

Antigravity troubleshooting

Grok Build troubleshooting

Hermes Agent troubleshooting

OpenCode troubleshooting

Devin troubleshooting

Related