claude-warden

What install.sh does:

1. Checks prerequisites (jq required, warns if rg/fd missing). Detects platform. Backs up existing hooks and settings.json.
2. Prompts for a profile (or uses --profile). Deep-merges defaults.json + profile + user.json.
3. Symlinks (or copies) hook scripts + lib/ + statusline.sh into ~/.claude/.
4. Builds the Go collector and installs to ~/.local/bin/.
5. Generates warden.env (thresholds). Merges env vars and permissions into settings.json.
6. Validates JSON and shell syntax for every installed script.

Shell environment

Add to ~/.zshrc or ~/.bashrc:

# claude-warden env
source "$HOME/.claude/.warden/warden.env.sh"

Exports OTEL, token limit, timeout, and sandbox vars from your profile into every new shell.

Token savings accounting

All hooks report savings to ~/.claude/.statusline/events.jsonl at ~3.5 bytes/token (estimated). For exact counts:

export WARDEN_TOKEN_COUNT=api

Each truncation event spawns a background call to the Anthropic token counting API (free, separate rate limits) and appends a correction event. Zero added latency.

Requirements for API mode

ANTHROPIC_API_KEY in environment; python3 with anthropic installed

Custom Python path

Set WARDEN_PYTHON=/path/to/venv/bin/python3 if needed

Graceful degradation

Missing key, missing package, or network failure → silently exits, estimate stands

Disabling specific guards

Remove the corresponding matcher from settings.hooks.json and re-run ./install.sh. Example — disable read compression:

{
  "matcher": "Read",
  "hooks": [{"type": "command", "command": "$HOME/.claude/hooks/read-compress", "timeout": 7}]
}

Adding your own permission allow-list

cp config/user.json.template config/user.json

{
  "permissions": {
    "allow": ["Bash(gh api:*)", "Bash(pacman -Q:*)", "mcp__filesystem__list_directory"]
  }
}

Re-run ./install.sh to merge. User permissions are unioned with profile permissions — nothing is removed.

• timeout: Falls back to gtimeout (coreutils), then no-timeout
• stat: Uses -c%s (Linux) with -f%z (macOS) fallback
• flock: Replaced with mkdir-based locking (atomic on all POSIX)
• notify-send: Falls back to osascript (macOS), silently skips if neither available
• rg: Falls back to grep where used
• Binary detection: Uses od -An -tx1 | grep ' 00' (POSIX, works on macOS/Linux/BSD)

• Session tracking — per-session token counts, model info, context window in WAL-mode SQLite
• OTLP receiver — listens on :4319 for traces from Claude Code, extracts llm_request spans
• Subagent budgets — tracks call counts and bytes; writes deny files checked by pre-tool-use via stat()
• Hook events — accepts events via POST /v1/ingest/hook over Unix domain socket
• Query API — GET /v1/sessions, GET /v1/sessions/{id}/context (used by statusline)

Data storage — ${XDG_STATE_HOME:-~/.local/state}/claude-warden/:

Viewer — optional htmx web UI on port 8477:

python3 viewer/warden-viewer.py

Start (Linux):

cd monitoring && docker compose up -d

macOS / Docker Desktop:

cd monitoring && docker compose -f docker-compose.yml -f docker-compose.macos.yml up -d

Dashboards — four provisioned in monitoring/grafana/dashboards/: cost/tokens/budget (claude-code-otel), tool latency/traces (warden-tool-latency), output size/tokens (warden-output-size), subagent/session lifecycle (warden-subagent-lifecycle).

Verification:

curl -s http://localhost:3100/ready   # Loki
curl -s http://localhost:3200/ready   # Tempo
grep tool_latency ~/.claude/.statusline/events.jsonl | tail -5

API capture

MITM proxy wrapper in capture/ for recording Claude Code API traffic.

capture/claude                          # interactive session
capture/claude -p "prompt"             # non-interactive

Logs land in ~/claude-captures/YYYY-MM-DD/capture-HHMMSS.jsonl.

[!IMPORTANT] Bodies are truncated to 200 chars by default. Set WARDEN_CAPTURE_BODIES=1 for full capture. Sensitive keys (system, messages) are always redacted.

• Requires: mitmdump + trusted CA cert at ~/.mitmproxy/mitmproxy-ca-cert.pem
• Permissions: JSONL files created with mode 600
• Scrubbing: x-api-key, authorization, proxy-authorization headers redacted

1. Confirm ~/.claude/settings.json contains the hooks key: jq '.hooks | keys' ~/.claude/settings.json
2. Start a fresh session — hooks load at startup, not mid-session.
3. Commands in permissions.allow bypass the permission-request hook entirely.

read-guard blocks bundled/generated patterns (node_modules/, dist/, minified JS) and files larger than 2MB (configurable via warden.read_guard_max_mb). Use bounded reads or find the source file.

The base docker-compose.yml uses network_mode: host, which Docker Desktop does not support. Use the macOS override:

docker compose -f docker-compose.yml -f docker-compose.macos.yml up -d

This switches to bridge networking and replaces localhost with Docker service DNS names.

Claude Code gates hooks on workspace trust. Until the project's CLAUDE.md is accepted at launch, all hooks are skipped. Symptom:

Skipping PreToolUse:Bash hook execution - workspace trust not accepted

Fix: create a CLAUDE.md in the project root. Press Enter to accept it on next session start.