Skip to content

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

Install Claude Code hooks with the claude harness by default

shukieshah7ef56a48e0e3
diff --git a/CLAUDE.md b/CLAUDE.md
index a82da3d9..6494a7ee 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -37,7 +37,7 @@ Do not recreate or depend on removed `asymptote` mirror trees. Keep new work foc
Supported runtime surfaces today:
-- Claude Code and Codex CLI use local OpenTelemetry settings; Claude/Codex hooks add runtime-native context where configured. `beacon endpoint codex sync` is the offline poll backfill from `~/.codex/sessions`; it never reads `~/.codex/auth.json` and cannot approve, deny, or delay tool calls.
+- Claude Code and Codex CLI use local OpenTelemetry settings, and `beacon endpoint install` writes their user-level hooks alongside those settings (`otlpTargetCarriesHook` in `cli/beacon/cmd/endpoint_targets.go`), because Claude's OTLP export has no session lifecycle, file activity, or subagent events and Codex's SessionStart hook supplies the OS-user context its spans lack. `beacon endpoint codex sync` is the offline poll backfill from `~/.codex/sessions`; it never reads `~/.codex/auth.json` and cannot approve, deny, or delay tool calls.
- Cursor hook telemetry for sessions, prompt submission, tool use, command execution, MCP-like tool activity, approval decisions, file edits, and agent reasoning (`afterAgentThought` thinking text recorded as `agent.reasoning` events in the OTel GenAI `gen_ai.output.messages` reasoning-part shape) where hook payloads expose those fields.
- Cline uses a Beacon-managed plugin (`~/.cline/plugins/beacon.ts`) for live capture plus `beacon endpoint cline sync` for local history backfill. Cline's own OTel export/hosted prompt storage are not used, and approvals are not exposed or synthesized.
- Pi-family runtimes use Beacon-managed extensions and the shared `cli/beacon-hooks/cmd/pi_family.go` mapper while keeping separate harness names and install roots: Pi (`pi_cli`), Oh My Pi (`omp`), Prime Agent (`prime_agent`), and Senpi/OMO (`omo_senpi`). Pi, Prime, and Senpi do not expose operator approval decisions, so Beacon does not synthesize them. Oh My Pi exposes real approval events and the extension carries the remembered tool input onto those approvals.
diff --git a/cli/beacon/cmd/endpoint_targets.go b/cli/beacon/cmd/endpoint_targets.go
index d2e83368..dccf4e10 100644
--- a/cli/beacon/cmd/endpoint_targets.go
+++ b/cli/beacon/cmd/endpoint_targets.go
@@ -199,6 +199,15 @@ func normalizeHookTarget(name string) (string, bool) {
return target, ok
}
+// otlpTargetCarriesHook names the OTLP harnesses whose hook integration is installed
+// alongside their OpenTelemetry settings by `endpoint install` and `endpoint repair`.
+// `beacon endpoint hooks install` still installs the same hooks on their own, and
+// `beacon endpoint hooks uninstall` removes them.
+var otlpTargetCarriesHook = map[string]bool{
+ "claude": true,
+ "codex": true,
+}
+
func splitEndpointTargets(values []string) (otlp []string, hooks []string, err error) {
seenOTLP := map[string]bool{}
seenHooks := map[string]bool{}
@@ -216,13 +225,20 @@ func splitEndpointTargets(values []string) (otlp []string, hooks []string, err e
otlp = append(otlp, target.Name)
seenOTLP[target.Name] = true
}
- // Codex usage comes from OTLP turn spans, but those spans do not
- // identify the local OS account. Its SessionStart context hook is
- // therefore part of the token integration rather than an optional
- // duplicate activity path.
- if target.Name == "codex" && !seenHooks["codex"] {
- hooks = append(hooks, "codex")
- seenHooks["codex"] = true
+ // Some OTLP harnesses carry their hook integration with them, so the
+ // default install list configures both without a second command:
+ //
+ // - Codex usage comes from OTLP turn spans, but those spans do not
+ // identify the local OS account. Its SessionStart context hook is
+ // therefore part of the token integration rather than an optional
+ // duplicate activity path.
+ // - Claude Code's OTLP export has no session start or end, no file
+ // reads or diffs, and no subagent lifecycle; those come only from
+ // its hooks. Without them a default install records a thinner
+ // session than every other supported runtime.
+ if otlpTargetCarriesHook[target.Name] && !seenHooks[target.Name] {
+ hooks = append(hooks, target.Name)
+ seenHooks[target.Name] = true
}
case endpointTargetHook:
if !seenHooks[target.Name] {
diff --git a/cli/beacon/cmd/endpoint_test.go b/cli/beacon/cmd/endpoint_test.go
index 2cdefd9a..313b5475 100644
--- a/cli/beacon/cmd/endpoint_test.go
+++ b/cli/beacon/cmd/endpoint_test.go
@@ -57,11 +57,36 @@ func TestSplitEndpointTargetsDedupesHookAliases(t *testing.T) {
if got, want := strings.Join(otlp, ","), "claude,codex"; got != want {
t.Fatalf("otlp targets = %q, want %q", got, want)
}
- if got, want := strings.Join(hooks, ","), "codex,devin-cli,devin-desktop,hermes"; got != want {
+ if got, want := strings.Join(hooks, ","), "claude,codex,devin-cli,devin-desktop,hermes"; got != want {
t.Fatalf("hook targets = %q, want %q", got, want)
}
}
+// The default install list must carry the Claude Code and Codex hooks with their OTLP
+// settings: a fresh `beacon endpoint install` otherwise records Claude sessions with no
+// start, end, file activity, or subagent lifecycle, since Claude's OTLP export has none.
+func TestDefaultInstallHarnessesCarryClaudeAndCodexHooks(t *testing.T) {
+ defaultList := endpointInstallCmd.Flags().Lookup("harness").DefValue
+ otlp, hooks, err := splitEndpointTargets(splitHarnessCSV(defaultList))
+ if err != nil {
+ t.Fatalf("splitEndpointTargets(%q) returned error: %v", defaultList, err)
+ }
+ if got, want := strings.Join(otlp, ","), "claude,codex"; got != want {
+ t.Fatalf("default otlp targets = %q, want %q", got, want)
+ }
+ if got, want := strings.Join(hooks, ","), "claude,codex"; got != want {
+ t.Fatalf("default hook targets = %q, want %q", got, want)
+ }
+ // Listing the explicit hook alias as well must not install Claude hooks twice.
+ _, hooks, err = splitEndpointTargets([]string{"claude", "claude-hooks", "codex"})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got, want := strings.Join(hooks, ","), "claude,codex"; got != want {
+ t.Fatalf("hook targets with explicit alias = %q, want %q", got, want)
+ }
+}
+
func TestCanonicalHookTargetsNormalizesAliasesToSwitchNames(t *testing.T) {
got, err := canonicalHookTargets([]string{"claude_code", "codex_cli", "vs_code", "droid", "devin", "devin_desktop", "antigravity_cli", "hermes-agent"})
if err != nil {
@@ -83,13 +108,19 @@ func TestPlannedInstallActionsSeparatesHookHarnesses(t *testing.T) {
actions := plannedInstallActions(false, service.KindAuto)
counts := map[string]int{}
+ hookRows := map[string]int{}
for _, action := range actions {
if action.Action == "configure_harness" {
counts[action.Target]++
+ if action.Message != "" {
+ hookRows[action.Target]++
+ }
}
}
- if counts["claude"] != 1 || counts["devin-cli"] != 1 || counts["devin-desktop"] != 1 {
- t.Fatalf("configure_harness counts = %#v, want claude/devin-cli/devin-desktop once", counts)
+ // claude is planned twice on purpose: its OTLP settings and its hooks are two
+ // separate writes, and the plan names each of them.
+ if counts["claude"] != 2 || hookRows["claude"] != 1 || counts["devin-cli"] != 1 || counts["devin-desktop"] != 1 {
+ t.Fatalf("configure_harness counts = %#v (hook rows %#v), want claude OTLP+hook, devin-cli/devin-desktop once", counts, hookRows)
}
if counts["devin"] != 0 {
t.Fatalf("legacy devin alias should be deduped, counts=%#v", counts)
diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdx
index 427bee65..e6741091 100644
--- a/docs/changelog/cli.mdx
+++ b/docs/changelog/cli.mdx
@@ -55,6 +55,14 @@ Stay up to date with the latest changes to the Agent Beacon CLI.
and persisted token usage. Poll events remain offline, deterministic, and
cannot approve, deny, or delay tools.
+- **Claude Code hooks install by default** · `beacon endpoint install` and `beacon endpoint repair`
+ now write Claude Code's user-level hooks together with its OpenTelemetry settings whenever
+ the `claude` harness is selected, which the default harness list does. Claude's OTLP export
+ has no session start or end, file reads or diffs, or subagent lifecycle, so a default install
+ previously recorded thinner Claude sessions than every other supported runtime. Package
+ installs already refreshed these hooks for the console user; this brings Homebrew and
+ tarball installs in line. `beacon endpoint hooks uninstall --harness claude` removes them.
+
### v1.3.17 · September 21, 2026
- **Reviewed cross-harness memory** · Beacon now has an explicit local learning
diff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdx
index 2b0dea3f..a93c2b1d 100644
--- a/docs/cli/endpoint-install.mdx
+++ b/docs/cli/endpoint-install.mdx
@@ -13,7 +13,7 @@ The service is a launchd job on macOS and a systemd unit on Linux. Where neither
beacon endpoint install
```
-By default, Beacon configures Claude Code and Codex CLI telemetry for local or customer-controlled runtime JSONL logs. Gemini CLI and VS Code Copilot telemetry are opt-in with the `gemini` and `vscode` harnesses. Claude Code can also use optional hook telemetry for richer lifecycle, subagent, permission, and tool detail; install the endpoint agent first, then add Claude hooks with `beacon endpoint hooks install --harness claude`. Codex uses OTLP logs plus one selective turn trace for tokens, and its required SessionStart hook adds local OS-user context. Beacon applies redaction, sanitization, truncation, and event-size limits before writing supported content fields. GitHub Copilot CLI and Factory Droid OTLP are managed through their launch environments, so Beacon validates their telemetry state but does not mutate shell profiles during install.
+By default, Beacon configures Claude Code and Codex CLI telemetry for local or customer-controlled runtime JSONL logs. Gemini CLI and VS Code Copilot telemetry are opt-in with the `gemini` and `vscode` harnesses. The `claude` harness writes both Claude Code's OpenTelemetry settings and its user-level hooks, because the OTLP export alone carries no session start or end, file activity, or subagent lifecycle; `beacon endpoint hooks uninstall --harness claude` removes the hooks again, and `beacon endpoint hooks install --harness claude --level project` adds project-level ones. Codex uses OTLP logs plus one selective turn trace for tokens, and its required SessionStart hook adds local OS-user context. Beacon applies redaction, sanitization, truncation, and event-size limits before writing supported content fields. GitHub Copilot CLI and Factory Droid OTLP are managed through their launch environments, so Beacon validates their telemetry state but does not mutate shell profiles during install.
## Flags
@@ -22,7 +22,7 @@ By default, Beacon configures Claude Code and Codex CLI telemetry for local or c
| `--user` | Use per-user endpoint paths. Enabled by default |
| `--system` | Use system endpoint paths and launch daemon. Requires root |
| `--log-path <path>` | Runtime JSONL log path |
-| `--harness <list>` | Comma-separated harnesses to configure. Defaults to `claude,codex`; include `gemini` for Gemini CLI or `vscode` for VS Code Copilot OTLP telemetry. Hook harnesses can be listed alongside them: `claude-hooks` (Claude Code hooks), `cursor`, `factory`, `opencode`, `cline`, `pi`, `omp`, `openclaw`, `grok`, `qwen`, `hermes`, `antigravity`, `devin-cli`, `devin-desktop`, `dsh`, and `kimi`, for example `beacon endpoint install --harness claude,codex,cursor,kimi`. DeepSeek Harness and Kimi Code are user-level only. `beacon endpoint hooks install` adds the same hooks to an existing install later, and is the only way to add VS Code hook telemetry. GitHub Copilot CLI and Factory Droid OTLP endpoints are managed through their launch environments |
+| `--harness <list>` | Comma-separated harnesses to configure. Defaults to `claude,codex`, each of which installs its OTLP settings and its hooks; include `gemini` for Gemini CLI or `vscode` for VS Code Copilot OTLP telemetry. Hook harnesses can be listed alongside them: `cursor`, `factory`, `opencode`, `cline`, `pi`, `omp`, `openclaw`, `grok`, `qwen`, `hermes`, `antigravity`, `devin-cli`, `devin-desktop`, `dsh`, and `kimi`, for example `beacon endpoint install --harness claude,codex,cursor,kimi`. DeepSeek Harness and Kimi Code are user-level only. `beacon endpoint hooks install` adds the same hooks to an existing install later, and is the only way to add VS Code hook telemetry. GitHub Copilot CLI and Factory Droid OTLP endpoints are managed through their launch environments |
| `--otlp-grpc-port <port>` | Local OTLP gRPC port. Defaults to `4317` |
| `--otlp-http-port <port>` | Local OTLP HTTP port. Defaults to `4318` |
| `--collector <path>` | Path to a `beacon-otelcol` binary |
@@ -152,10 +152,10 @@ For richer hook telemetry, install runtime hooks after the endpoint configuratio
beacon endpoint hooks install --harness antigravity,claude,cline,cursor,devin-cli,devin-desktop,factory,grok,hermes,opencode,qwen
```
-Install Claude Code hooks at the user level:
+Claude Code hooks are already installed at the user level by `endpoint install`. Add project-level hooks, or re-add user-level ones after removing them:
-```bash title="Install Claude Code hooks at the user level"
-beacon endpoint hooks install --harness claude
+```bash title="Add Claude Code hooks to a project"
+beacon endpoint hooks install --harness claude --level project
```
Install Grok Build hooks at the user level:
diff --git a/docs/runtimes/claude-code.mdx b/docs/runtimes/claude-code.mdx
index 2330e264..beaab109 100644
--- a/docs/runtimes/claude-code.mdx
+++ b/docs/runtimes/claude-code.mdx
@@ -20,11 +20,11 @@ Before enabling Claude Code telemetry, make sure:
Claude Code exports OTLP telemetry to the local Beacon collector. Beacon writes normalized [endpoint events](/concepts/core-concepts#endpoint-event) to the configured runtime JSONL log and makes them available in the local dashboard.
-For richer local telemetry, Beacon can also install Claude Code hooks with the same hook adapter used by other supported runtimes:
+The OTLP export carries prompts, tool calls, commands, approvals, and token usage, but no session start or end, file reads or diffs, or subagent lifecycle. Those come from Claude Code hooks, which use the same hook adapter as the other supported runtimes, so `beacon endpoint install` writes the user-level hooks together with the OTLP settings whenever the `claude` harness is selected. Check or manage them with the hooks commands:
-```bash title="Install Claude Code hooks"
-beacon endpoint hooks install --harness claude
+```bash title="Inspect or remove Claude Code hooks"
beacon endpoint hooks status --harness claude
+beacon endpoint hooks uninstall --harness claude
```
User-level hooks are written to `~/.claude/settings.json`. Project-level hooks are written to `./.claude/settings.json`: