Wardenby Bitmill
Documentation

Warden, explained.

Warden is a runtime control layer for AI coding agents. It hooks into every tool call your agent makes — evaluating, blocking, redirecting, or compressing it before it reaches your codebase. The result: fewer mistakes, less wasted context, and sessions that stay productive from turn 1 to turn 100.

Warden works with Claude Code and Gemini CLI. It installs in one command, requires zero configuration, and runs silently in the background. When a session is healthy, you won’t know it’s there. When a session starts degrading, Warden intervenes with precisely targeted corrections.

What Warden Does

  • Prevents destructive mistakes. Blocks rm -rf /, force pushes, credential leaks, and 300+ other dangerous patterns before they execute. Your agent never gets the chance to break something that matters.
  • Saves context budget. A single npm install or cargo build can dump 40,000 tokens of noise into the context window. Warden compresses that to a 2,000-token error summary. The agent gets what it needs, nothing more.
  • Redirects to better tools. When the agent reaches for grep, Warden transparently runs rg instead. When it tries find, Warden uses fd. Faster results, less output, better defaults.
  • Keeps sessions on track. Warden monitors focus, detects loops, tracks verification debt, and injects targeted corrections when the session starts drifting. Healthy sessions run silently; struggling sessions get guidance.

How It Works (30-second version)

Every time your AI agent makes a tool call, the following happens:

  1. Agent issues a tool call — a Bash command, a file read, a write, anything.
  2. The hook fires — Claude Code and Gemini CLI both support hook scripts that run before and after tool calls. Warden registers itself as those hooks.
  3. Warden evaluates — the daemon receives the call over IPC (named pipes on Windows, Unix sockets elsewhere) and runs it through the rule engine. All 300+ patterns are evaluated in a single RegexSet DFA pass.
  4. Decision is made — the result is one of three outcomes:
    • Allow (silent) — the command proceeds. The agent never knows Warden is there.
    • Deny — the command is blocked. The agent receives an explanation and a suggested alternative.
    • Allow + Advisory — the command runs, but the agent also receives a targeted hint (e.g., “4 files edited since last build — consider running tests”).
  5. Post-tool processing — after the command runs, Warden can compress the output, update session state, and detect patterns like loops or drift.

The entire round-trip completes in under 2 milliseconds. The agent never waits.

Installation

Install via npm (recommended) or Cargo. Both download a compiled Rust binary and set up the interactive wizard.

npx @bitmilldev/warden init

Cargo

cargo install warden-ai
warden init

The init wizard walks you through:

  • Creating the ~/.warden/ directory structure
  • Installing the binary to PATH
  • Detecting and optionally installing CLI tools (rg, fd, bat, etc.)
  • Configuring hooks for your AI assistant
  • Writing default configuration
  • Starting the background daemon

Troubleshooting Installation

cargo: command not found — Install Rust first via rustup.rs. After installing, restart your terminal so cargo is on PATH.

npx hangs or permission error — On Linux/macOS, you may need to run with sudo if your global npm prefix requires elevated permissions. Alternatively, configure npm to use a user-level prefix: npm config set prefix ~/.npm-global.

Windows PATH not updated — If warden isn’t recognized after install, the wizard may have added it to PATH but your terminal hasn’t reloaded. Close and reopen your terminal, or run refreshenv if using Chocolatey. The binary is installed to %USERPROFILE%\.warden\bin\ by default.

Firewall blocks the download — npx @bitmilldev/warden init fetches the binary from GitHub Releases. If your corporate network blocks this, download the binary manually from the releases page and place it in ~/.warden/bin/.

Quick Start

After installation, connect Warden to your AI assistant:

# For Claude Code
warden install claude-code

# For Gemini CLI
warden install gemini-cli

That’s it. Start a coding session and Warden activates automatically via hooks. No commands to run, no config to write.

What Happens After Install

Once installed, Warden runs as three components:

  • Hook scripts — registered with your AI assistant. These are tiny shims that forward tool calls to the daemon. You never edit or manage these directly.
  • The daemon — a background process that handles all evaluation, session tracking, and learning. It starts automatically when you begin a session and self-heals if it crashes (the next hook call restarts it).
  • The rule engine — compiled into the binary. Over 300 patterns across safety, substitution, hallucination detection, path protection, and more. No config files to maintain.

You can verify everything is working:

warden doctor

This checks that the binary is on PATH, the daemon is reachable, hooks are registered, and your AI assistant is configured correctly.

Updating

Check for new versions:

warden update --check

Apply the update:

warden update --apply

Updates download the new binary from GitHub Releases and replace the current one. Your configuration, session data, and learned patterns are preserved.

Uninstalling

warden uninstall

This removes hook registrations, stops the daemon, and optionally deletes all Warden data (~/.warden/). Your AI assistant will continue to work normally — it just won’t have Warden’s protection.

Supported Agents

AgentIntegrationStatus
Claude CodeNative hooks (PreToolUse, PostToolUse, etc.)Full support
Gemini CLINative hooksFull support

Both agents use a hook-based integration where the agent calls hook scripts before and after each tool use. Warden registers itself as those hooks and handles the rest. The integration is identical from Warden’s perspective — the same rules, the same session intelligence, the same output compression. The only difference is the wire format of the hook payload, which is handled by adapter modules internally.

Directory Structure

After installation, Warden creates the following structure:

~/.warden/
  bin/              # warden binary (and warden-relay.exe on Windows)
  config.toml       # Runtime configuration (optional, zero-config by default)
  rules.toml        # Global rule overrides (optional)
  data/
    <project-hash>/ # Per-project data
      warden.redb   # Session database (redb embedded key-value store)
      session-notes.jsonl  # Session event log
      panic.log     # Crash log (if any)

Project-level overrides live in your project repository:

<project-root>/
  .warden/
    rules.toml      # Project-specific rule overrides (commit this)

What’s Next