# Connect coding assistants

> Install native agent hooks, understand adapter coverage, and verify a real captured event.

Source: https://docs.agentbeam.com/agent-cli/agent-hooks

Beam's adapters translate each assistant's hook payload into a common event shape. Hook installation merges Beam's entry into the assistant's own configuration. Existing hooks are preserved, and repeating installation does not intentionally add a duplicate entry.

## Choose an adapter

| Agent ID      | Hook configuration                       | Coverage                                                  |
| ------------- | ---------------------------------------- | --------------------------------------------------------- |
| `claude-code` | `~/.claude/settings.json`, PreToolUse    | Verified payload adapter; policy deny output wired        |
| `codex`       | `~/.codex/hooks.json`, PreToolUse        | Verified payload adapter; policy deny output wired        |
| `cursor`      | `~/.cursor/hooks.json`, preToolUse       | Verified payload adapter; blocking response not wired     |
| `copilot-cli` | `~/.copilot/hooks/beam.json`, preToolUse | CamelCase payload translated; blocking response not wired |
| `gemini`      | `~/.gemini/settings.json`, BeforeTool    | Best-effort payload adapter; not verified                 |
| `hermes`      | `~/.hermes/config.yaml`, `hooks.pre_tool_call` shell hook | Payload and block contract verified against Hermes' hooks docs; asks you to approve on first use |
| `openclaw`    | A Beam-written plugin using `before_tool_call` | Registration follows OpenClaw's plugin docs; event field names not verified |
| `opencode`    | Config/artifact discovery                | Hook installation not implemented                         |

Check `beam agent list` for the installed release's supported IDs. Adapter status is not proof that a particular assistant version is invoking the hook correctly on your machine.

Only `claude-code` and `codex` events carry token usage in the dashboard's "Tokens used" figures. Both read it from that agent's own local session transcript after the hook fires (see `findClaudeCodeUsage`/`findCodexUsage` in `client.ts`), since neither agent's hook payload includes it directly. Cursor has no equivalent: none of its documented hook events, its `cursor-agent` CLI output formats, or its local `~/.cursor` state expose per-turn token counts, so Cursor's token usage is omitted rather than estimated.

## Hermes Agent and OpenClaw

Neither agent has a JSON hook file Beam can merge into, so `beam agent install hermes` and `beam agent install openclaw` work differently.

**Hermes Agent** reads shell hooks from the `hooks:` block of `~/.hermes/config.yaml` (the default profile). Beam adds one `pre_tool_call` entry between `# beam:begin` and `# beam:end` comments and leaves everything else in the file alone. If you already have a `pre_tool_call` list, or an inline `hooks: {}`, Beam stops and prints the entry to add by hand. Hermes asks you to approve a new hook the first time it runs, and saves that choice in `~/.hermes/shell-hooks-allowlist.json`; in the gateway, cron or CI the hook stays inactive until you approve it, start Hermes with `--accept-hooks`, or set `HERMES_ACCEPT_HOOKS=1`. A Hermes shell hook that errors or times out fails open unless `fail_closed` is set on the entry.

**OpenClaw** has no hook config file: typed hooks are registered by a plugin. Beam writes a small plugin under its own data directory (`openclaw-plugin/`), then runs `openclaw plugins install --link` and `openclaw plugins enable beam`. If the `openclaw` command is not on PATH, Beam writes the plugin and prints those two commands for you to run. OpenClaw's docs describe the `before_tool_call` registration and the `{ block, blockReason }` result, but not every event field, so treat enforcement as unverified until a real event shows up in Studio. Because OpenClaw fails open when a hook throws, the plugin returns a block when Beam itself errors.

Both are the agent's own tool calls, so a Hermes `terminal` command is recorded as a command, and the same workspace policy applies. They do not cover a cloud-hosted agent or the agent's web interface; the [Agentbeam browser extension](https://chromewebstore.google.com/detail/agentbeam/cfnfncghihajlmpjafimebnafkhibipg) covers supported AI websites.

## Install the hooks

```sh
beam agent install claude-code
beam agent install codex
```

To discover and wire all supported installed assistants:

```sh
beam agent install-all
```

Detection uses the assistant's existing files, not files Beam creates itself. Review errors per agent; malformed existing configuration should be repaired deliberately instead of overwritten.

## Verify capture

Start the collector and reopen or refresh the assistant according to its configuration-loading behavior. Run a harmless tool action and inspect it in Studio. Confirm the source agent, tool name, and phase rather than relying only on an “installed” message.

Beam must be on the assistant process's PATH. A desktop-launched application may inherit a different PATH from your terminal. Use a reviewed absolute executable path in the hook configuration when necessary.

## Understand event phase and enforcement

A PreToolUse hook records a proposed action. Historical extraction records observed transcript entries. Neither a finding nor a captured proposal establishes an effect on the filesystem or network.

In observe mode, capture failures are reported without intentionally blocking the calling assistant. With an active workspace policy, Claude Code and Codex can receive a deny response before local capture. Other agents receive a stderr note for a deny decision. See [policies](https://docs.agentbeam.com/agent-cli/policies) for fail-open and compatibility limits.