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`
Codex CLI	`~/.codex/hooks.json`	`./.codex/hooks.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`
Cline	`~/.cline/plugins/beacon.ts`	`./.cline/plugins/beacon.ts`	`~/.beacon/endpoint/hooks/beacon-hooks`	`~/.beacon/endpoint/logs/runtime.jsonl`
Pi	`~/.pi/agent/extensions/beacon.ts`	`./.pi/extensions/beacon.ts`	`~/.beacon/endpoint/hooks/beacon-hooks`	`~/.beacon/endpoint/logs/runtime.jsonl`
Oh My Pi	`~/.omp/agent/extensions/beacon.ts`	`./.omp/extensions/beacon.ts`	`~/.beacon/endpoint/hooks/beacon-hooks`	`~/.beacon/endpoint/logs/runtime.jsonl`
Qwen Code	`~/.qwen/settings.json`	`./.qwen/settings.json`	`~/.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`, `cline`, `codex`, `cursor`, `devin-cli`, `devin-desktop`, `factory`, `grok`, `hermes`, `omp`, `openclaw`, `opencode`, `pi`, `qwen`, or `antigravity,claude,cline,codex,cursor,devin-cli,devin-desktop,factory,grok,hermes,omp,openclaw,opencode,pi,qwen`. `devin` remains a legacy alias for `devin-cli`; `hermes-agent` maps to `hermes`; `qwen-code` maps to `qwen`; `pi-cli` and `pi_cli` map to `pi`; `oh-my-pi` and `ohmypi` map to `omp`; `openclaw-gateway` maps to `openclaw`. 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, Cline, Codex CLI, 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. Codex CLI uses SessionStart for metadata-only OS-user context; Codex prompt, tool, and token telemetry still comes from its local OpenTelemetry export path, and inventory comes from the scheduled inventory job rather than a hook. 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. Cline hooks use Beacon’s managed local plugin to forward beforeRun, beforeTool, afterTool, and afterRun, and also accept Cline’s file-based hook names (TaskStart, UserPromptSubmit, PreToolUse, PostToolUse) so one adapter serves both of Cline’s hook surfaces.

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 Codex CLI session-context hooks at the user level:

Install Codex CLI session-context hooks at the user level

beacon endpoint hooks install --harness codex

A successful user-level install prints Codex CLI hooks installed: /Users/you/.codex/hooks.json. 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 Qwen Code hooks at the user level:

Install Qwen Code hooks at the user level

beacon endpoint hooks install --harness qwen

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. Install Qwen Code hooks at the project level:

Install Qwen Code hooks at the project level

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

Project-level Qwen Code hooks are only executed in a folder Qwen trusts, so a user-level install is the one that collects without further interaction. 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, Codex CLI, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, OpenCode, and Qwen Code hooks with the same runtime log:

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

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

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 Codex CLI inventory hook status:

Check Codex CLI inventory hook status

beacon endpoint hooks status --harness codex

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

Check Qwen Code hook status:

Check Qwen Code hook status

beacon endpoint hooks status --harness qwen

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 user-level Codex CLI inventory hooks:

Remove user-level Codex CLI inventory hooks

beacon endpoint hooks uninstall --harness codex

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 user-level Qwen Code hooks:

Remove user-level Qwen Code hooks

beacon endpoint hooks uninstall --harness qwen

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, identified by the endpoint settings flags (--log, --config, --cli) or a legacy BEACON_ENDPOINT_MODE=1 prefix, together with --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.

Qwen Code troubleshooting

Beacon merges its hooks into Qwen Code’s own settings.json: ~/.qwen/settings.json for user-level installs, ./.qwen/settings.json for project-level installs. Unrelated top-level keys and non-Beacon hooks in the same event group are preserved, and a re-install replaces Beacon’s own entries instead of adding a second copy. Beacon identifies its entries by the --platform qwen argument in the hook command, since it has no file of its own in ~/.qwen to stamp. Qwen Code is a Gemini CLI fork without Gemini’s OpenTelemetry export, so hooks are the only collection path for this runtime. beacon endpoint install --harness qwen installs these same hooks and writes ~/.qwen/settings.json. Two Qwen-specific details are worth knowing before hand-editing the file:

Timeouts are milliseconds, not seconds. Claude Code reads timeout as seconds, so a Claude-style 10 means 10 ms to Qwen and every tool event is killed mid-write while the install still reports success. Beacon writes millisecond values (30000 for prompt submission, 10000 for tool events, 45000 for stop); events with no entry inherit Qwen’s own 60000 ms default.
Hooks declare shell: bash. Qwen only uses bash when the hook configuration asks for it. Left unset on Windows it falls back to cmd.exe, which cannot parse Beacon’s POSIX-quoted command, so every hook fails to start. This requires bash on PATH on Windows, the same requirement Claude Code already carries there.

If Qwen telemetry is missing, check the selected level, confirm settings.json contains commands with --platform qwen, confirm disableAllHooks is not set in Qwen’s settings, confirm hook timeouts are millisecond values, trust the folder for a project-level install, and restart Qwen so new sessions pick up the updated settings. Beacon’s PreToolUse hook answers with an empty object on purpose. Qwen reads hookSpecificOutput.permissionDecision from that hook, where allow means run the tool without the usual approval prompt, so an observing hook that answered allow would silently disarm your own permission prompts. Approval telemetry comes from Qwen’s PermissionRequest event instead.

Codex CLI troubleshooting

Beacon writes Codex CLI endpoint hooks to ~/.codex/hooks.json for user-level installs or ./.codex/hooks.json for project-level installs. SessionStart writes local OS-user/session context. This metadata-only hook does not replace the Codex OTLP runtime path for prompt, tool, or token events, and it no longer triggers inventory: that is the scheduled inventory job’s work, in every mode, whether or not Codex runs. If Codex session context is missing, check the selected level, confirm the hook file contains a command with --platform codex, and restart Codex CLI so new sessions pick up the updated hook configuration.

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.

Install and Upgrade

CLI Resources

Command Manual

beacon endpoint hooks

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

Qwen Code troubleshooting

Codex CLI troubleshooting

OpenCode troubleshooting

Devin troubleshooting

Core Concepts

Agent harness integrations

​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

​Qwen Code troubleshooting

​Codex CLI 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

Qwen Code troubleshooting

Codex CLI troubleshooting

OpenCode troubleshooting

Devin troubleshooting

Related