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

# Claude Code Plugin

> Reference for the Adrian Claude Code plugin: install, configuration, commands, enforcement modes, and what it captures.

The Adrian Claude Code plugin is a runtime security plugin for [Claude Code](https://claude.com/claude-code). It hooks every tool call the agent makes, classifies it with the Adrian backend, and enforces the result per your policy - blocking, prompting, or allowing before the tool runs. Unlike the [Python SDK](/reference/sdk), there is no code to write: it installs from the plugin marketplace and configures through a guided command.

```
Claude Code  ->  Plugin hook  ->  Adrian backend (WebSocket, protobuf)
                     |                   |
                     |                   ├─ Classify (M0 / M2 / M3 / M4)
                     |                   ├─ Store event + verdict
                     |                   └─ Return verdict
                     |
                     ├─ allow  (benign / policy off)
                     ├─ ask    (Human Review: prompt to approve)
                     └─ deny   (block before the tool runs)
```

## Install

From inside Claude Code:

```
/plugin marketplace add secureagentics/Adrian
/plugin install adrian-cc@adrian
# Reload so the plugin's slash commands register - without this, /adrian-init won't appear yet:
/reload-plugins
/adrian-init
```

1. **Add the marketplace** - registers the `adrian` marketplace from the Adrian repo.
2. **Install the plugin** - installs `adrian-cc` from that marketplace.
3. **Configure** - `/adrian-init` picks a backend, writes `~/.adrian/.env`, and verifies the connection.

Monitoring is active for new Claude Code sessions once `/adrian-init` reports OK.

<Note>
  No `pip install` step. The plugin vendors its only third-party dependencies (protobuf, websockets, certifi), so a working Python 3.12+ is all it needs.
</Note>

## Configure

`/adrian-init` is the guided path: it asks which backend you want (Adrian Cloud, a self-hosted OSS backend, or a custom URL), writes `~/.adrian/.env`, and asks you to drop your API key into that file - never into the chat. It then verifies the connection and reports the backend mode.

For Adrian Cloud, generate a key (`adr_live_...`) in your [dashboard](https://app.adrian.secureagentics.ai) and paste it into `~/.adrian/.env` when prompted.

## Commands

| Command          | Description                                                                   |
| ---------------- | ----------------------------------------------------------------------------- |
| `/adrian-init`   | Guided setup: choose backend, write `~/.adrian/.env`, verify the connection.  |
| `/adrian-status` | Show the configured backend URL, whether a key is set, and connection health. |

## Configuration

`/adrian-init` writes `~/.adrian/.env`. A value already set in the environment wins; otherwise a project-local `.env` (in the directory you launch Claude Code from) takes precedence over `~/.adrian/.env`.

| Variable                    | Default                  | Purpose                                                                                          |
| --------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
| `ADRIAN_API_KEY`            | *(required)*             | API key for backend auth. `adr_live_...` for Adrian Cloud.                                       |
| `ADRIAN_WS_URL`             | `ws://localhost:8080/ws` | Backend WebSocket URL. `/adrian-init` sets `wss://adrian.secureagentics.ai/ws` for Adrian Cloud. |
| `ADRIAN_CC_VERDICT_TIMEOUT` | `15`                     | Seconds to wait for a verdict before applying the fail-open / fail-closed rule.                  |
| `ADRIAN_CC_FAIL_OPEN`       | `true`                   | On timeout or backend error, allow (`true`) or block (`false`) the tool call.                    |

## Enforcement modes

Enforcement is server-driven: the backend policy decides the mode on login and the plugin acts accordingly. Nothing is hard-wired in the client.

| Mode                    | Behaviour                                                          |
| ----------------------- | ------------------------------------------------------------------ |
| **ALERT**               | Log only. Never blocks.                                            |
| **BLOCK**               | Deny in-scope high-risk tool calls before they execute.            |
| **HITL** (Human Review) | Prompt you in Claude Code to approve or deny the tool call inline. |

Which severity codes are *in scope* for action is also policy-driven. The default policy acts on high-risk codes (`M3` / `M4`), but a policy can act on any code. See [Severity codes](/reference/severity-codes) for what each M-code means and [How it works](/how-it-works) for the operating modes.

## What's captured

* **Every tool call.** Classified in real time at `PreToolUse`, before the tool runs.
* **Tool outputs.** Captured at `PostToolUse`.
* **Sub-agent activity.** `Agent` tool spawns are tracked with parent / child hierarchy.
* **Invocation grouping.** Events are grouped by the user prompt that triggered them.
* **Reasoning and instructions.** Claude's reasoning and your instructions are extracted from the session transcript.

Events and verdicts appear in your [dashboard](https://app.adrian.secureagentics.ai). PII is redacted before data leaves your machine - see [Security and Privacy](/security-and-privacy).

## Requirements

* **Claude Code.**
* **Python 3.12+** on your PATH (`python3`, `python`, or the `py` launcher on Windows).
* **Windows only:** Git for Windows (Git Bash). Claude Code runs plugin hooks under Git Bash by default; a `.cmd` launcher is bundled as a cmd.exe fallback.
* An Adrian backend and API key - Adrian Cloud, or a self-hosted OSS backend. `/adrian-init` walks you through it.

## Known limitations

* **Fail-open by default.** If the backend is unreachable or a verdict times out, tool calls are allowed so your workflow is never blocked by an outage. Set `ADRIAN_CC_FAIL_OPEN=false` to fail closed. A quiet session can mean the backend was simply unreachable - check `/adrian-status` first.
* **Effective next session.** Hooks load at session start, so installing, updating, or reconfiguring the plugin takes effect in new Claude Code sessions.
* **Pre-execution classification.** `PreToolUse` judges a tool call from its parameters before it runs; the verdict is based on the requested action, not its result.

## Updating

New versions ship through the marketplace. Refresh the marketplace, then update the plugin - a restart applies it:

```
/plugin marketplace update adrian   # refresh the marketplace from its source
/plugin update adrian-cc@adrian      # pull the latest plugin version (restart to apply)
```