Connect coding assistants

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 covers supported AI websites.

Install the hooks

beam agent install claude-code
beam agent install codex

To discover and wire all supported installed assistants:

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 for fail-open and compatibility limits.