A Claude Code plugin that intercepts every tool call, evaluates it against your governance policy, and enforces the decision before execution proceeds.
VAIBot classifies each tool call by risk and returns an allow, deny, or approval-required verdict. Every decision creates a tamper-evident receipt with on-chain provenance anchoring. The plugin works with zero configuration — a free account is provisioned automatically on first run.
VAIBot also ships an MCP server that exposes governance tools Claude can call voluntarily. The plugin and the MCP server are complementary — they serve different roles:
| MCP server | This plugin | |
|---|---|---|
| Agent queries policy / status | ✓ | ✗ |
| Agent approves actions in-session | ✓ | ✓ |
| Enforcement happens before execution | ✗ | ✓ |
| Agent can skip or bypass the check | ✓ | ✗ |
| Audit trail the agent can't forge | ✗ | ✓ |
The MCP server gives the agent a way to query and interact with VAIBot. This plugin is what makes governance mandatory — it hooks into Claude Code's PreToolUse event before the tool executes, regardless of what the agent chooses to do. If the goal is a tamper-evident audit record or blocking a misbehaving agent, the plugin is the enforcement layer that actually enforces it.
Most deployments use both: the plugin for mandatory pre-execution enforcement, the MCP server so the agent can surface policy context and manage approvals in-session.
Recommended — install the whole stack in one command. The vaibot CLI is the entry point: it installs the guard, detects and wires your agents (including Claude Code), and sets a policy floor. macOS + Linux:
curl -fsSL https://raw.githubusercontent.com/vaibot-io/command-cli/main/install.sh | shOr install only the plugin from inside a Claude Code session:
# 1. Register the marketplace (clones the GitHub repo into Claude Code's cache)
/plugin marketplace add vaibot-io/claudecode-circuitbreaker-plugin
# 2. Install the plugin from that marketplace
/plugin install vaibot-governance@vaibot-claudecode
# 3. Activate without restarting Claude Code
/reload-plugins
The plugin lands at ~/.claude/plugins/cache/.../vaibot-governance/<version>/ (e.g. 0.2.2/). On first tool call the plugin auto-bootstraps a free-tier VAIBot account using a machine fingerprint and saves credentials to ~/.vaibot/credentials.json.
Allowed tool — passes through silently. A receipt is recorded in the background.
Approval required — Claude Code shows a native approval dialog:
VAIBot flagged this Bash call as elevated risk — command writes outside workspace.
content_hash: sha256:a3f9c1...
Approving here will record your decision in the VAIBot audit chain.
Allow? [Yes] [No, tell Claude]
Clicking Yes records the approval and the tool proceeds. Clicking No records a denial — the agent is told the action was blocked and why.
If you later approve the same action from the dashboard, the agent retries it automatically on its next attempt.
Hard deny — the tool is blocked outright. The agent receives the policy reason and reports it to you.
In observe mode — all tools proceed, but the policy verdict is logged to stderr:
VAIBot [observe]: Bash would be denial — command writes outside workspace.
The effective mode is resolved by the guard from your account and wins whenever the guard is reachable. VAIBOT_MODE is the local fallback, used only before the guard has answered — and it defaults to enforce.
Tool calls are blocked when the policy returns deny, and routed to Claude Code's native approval prompt when it returns approval_required. The agent sees the policy reason.
export VAIBOT_MODE=enforceAll tool calls proceed; the governance verdict is logged to stderr but never enforced (except the catastrophic floor). Use it to audit your agent — and as the escape hatch if enforcement ever blocks you (see Recovery / escape hatch).
export VAIBOT_MODE=observeOn first run with no API key, the plugin calls POST /v2/bootstrap with a machine fingerprint and provisions a free-tier account. Credentials are saved to ~/.vaibot/credentials.json and reused on every subsequent run.
If the account was already provisioned (e.g. by the OpenClaw plugin on the same machine) but the local key is missing, you'll see:
VAIBot: account exists but API key not found locally.
Check ~/.vaibot/credentials.json or set VAIBOT_API_KEY manually.
To claim your account and approve actions from the dashboard, visit the URL printed on first run or run /vaibot status.
A missing or unprovisionable key does not fail-closed. If /v2/bootstrap can't mint one (the account already exists and the local key was lost, or the endpoint is unreachable), the plugin governs locally with the built-in classifier:
- safe tools run,
- risky tools route to Claude Code's native approval prompt (no key needed),
- the catastrophic floor still denies (filesystem-root/home wipes, guard self-protection, fork bombs, …).
Server-backed receipts are skipped until a key is restored, so a fresh or key-lost machine keeps working — and can always recover itself.
If enforcement ever blocks you and you need out now:
# Instant escape: relaunch Claude Code in observe mode (allows all but the floor).
# This is a LOCAL offline fallback — it does NOT weaken enforcement once the guard
# is reachable and you have a key again.
VAIBOT_MODE=observe claude/plugin commands are slash commands, not tool calls, so you can update/reinstall the plugin even mid-block:
/plugin marketplace update vaibot-claudecode
/reload-plugins
To restore full (server-backed) governance, get a key back — any one:
vaibot login(allowed — it's a safe tool),- copy your key from https://www.vaibot.io →
export VAIBOT_API_KEY=vb_…, - or check
~/.vaibot/credentials.json.
| Command | Description |
|---|---|
/vaibot status |
Auth context, quota usage, and current governance mode |
/vaibot pending |
List tool calls waiting for approval |
/vaibot approve <content_hash> |
Approve a pending action |
/vaibot deny <content_hash> |
Deny a pending action |
/vaibot recent |
Recent governance receipts |
/vaibot policy |
Active governance policy |
All environment variables are optional.
| Variable | Default | Description |
|---|---|---|
VAIBOT_API_KEY |
(auto-provisioned) | Bearer token for the governance API |
VAIBOT_MODE |
observe |
observe or enforce |
VAIBOT_API_URL |
https://api.vaibot.io |
API base URL |
VAIBOT_TIMEOUT_MS |
10000 |
Request timeout in ms |
VAIBOT_FAIL_OPEN |
false |
If true, allow tool calls when the API is unreachable |
VAIBOT_DEBUG |
(unset) | Set to 1 for verbose decision logging |
VAIBOT_BREAKER_FAILURE_THRESHOLD |
3 |
Transient API failures within WINDOW_MS that trip the local breaker |
VAIBOT_BREAKER_WINDOW_MS |
10000 |
Sliding window for failure counting, in ms |
VAIBOT_BREAKER_COOLDOWN_MS |
60000 |
Auto-reset window after the breaker trips, in ms |
VAIBOT_BREAKER_DENYLIST |
(empty) | Tool names always blocked when tripped (the un-overridable safety floor) |
When the V2 governance API is unreachable, repeated transient failures trip a
local circuit breaker that takes over until the API recovers. Sliding window:
VAIBOT_BREAKER_FAILURE_THRESHOLD failures inside VAIBOT_BREAKER_WINDOW_MS
trip the breaker for VAIBOT_BREAKER_COOLDOWN_MS. While tripped:
- The local risk classifier re-decides each call: classifier-safe tools
pass through (
permissionDecision: allow). - Tools in
VAIBOT_BREAKER_DENYLISTare blocked (permissionDecision: deny). - Anything the classifier would ask/deny is denied with an actionable reason (approval can't be requested while offline — wait for cooldown or API recovery).
Only 5xx responses and network errors count as transient failures. 401/403 (authentication) and other 4xx responses do not trip the breaker — those are real verdicts or config problems, not transient outages.
Breaker state persists at ~/.vaibot/breaker-state/claudecode.json (mode
0o600) so trip state survives Claude Code restarts. In observe mode the
breaker still tracks failures but never blocks — it just logs a breadcrumb
when tripped.
Claude Code VAIBot API On-chain
│ │ │
├─ PreToolUse ────────────────►│ │
│ (tool, command, target) │ │
│ ├─ classifyRisk() │
│ ├─ makeDecision() │
│ ├─ buildReceipt() │
│ ├─ anchorProvenance() ──────►│
│◄─ allow/deny/ask ───────────┤ │
│ │ │
├─ [tool executes or blocked] │ │
│ │ │
├─ PostToolUse ───────────────►│ │
│ (outcome, duration) ├─ finalizeReceipt() │
│ │ │
Tools prefixed with mcp__vaibot are skipped automatically to prevent the governance plugin from governing itself.
Join the VAIBot Discord — get help, share feedback, and connect with other users.
VAIBot is in early access. If you're installing this plugin now, you're among the first developers putting verifiable AI governance into production. Early community members shape the roadmap directly — feature requests, policy design, and integration patterns all come from conversations in Discord.
To become a founding member, join the Discord and introduce yourself in #founding-members. Founding members get:
- Direct access to the VAIBot team
- Early previews of upcoming governance features
- Input on default policy design and approval workflows
- Recognition in the project
Uninstall with /plugin uninstall vaibot-governance@vaibot-claudecode. No state is written outside ~/.vaibot/ and a system temp directory (/tmp/vaibot-claudecode/).