Claude Code Plugin

The Adrian Claude Code plugin is a runtime security plugin for 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, 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

Add the marketplace - registers the adrian marketplace from the Adrian repo.
Install the plugin - installs adrian-cc from that marketplace.
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.

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.

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 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 for what each M-code means and 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. PII is redacted before data leaves your machine - see 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)

Get started

Concepts

Reference

Deployment

Claude Code Plugin

Install

Configure

Commands

Configuration

Enforcement modes

What’s captured

Requirements

Known limitations

Updating

​Install

​Configure

​Commands

​Configuration

​Enforcement modes

​What’s captured

​Requirements

​Known limitations

​Updating

Install

Configure

Commands

Configuration

Enforcement modes

What’s captured

Requirements

Known limitations

Updating