> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Setup

> See and control the tool calls that Claude Code makes on your organization's computers.

> [!NOTE]
>
> Tool call governance is currently in limited beta. Contact Opal support to enable it for your organization.

With Claude Code connected to [tool call governance](https://docs.opal.dev/docs/tool-call-governance.md), Opal sees the tool calls that Claude Code makes on your computers, including shell commands, file edits, and MCP calls. Each call appears in Opal on that person's Claude agent. Opal checks each call against your rules before it runs, and a rule can block the call or ask the person to confirm it. If Opal is slow or can't be reached, the call runs anyway.

Syncing Claude agents from your Anthropic organization is a separate setup. See [Anthropic Setup](https://docs.opal.dev/docs/anthropic-agent-setup.md).

## Requirements

Before you begin, you must:

* Be an Opal Admin. Only admins see the **Setup** tab.
* For the one-computer command on macOS and Linux, have `bash`, `curl`, `jq` 1.6 or later, and either `unzip` or `python3` on the computer.
* For managed settings, be able to edit your organization's managed settings for Claude Code in claude.ai (Team and Enterprise plans), or push settings with your device management tool.
* Make sure each person who installs the kit has an Opal account. They approve a sign-in once, in their browser.
* Decide what Opal may store from conversations. See [What Opal records](#what-opal-records).

In Opal, go to **Agent Center** > **Setup** > **Anthropic**. The setup is in the **Client-side hooks** section. If the section has no card that starts with "Try it on your own computer", your Opal doesn't serve the hook kit yet. Contact Opal support.

## Install

You can install on one computer to try Opal, or roll it out to every computer with Claude Code's managed settings.

### Try it on one computer

Each person runs one command in Terminal. To copy it, go to **Agent Center** > **Setup** > **Anthropic** and find the card that starts with "Try it on your own computer". Choose **macOS and Linux**. With your Opal's address in it, the command is:

```bash theme={null}
curl -fsSL https://<your Opal>/downloads/claude-code-hooks/install.sh | bash
```

The command also sets up Cursor if Cursor is on the computer. To set up only Claude Code, add `-s -- --only=claude` after `bash`:

```bash theme={null}
curl -fsSL https://<your Opal>/downloads/claude-code-hooks/install.sh | bash -s -- --only=claude
```

1. Run the command. The installer shows what leaves the computer and which files it changes, and asks before it changes anything. Enter `y`.
2. Sign in. The installer shows a code and opens Opal in your browser. Check that the page shows the same code, then select **Approve**. Don't approve a code that someone else sent you.
3. Restart Claude Code.

The installer puts the hook and its settings in `~/opal-hook/`. It adds Opal's hooks to `~/.claude/settings.json` after saving a backup of that file, and it turns on Claude Code's own log export to Opal in the same file. If the person's settings or environment already send Claude Code's telemetry somewhere, the installer leaves that alone and says that Opal's log export wasn't turned on.

Approving the sign-in creates a personal access token for the computer. Its name says which client it is for and which computer, such as **Claude Code hooks on** or **Agent hooks on** followed by the computer's name. The token works only for the hook's own requests, such as reporting activity and reading the hook's settings. Opal refuses it for anything else.

The token is listed under **Settings** > **Personal Access Tokens**. Admins see that page. Other people see it only if your organization allows all users to create personal access tokens, and without that setting they can't revoke the token. If you set a maximum API token lifetime, the token expires then, and the person signs in again.

### Roll out with managed settings

Claude Code's managed settings configure every computer at once, so nobody runs an installer. You copy one block of settings from Opal and paste it into your organization's managed settings in claude.ai.

1. In Opal, go to **Agent Center** > **Setup** > **Anthropic**. Under **Claude Code on Team and Enterprise plans**, go to the first step. If your organization has no key, select **Create key**. The key can only report agent activity and read the hook's settings, and Opal doesn't attribute calls sent with it to the admin who made it.
2. In the **Copy the settings** step, choose **HTTP hook**, **Opal kit on each laptop**, or both. See [HTTP hook or Opal kit](#http-hook-or-opal-kit). If your Opal doesn't serve the kit, the settings have the HTTP hook only. Select **Copy settings and open claude.ai**, or **Copy settings** to paste them yourself. The page shows the key masked, and the copy has the real key.
3. In claude.ai, go to **Organization settings** > **Claude Code** > **Managed settings**. Paste the settings and save.

claude.ai keeps one block of managed settings, and pasting replaces it. If you already have managed settings, select **Already have managed settings? Merge them** under the copy buttons and paste your current settings. Opal adds its hooks and variables to your settings, replaces any that it added before, and keeps everything else. This happens in your browser. Copy the merged result instead. If your settings already set one of the telemetry variables that Opal needs to a different value, the merge keeps your value and warns you, and Claude Code then doesn't send its telemetry to Opal.

Claude Code asks each person once to approve hooks that come from managed settings. If they decline, Claude Code quits.

#### HTTP hook or Opal kit

With both chosen, which is the default, Claude Code and the kit each report every call, and Opal stores it once.

| | HTTP hook | Opal kit on each laptop |
| - | - | - |
| How it works | Claude Code sends each call to Opal. Nothing is installed. | Claude Code installs Opal's kit from your Opal when a session starts. |
| Computers | macOS, Linux, and Windows | macOS and Linux |
| Needs | Claude Code | `bash`, `curl`, `tar`, and `jq` 1.6 or later |
| If Opal is slow | Claude Code waits up to 5 seconds at each hook. | Only the check before a call waits, up to 5 seconds. |
| If a send fails | The event is lost. | The kit retries for up to 15 minutes. |
| Tool output and conversation | Sent as Claude Code gives them. | The kit masks secrets on the computer first. |
| Model replies | The final message of each turn. | Every text the model writes in a turn. |
| Prompts checked for secrets | No | Yes |
| Configuration report | No | Yes |

With either route, Opal masks credentials and personal data in the tool output and conversation text it stores.

Managed settings don't install `jq`, so install it on each computer first.

You paste the settings once. Each computer's kit asks your Opal once a day which kit it serves and updates itself, so the settings stay the same when Opal updates the kit.

Until a person signs in, the kit sends with your organization key and the person's email, and Opal's sign-in page opens in their browser at most once an hour. After they approve, the kit sends with their own token.

#### Use your device management tool instead

Push the same settings with your device management tool:

* **macOS:** a configuration profile for the `com.anthropic.claudecode` domain, or the file `/Library/Application Support/ClaudeCode/managed-settings.json`
* **Windows:** the string value `Settings` under `HKLM\SOFTWARE\Policies\ClaudeCode`, or the file `C:\Program Files\ClaudeCode\managed-settings.json`
* **Linux:** the file `/etc/claude-code/managed-settings.json`

Claude Code uses one source of managed settings. Once the settings are in claude.ai, a profile or file on a computer stops applying, except for environment variables that claude.ai leaves unset. If you want both to apply, set `"managedSourcesBehavior": "merge"` in the claude.ai settings. This needs Claude Code 2.1.242 or later. Merge also adds the hooks and allow rules from every profile and file, so set it only when administrators control all of them.

### Windows

Each person runs this in PowerShell:

```powershell theme={null}
irm https://<your Opal>/downloads/claude-code-hooks/install.ps1 | iex
```

To copy the command with your Opal's address in it, go to **Agent Center** > **Setup** > **Anthropic**, find the card that starts with "Try it on your own computer", and select **Windows**. The installer shows what it changes and asks before it changes anything. Then it signs the person in through the browser, as on macOS and Linux.

The installer picks a mode. If Git for Windows and `jq` are installed, it runs the same hook as macOS and Linux through Git Bash. Otherwise it adds Claude Code's HTTP hook, which needs nothing else. The installer says which mode it picked and why. To get the first mode, run `winget install Git.Git jqlang.jq`, then run the installer again. The table above lists the differences. In HTTP mode, the installer also sends Opal a one-time list of the MCP servers in Claude Code's configuration.

On Windows, the installer ignores **Store conversation content**. It sends the conversation only when you run it with `-Content`:

```powershell theme={null}
& ([scriptblock]::Create((irm https://<your Opal>/downloads/claude-code-hooks/install.ps1))) -Content
```

**Never** still applies, so Opal stores none.

Managed settings reach Windows computers too, but only the HTTP hook works there. Managed settings don't install the kit on Windows.

### Check calls with Anthropic's inference hooks

Claude Enterprise organizations can also have Anthropic send each Claude Code tool call to Opal before it runs, with no hook on the computer. The setup is the same for Claude Code and Cowork. See [Check Cowork's tool calls before they run](https://docs.opal.dev/docs/tool-call-governance-cowork.md#check-coworks-tool-calls-before-they-run). Opal checks calls that come through an inference hook against your rules whatever the **Log** and **Enforce** switches say.

## Check that it works

1. Start a new Claude Code session on the computer and ask it to run `echo opal-check`.
2. In Opal, go to **Agent Center** > **Activity**. Open the runtime filter, which shows **All runtimes**, and choose **Claude Code**. Within a few seconds, the call appears. The **Agent** column shows the person's Claude agent, with **Claude Code** under it.
3. To test a block, make sure **Enforce** is on for Claude Code under **Setup** > **Clients**. Go to **Agent Center** > **Policies** and select **New policy**. If Opal offers to draft the rule from a description, select **Create manually**. Set **Rule name** to `Opal block test` and **Result** to **Block**. Select **Add condition** > **Arguments**, enter `*opal-block-test*`, and select **Create rule**. Ask Claude Code to run `echo opal-block-test`. Claude Code doesn't run the call, and the row in **Activity** shows **Blocked**. Delete the rule afterwards. For more on creating rules, see [Create a rule](https://docs.opal.dev/docs/tool-call-governance-rules.md#create-a-rule).

Opal turns on enforcement for each organization. Until it is on for yours, **Enforce** behaves like **Log** only: Opal checks every call and records what each rule would have done, but it doesn't stop any call, except a call that a pause stops. In the test above, the call runs and the row shows **Would have blocked**. Contact Opal support to turn on enforcement.

If the call doesn't appear, check the following:

| What you see | What it means | What to do |
| - | - | - |
| Nothing in **Activity** | Claude Code was open during the install. | Restart Claude Code. |
| Nothing in **Activity** after the one-computer command | The sign-in wasn't approved in time, so the installer stopped. | Run the command again and approve the sign-in within 10 minutes. |
| Nothing in **Activity** | Claude Code's **Log** switch is off. | Turn **Log** on under **Setup** > **Clients**. With **Log** off and **Enforce** on, Opal records only the calls that a rule acted on. |
| Nothing in **Activity** after a managed settings rollout | The person's Claude Code isn't signed in to your organization's Claude account, or they didn't approve the hooks. | Check that they use your organization's account, then ask them to start a new session and approve the hooks. |
| `status=401` in `~/opal-hook/errors.log` | Opal refused the token. It was revoked or expired, or you rotated the organization key. | Run the install command again to sign in. If you rotated the key, paste the new settings. |
| `status=curl-error-7` in `~/opal-hook/errors.log` | The computer couldn't connect to Opal. | Check that the computer can reach your Opal's address. |
| Nothing in **Activity**, and no errors in `errors.log` | Tool call governance isn't turned on for your organization. Opal accepts what computers send and doesn't store it. | Contact Opal support. |
| An email or ID with an **unknown** tag in the **Agent** column, or **Unknown agent** | Opal can't match the call to a Claude agent. | See [Who made the call](#who-made-the-call). |

## What Opal records

For every call, whatever your conversation setting is, Opal receives:

* The tool's name and arguments, for example the shell command. Arguments are sent as Claude Code gives them, so a secret pasted into a command reaches Opal. Opal masks credentials and personal data, such as email addresses and phone numbers, in the copy it stores, and it doesn't store very large arguments, such as the contents of a file that a call writes. Your rules match the arguments as sent.
* For an MCP call, the server's name. With the kit, also the server's URL or a hash of its command, when the server is in the computer's Claude Code configuration.
* The session, the folder the call ran in, and Claude Code's permission mode.
* How the call ended, and how long it took, which the person's agent page shows as **Took**.
* What Opal decided: allowed, flagged, held for approval, or blocked, and the rule that decided it.
* The time of the call.

### Who made the call

Opal matches each call to a person by email and shows it on that person's Claude agent, which also appears in [Agent Inventory](https://docs.opal.dev/docs/agent-inventory.md). How Opal learns the email depends on the route:

* **HTTP hook alone.** The call carries no identity, so Opal uses the email of the Claude account that Claude Code's telemetry reports for the session. A session's first calls can reach Opal before its first telemetry export does. Opal attributes those calls when the export arrives, but a rule that names a person may not match them.
* **Kit.** Opal tries, in this order, the person's own sign-in token, the emails the kit reports (the email set at install, the Claude account's email, and the git email), and then the telemetry. The kit also reports the user name on the computer and the computer's name. If a person signed in to Claude Code with a personal account, that address is sent.

A call sent with a person's own sign-in token is for that person, whatever email the computer reports.

If a person has no Claude agent, Opal creates one from their first call when your organization has that turned on. Contact Opal support to turn it on. See [Claude Code and Cowork Agents](https://docs.opal.dev/docs/agent-inventory-claude-code.md). You can also sync Claude agents from your Anthropic organization first. See [Anthropic Setup](https://docs.opal.dev/docs/anthropic-agent-setup.md). A call that Opal can't match shows under the email the computer reported, with an **unknown** tag, or as **Unknown agent**.

### Claude Code's telemetry

The settings and the installer turn on Claude Code's own log export to Opal. Opal reads who is signed in to each session, how each call ended, and how long it took. With the managed settings, or an install with `--content`, it also reads the names of the MCP servers that a session connects to. Opal keeps a session's sign-in email, Claude account ID, terminal type, and Claude Code version for a day after the session's last export. It doesn't keep Claude Code's other events, such as API requests.

The managed settings also turn on Claude Code's tool details, which add each call's arguments and error text to the export. Opal doesn't read them.

### Conversation content

Opal turns on conversation content storage for each organization. Until it is on for yours, Opal stores none, whatever you choose in **Clients**. Contact Opal support to turn it on. The **Copy the settings** step says whether it's on. After that, **Store conversation content** decides for each client. Go to **Agent Center** > **Setup** > **Clients**, find Claude Code, and set it:

| Choice | What happens |
| - | - |
| Always (the default) | Every computer sends the conversation, and Opal stores it. |
| Each person decides | A computer with the kit sends it only if its person installed with `--content`, and Opal stores what it receives. Computers with the HTTP hook always send it, and Opal stores it. |
| Never | Opal stores none, even if a computer was installed with `--content`. |

To say yes under **Each person decides**, a person runs the install command with `--content`:

```bash theme={null}
curl -fsSL https://<your Opal>/downloads/claude-code-hooks/install.sh | bash -s -- --content
```

Managed settings run no installer, so a computer that gets only the kit from managed settings sends nothing under **Each person decides**. Computers that get the HTTP hook from managed settings send the conversation whatever each person chose, so **Each person decides** acts like **Always** for them. With the HTTP hook, tool output and conversation cross the network to Opal even when you choose **Never**, and Opal discards them. To keep the conversation off the network, choose **Never** and use the kit without the HTTP hook. Claude Code's log export, described above, still carries a failed call's error text, which Opal doesn't read. Computers installed with the Windows command send the conversation only with `-Content`. See [Windows](#windows).

When the conversation is sent, Opal gets each prompt, what each tool printed, and what the model wrote. With the kit, for a prompt's images, Opal gets the number and size, not the images. Opal masks credentials and personal data in the text it stores, and it cuts long text to a size limit. If **Log** is off for Claude Code, Opal stores no conversation content. These settings apply to your whole organization, and changes take effect within a few minutes, with no reinstall.

### Prompts that contain a secret

With the kit, Opal checks each Claude Code prompt for secrets on the person's computer, using the same patterns Opal uses to mask text. The prompt isn't sent for this check. Only the kinds of secret found are sent.

* With **Enforce** on, and once Opal has turned on enforcement for your organization, a prompt with a key or token that is recognized by its shape is blocked. Claude Code tells the person why and asks them to remove it.
* Otherwise, the prompt goes through and Opal records it as flagged.
* A secret that is recognized only by a name next to it, such as `DB_PASSWORD=`, is flagged and never blocked.

If **Log** and **Enforce** are both off, there is no check. Blocking doesn't keep the secret off the person's computer. Claude Code still writes the prompt to its transcript and history. The HTTP hook doesn't check prompts.

### Configuration report

The kit also reports each computer's Claude Code configuration: its MCP servers, enabled plugins, skills, subagents, and permission rules. It sends names, scopes, and how each server connects. It doesn't send environment values, headers, command lines, project folders, or the contents of skill and subagent files beyond their names and tool lists. It masks each permission rule's text on the computer and cuts it to 512 bytes. The kit sends the report when it differs from the last one Opal took, and otherwise at most every 6 hours. To see the servers, plugins, skills, and subagents, go to **Agent Center** > **Tools**.

### Who can see it

Admins and read-only admins can see all of this under **Agent Center** > **Activity**, and on the person's agent page. Other users can't.

## What isn't covered

* **Claude Code that doesn't get managed settings from claude.ai.** Managed settings from claude.ai reach only Claude Code signed in to your organization's Claude account. Claude Code on Amazon Bedrock or Google Cloud, and anyone who points Claude Code at their own API address (`ANTHROPIC_BASE_URL`), don't get them. For those computers, use the one-computer command or your device management tool.
* **The kit on Windows through managed settings.** Only the HTTP hook works there. To install the kit on a Windows computer, use the PowerShell command above.
* **Prompts with the HTTP hook.** The HTTP hook doesn't check prompts for secrets.
* **Calls that run when Opal doesn't answer.** If Opal is slow or can't be reached, the call runs anyway. The kit sends a late copy of the check, but Opal doesn't check that copy against your rules, so it can't stop the call. Treat rules as a guardrail, not a hard security boundary.
* **Cowork.** Cowork runs no hook. See [Cowork Setup](https://docs.opal.dev/docs/tool-call-governance-cowork.md).

## Turn it off or remove it

* **Switch Claude Code off for everyone.** Under **Agent Center** > **Setup** > **Clients**, turn **Log** and **Enforce** off for Claude Code. A client with both off sends no hook calls, and its tool calls run without Opal's check. Computers with the kit notice within a few minutes, with no reinstall. The HTTP hook keeps sending, and Opal drops what it receives and lets the call run. Claude Code's log export keeps sending too, and Opal still reads who is signed in and the names of MCP servers. To stop those requests, remove the managed settings or run the uninstall command. For what each combination of the two switches does, see [Tool Call Governance](https://docs.opal.dev/docs/tool-call-governance.md).
* **Remove it from one computer.** Run `bash ~/opal-hook/uninstall.sh`, then restart Claude Code. It asks you to confirm, and `--yes` skips that. It removes Opal's hooks and the log export settings it added from `~/.claude/settings.json` after saving a backup, and it also removes Opal's entries from Cursor's `~/.cursor/hooks.json`. It deletes `~/opal-hook/`, including events that weren't sent yet. It doesn't revoke the token. A person who can see **Settings** > **Personal Access Tokens** can delete it there.
* **Remove it from a Windows computer.** Download `https://<your Opal>/downloads/claude-code-hooks/opal-hook-kit-windows.zip`, unzip it, and run **Remove Opal Hook.cmd**.
* **Remove the managed settings.** Delete Opal's hooks and variables from your managed settings in claude.ai, or take the profile or file off the computers. The uninstall command doesn't undo managed settings. While they're in place, the next session start installs the kit again. After you remove them, run the uninstall command on each computer that got the kit.
* **Cut off the organization key.** Under **Agent Center** > **Setup** > **Anthropic**, find the **Organization key** step and select **Rotate key**. The old key stops working at once, and every computer that sends with it stops reporting until it gets new settings. Don't paste the new settings. This doesn't affect computers that send with a person's own token.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.