> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beacon.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# beacon endpoint hooks
> Install and manage Beacon endpoint hooks for supported agent harnesses
## Command overview
Beacon can install [hook-based endpoint telemetry](/concepts/core-concepts#hooks) for supported [agent harnesses](/runtimes). The hook adapter emits local Beacon [endpoint events](/concepts/core-concepts#endpoint-event) 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.
```bash title="Command syntax" theme={null}
beacon endpoint hooks [command]
```
## Commands
Install endpoint hooks for supported hook runtimes.
Show endpoint hook integration status.
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 ` | 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 ` | 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 ` | 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.
```bash title="Install runtime hooks" theme={null}
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:
```bash title="Install Cursor hooks at the user level" theme={null}
beacon endpoint hooks install --harness cursor
```
Install Antigravity hooks at the user level:
```bash title="Install Antigravity hooks at the user level" theme={null}
beacon endpoint hooks install --harness antigravity
```
Install Claude Code hooks at the user level:
```bash title="Install Claude Code hooks at the user level" theme={null}
beacon endpoint hooks install --harness claude
```
Install Codex CLI session-context hooks at the user level:
```bash title="Install Codex CLI session-context hooks at the user level" theme={null}
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:
```bash title="Install Antigravity hooks at the project level" theme={null}
beacon endpoint hooks install --harness antigravity --level project
```
Install Cursor hooks at the project level:
```bash title="Install Cursor hooks at the project level" theme={null}
beacon endpoint hooks install --harness cursor --level project
```
Install Devin CLI hooks at the user level:
```bash title="Install Devin CLI hooks at the user level" theme={null}
beacon endpoint hooks install --harness devin-cli
```
Install Devin CLI hooks at the project level:
```bash title="Install Devin CLI hooks at the project level" theme={null}
beacon endpoint hooks install --harness devin-cli --level project
```
Install Devin Desktop hooks at the user level:
```bash title="Install Devin Desktop hooks at the user level" theme={null}
beacon endpoint hooks install --harness devin-desktop
```
Install Devin Desktop hooks at the project level:
```bash title="Install Devin Desktop hooks at the project level" theme={null}
beacon endpoint hooks install --harness devin-desktop --level project
```
Install Factory hooks at the user level:
```bash title="Install Factory hooks at the user level" theme={null}
beacon endpoint hooks install --harness factory
```
Install OpenCode hooks at the user level:
```bash title="Install OpenCode hooks at the user level" theme={null}
beacon endpoint hooks install --harness opencode
```
Install Grok Build hooks at the user level:
```bash title="Install Grok Build hooks at the user level" theme={null}
beacon endpoint hooks install --harness grok
```
Install Hermes Agent hooks at the user level:
```bash title="Install Hermes Agent hooks at the user level" theme={null}
beacon endpoint hooks install --harness hermes
```
Install Qwen Code hooks at the user level:
```bash title="Install Qwen Code hooks at the user level" theme={null}
beacon endpoint hooks install --harness qwen
```
Install Grok Build hooks at the project level:
```bash title="Install Grok Build hooks at the project level" theme={null}
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:
```bash title="Install Qwen Code hooks at the project level" theme={null}
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:
```bash title="Install all supported hook integrations" theme={null}
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:
```bash title="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" theme={null}
beacon endpoint hooks install --harness antigravity,claude,codex,cursor,devin-cli,devin-desktop,factory,grok,hermes,opencode,qwen
```
Use a custom runtime log:
```bash title="Use a custom runtime log" theme={null}
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.
```bash title="Check hook status" theme={null}
beacon endpoint hooks status --harness cursor
```
### Examples
Check Cursor hook status:
```bash title="Check Cursor hook status" theme={null}
beacon endpoint hooks status --harness cursor
```
Check Antigravity hook status:
```bash title="Check Antigravity hook status" theme={null}
beacon endpoint hooks status --harness antigravity
```
Check Claude Code hook status:
```bash title="Check Claude Code hook status" theme={null}
beacon endpoint hooks status --harness claude
```
Check Codex CLI inventory hook status:
```bash title="Check Codex CLI inventory hook status" theme={null}
beacon endpoint hooks status --harness codex
```
Check Factory hook status:
```bash title="Check Factory hook status" theme={null}
beacon endpoint hooks status --harness factory
```
Check Devin CLI hook status:
```bash title="Check Devin CLI hook status" theme={null}
beacon endpoint hooks status --harness devin-cli
```
Check Devin Desktop hook status:
```bash title="Check Devin Desktop hook status" theme={null}
beacon endpoint hooks status --harness devin-desktop
```
Check OpenCode plugin status:
```bash title="Check OpenCode plugin status" theme={null}
beacon endpoint hooks status --harness opencode
```
Check Grok Build hook status:
```bash title="Check Grok Build hook status" theme={null}
beacon endpoint hooks status --harness grok
```
Check Hermes Agent hook status:
```bash title="Check Hermes Agent hook status" theme={null}
beacon endpoint hooks status --harness hermes
```
Check Qwen Code hook status:
```bash title="Check Qwen Code hook status" theme={null}
beacon endpoint hooks status --harness qwen
```
Print hook status as JSON:
```bash title="Print hook status as JSON" theme={null}
beacon endpoint hooks status --harness cursor --json
```
Show every supported hook integration:
```bash title="Show every supported hook integration" theme={null}
beacon endpoint hooks status --all
```
Check project-level hooks:
```bash title="Check project-level hooks" theme={null}
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.
```bash title="Remove runtime hooks" theme={null}
beacon endpoint hooks uninstall --harness cursor
```
### Examples
Remove user-level Cursor hooks:
```bash title="Remove user-level Cursor hooks" theme={null}
beacon endpoint hooks uninstall --harness cursor
```
Remove user-level Antigravity hooks:
```bash title="Remove user-level Antigravity hooks" theme={null}
beacon endpoint hooks uninstall --harness antigravity
```
Remove user-level Claude Code hooks:
```bash title="Remove user-level Claude Code hooks" theme={null}
beacon endpoint hooks uninstall --harness claude
```
Remove user-level Codex CLI inventory hooks:
```bash title="Remove user-level Codex CLI inventory hooks" theme={null}
beacon endpoint hooks uninstall --harness codex
```
Remove project-level Antigravity hooks:
```bash title="Remove project-level Antigravity hooks" theme={null}
beacon endpoint hooks uninstall --harness antigravity --level project
```
Remove project-level Cursor hooks:
```bash title="Remove project-level Cursor hooks" theme={null}
beacon endpoint hooks uninstall --harness cursor --level project
```
Remove user-level Devin CLI hooks:
```bash title="Remove user-level Devin CLI hooks" theme={null}
beacon endpoint hooks uninstall --harness devin-cli
```
Remove project-level Devin CLI hooks:
```bash title="Remove project-level Devin CLI hooks" theme={null}
beacon endpoint hooks uninstall --harness devin-cli --level project
```
Remove user-level Devin Desktop hooks:
```bash title="Remove user-level Devin Desktop hooks" theme={null}
beacon endpoint hooks uninstall --harness devin-desktop
```
Remove project-level Devin Desktop hooks:
```bash title="Remove project-level Devin Desktop hooks" theme={null}
beacon endpoint hooks uninstall --harness devin-desktop --level project
```
Remove user-level Factory hooks:
```bash title="Remove user-level Factory hooks" theme={null}
beacon endpoint hooks uninstall --harness factory
```
Remove user-level OpenCode hooks:
```bash title="Remove user-level OpenCode hooks" theme={null}
beacon endpoint hooks uninstall --harness opencode
```
Remove user-level Grok Build hooks:
```bash title="Remove user-level Grok Build hooks" theme={null}
beacon endpoint hooks uninstall --harness grok
```
Remove user-level Hermes Agent hooks:
```bash title="Remove user-level Hermes Agent hooks" theme={null}
beacon endpoint hooks uninstall --harness hermes
```
Remove user-level Qwen Code hooks:
```bash title="Remove user-level Qwen Code hooks" theme={null}
beacon endpoint hooks uninstall --harness qwen
```
Remove project-level Grok Build hooks:
```bash title="Remove project-level Grok Build hooks" theme={null}
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.
## Related
Review hook, harness, endpoint event, and runtime log terminology.
Compare hook and OTLP support across Beacon runtimes.