Every token your agent spends on noise is a token it didn't spend on your actual problem. Warden fixes this.

Warden is a local context layer for AI coding agents. It drops into Claude Code, Cursor, Codex, Windsurf, Cline, Gemini, and 30+ other agents. Install once. Warden removes unnecessary tool-output noise, preserves important information, indexes your codebase for efficient retrieval, maintains useful memory across sessions — then verifies that compression did not lose critical information.

50-90% fewer tokens. Zero config. Zero cloud. Zero lock-in.

Benchmarked. 30-task suite. 72.3% overall reduction. 100% guard pass rate. 8ms avg overhead. See the numbers →

Why Warden?

Most context optimizers simply remove or summarize information. Warden verifies the reduction.

Raw agent output → Warden → Intelligent reduction → Verification → Agent

Warden stands between your coding agent and the firehose of tool output. The agent requests huge amounts of information. Warden decides what actually needs to reach the agent, then verifies the result — every retained line is checked byte-for-byte against the raw output. If anything was altered, the raw ships instead. No exceptions.

This is the differentiator: not just compression, but verified compression. You don't have to trust that Warden got it right — the trust guard proves it on every call.

Warden AI is a local context layer for AI coding agents. It is not a security firewall, authentication system, agent framework, or infrastructure management tool.

Install

All platforms (macOS, Linux, Windows, WSL):

npm install -g warden-ai && warden init

macOS / Linux / WSL (curl one-liner):

curl -fsSL https://raw.githubusercontent.com/rynald0cst0ltziam/Warden-AI/main/install.sh | bash

Windows (PowerShell one-liner):

irm https://raw.githubusercontent.com/rynald0cst0ltziam/Warden-AI/main/install.ps1 | iex

Windows users: do NOT use the curl command in CMD or PowerShell — bash triggers WSL on Windows. Use the PowerShell or npm command above.

~10 seconds · Node >= 22.5 · skips agents you don't have · safe to re-run

warden init does everything automatically:

| Step | What happens | |:-----|:-------------| | Register | Warden registered as MCP server in all detected agents (30+) | | Rules | Agent rules files written (CLAUDE.md, AGENTS.md, .cursorrules, etc.) | | Index | Code index built — call graph, imports, symbols, dead code | | Compress | Memory files compressed to save tokens every future session |

Restart your IDE. Start working normally. Warden runs automatically — no commands to remember, no settings to tune, no levels to pick. Max compression is always on.

See it working: your agent prints ‹warden› saved 4295 tokens (79%) on every tool call. Run warden hud for a live terminal HUD. Run warden dashboard for a web UI at http://localhost:7878.

warden doctor          # see which agents are detected (16 checks)
warden init            # re-register after installing a new agent
warden benchmark       # see real benchmark numbers on your own files

Warden detects and registers for: Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI, Cline, Roo Code, Continue, VS Code Copilot, Zed, JetBrains, Amazon Q, Gemini CLI, Antigravity, Aider, Goose, OpenHands, opencode, Augment Code, Warp, Cody, Tabnine, Replit AI, and more.

Before / After

Same grep query. Same information. 79% fewer tokens.

Without Warden — 4,295 tokens:

$ grep -rn "function auth" src/
src/auth/login.ts:15:export function login(user) {
src/auth/login.ts:16:  const token = signJWT(user);
src/auth/login.ts:17:  if (!token) throw new Error("no token");
src/auth/login.ts:18:  return { token, user };
src/auth/middleware.ts:45:export function authMiddleware(req, res, next) {
src/auth/middleware.ts:46:  const token = req.headers.authorization;
src/auth/middleware.ts:47:  if (!token) return res.status(401).send("no token");
... (138 more matches)

With Warden — 883 tokens:

warden_grep({ pattern: "function auth" })

  200 matches → 12 relevant
  ‹warden› removed 50 duplicates
  ‹warden› collapsed 138 low-signal
  guard: every line verbatim ✓
  saved: 4295 → 883 tokens (-79%)

  src/auth/login.ts:15    export function login(user)
  src/auth/login.ts:22    export function logout()
  src/auth/middleware.ts:45    authMiddleware(req,res,next)
  src/auth/token.ts:8     export function generateToken()
  src/auth/token.ts:31    export function verifyToken()
  ... 7 more (use warden_retrieve for full)

Every line in the pruned output exists verbatim in the raw — verified by the trust guard.

AST-aware read modes

warden_file_read now supports 5 read modes beyond the default auto-pruning:

// Signatures only — symbol declarations, no bodies (80-90% savings)
warden_file_read({ filePath: "src/auth.ts", mode: "signatures" })
// → export interface User { ... }
//   export class AuthService { ... }
//   async login(user: string, pass: string): Promise<AuthToken>
//   ...

// One symbol by name — just that function/class body
warden_file_read({ filePath: "src/auth.ts", mode: "symbol", symbolName: "login" })
// → the 7 lines of the login() method, nothing else

// Outline only — structural headers, no bodies
warden_file_read({ filePath: "src/auth.ts", mode: "outline" })

// Imports only — just import statements
warden_file_read({ filePath: "src/auth.ts", mode: "imports" })

// Full — no pruning (when you need everything)
warden_file_read({ filePath: "src/auth.ts", mode: "full" })

Powered by the tree-sitter code index. Every line in the output is verbatim from the source file — the trust guard verifies it. When no index is available, falls back to regex-based header detection.

MCP proxy mode

Warden can wrap any upstream MCP server and compress its tool descriptions, inputSchemas, and tool-call responses — and optionally replace the full tool catalog with a tiny lazy-loading surface:

{
  "mcpServers": {
    "fs-shrunk": {
      "command": "warden",
      "args": ["proxy", "npx", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}

The proxy spawns the upstream server, intercepts tools/list / prompts/list / resources/list responses, and compresses description fields using Warden's compression engine. Technical identifiers (code, paths, URLs, version numbers) are preserved. All other messages pass through unchanged.

# Wrap any MCP server (lazy-loading + schema compression ON by default)
warden proxy npx @modelcontextprotocol/server-filesystem /tmp

# Custom fields + debug logging
warden proxy npx @modelcontextprotocol/server-github --fields description,summary --debug

# Compression level
warden proxy npx some-mcp-server --level ultra

# Also prune tools/call response content (guard-verified, removal-only)
warden proxy npx @modelcontextprotocol/server-filesystem /tmp --prune-responses

# Disable lazy-loading (show full tool catalog)
warden proxy npx some-mcp-server --no-lazy

# Disable schema compression (keep full inputSchemas)
warden proxy npx some-mcp-server --no-compress-schema

# All features combined
warden proxy npx some-mcp-server --lazy-level medium --compress-schema --prune-responses

Lazy-loading mode (--lazy)

Replaces the full tool catalog with 3 meta-tools. The client sees a tiny surface and loads schemas on demand:

• warden_list_tools — returns a compact index of tool names and short descriptions
• warden_get_tool_schema — returns the full inputSchema for one tool
• warden_invoke_tool — forwards a tools/call to the upstream

The full schemas are cached from the upstream's tools/list response and returned on demand. This reduces initial context by 97.9% on a 50-tool server (14,105 → 297 tokens).

Lazy listing levels (--lazy-level):

| Level | Format | Description included | |-------|--------|---------------------| | low | name(arg1, arg2): full compressed description | Full (compressed) | | medium | name(arg1, arg2): first sentence | First sentence only | | high | name(arg1, arg2) | None | | max | name | None |

• On by default. Disable via --no-lazy (or WARDEN_PROXY_LAZY=0).
• --lazy-level controls compactness (default: medium).

inputSchema compression (--compress-schema)

Strips cosmetic JSON-Schema fields that add tokens without affecting validation: title, default, examples, $schema, $comment, readOnly, writeOnly, unreferenced $defs/definitions. Compresses description strings within schema properties using Warden's prose compression engine.

Never touches validation constraints: type, required, enum, minimum, maximum, pattern, items, properties, additionalProperties, oneOf, anyOf, allOf, not, $ref, deprecated, etc. are preserved exactly.

• Measured 21.5% additional reduction on top of description compression.
• On by default. Disable via --no-compress-schema (or WARDEN_PROXY_COMPRESS_SCHEMA=0).

Guard-verified response pruning (--prune-responses)

Description-only compressors deliberately never touch tools/call responses — rewriting a tool's output is unsafe. Warden can prune them safely because the trust guard enforces that the pruned output is a verbatim subsequence of the raw: lines are removed, never altered. If the guard fails or nothing is removed, the original ships untouched.

• Opt-in via --prune-responses (or WARDEN_PROXY_PRUNE_RESPONSES=1); off by default.
• Runs each text content block through Warden's pruning engine (same trust guard as the wrapper tools).
• Measured ~79% reduction on a large, low-signal tool result — with every retained line byte-for-byte identical to the original.

Works with any MCP client (Claude Code, Cursor, Windsurf, Codex, Gemini). Stdio-based — no HTTP server needed.

Benchmarks

30 tasks. Measured, not estimated. One command to reproduce:

npx tsx benchmarks/run-bench.ts

| Category | Tasks | Raw tokens | Pruned tokens | Reduction | Avg overhead | |:---------|------:|-----------:|--------------:|----------:|-------------:| | grep | 5 | 55,655 | 6,944 | 87.5% | 17ms | | file read | 5 | 45,360 | 9,814 | 78.4% | 6ms | | generic (auto-routed) | 5 | 38,166 | 3,495 | 90.8% | 9ms | | shell output | 5 | 16,556 | 4,226 | 74.5% | 4ms | | file compression | 5 | 41,763 | 27,933 | 33.1% | 11ms | | test log | 5 | 17,080 | 7,037 | 58.8% | 4ms | | OVERALL | 30 | 214,580 | 59,449 | 72.3% | 8ms |

• 100% trust guard pass rate — every pruned line verified verbatim against raw
• 8ms average overhead — negligible vs agent API latency (1-10s)
• Shell-output pruning: 24 command pattern detectors (git log/diff/status, npm install/ls/build, docker logs/build/ps, cargo build, kubectl logs/get, ps aux, find, tree, make, go test/build, pip install, mvn, gradle, rustc, tsc) — 74.5% avg reduction
• Raw data: CSV + JSON in benchmarks/results/
• Honest numbers: HONEST-NUMBERS.md — what these numbers mean and what they don't
• Methodology: benchmarks/README.md — fixtures, task selection, reproduction

What it does

Verified context optimization across eight layers. One MCP server. Zero config.

| Layer | What it does | Savings | |:------|:-------------|:-------:| | Code intelligence | Index functions, imports, call sites. Query call graph, impact, dead code | 100x fewer round trips | | Context selection | Recommends files for the task with 2-hop symbol expansion | 80%+ smaller context | | Tool output pruning | warden_grep, warden_file_read, warden_run_tests, warden_run_command | 50-91% per call | | Agent memory | Decisions persist across sessions with lifecycle (reaffirm, supersede, archive). Hybrid search: FTS5 keyword + semantic vector (all-MiniLM-L6-v2, local ONNX). Failed approaches surface as warnings | 0 repeated mistakes | | Response compression | Rules drop filler, preamble, narration. Code stays verbatim | 45-65% per reply | | File compression | warden compress strips filler from memory files, no LLM call | up to 32% per file | | Description compression | 32 tool descriptions compressed before sending | ~41% per turn | | Session continuity | warden_handoff reads previous session at start, writes at end | 0 cold starts | | Git context | File history, blame, churn metrics — know if code is stable or volatile | fewer surprises | | Sufficient context | Unified context: files + past decisions + failed approaches + git volatility + token budget | 90%+ smaller context | | Task reports | Per-task and project-wide reports with overhead timing | measure what matters |

Safety net — always on

| Mechanism | What it does | |:----------|:-------------| | Trust guard | Every pruned line verified verbatim against raw. If altered, raw ships instead. | | Eval gate | Rules earn confidence through real samples before going live. | | Regression watchdog | Tracks task success rates. Auto-reverts rules that degrade outcomes. | | CCR | Every cut reversible. Full original cached 7 days. warden_retrieve with --around and --lines. |

Code intelligence

// Who calls auth() and what does auth() call?
warden_call_graph({ function: "auth" })
// → Callers: login(), UserService.isValid()
//   Callees: checkToken(), generateToken()

// What's affected if I change src/auth.ts?
warden_impact({ filePath: "src/auth.ts" })
// → Risk: HIGH — 5 dependents, 12 callers

// Project overview in one call
warden_architecture({})
// → TypeScript: 57 files, 251 symbols, 2061 calls

// Find dead code
warden_dead_code({})
// → 3 functions with zero callers

// Search for symbols
warden_search_symbols({ pattern: "auth" })
// → 8 matches across 4 files

Powered by tree-sitter (WASM — no native compilation, works on Windows/macOS/Linux). Supports 30+ languages including TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, C#, Ruby, PHP, Swift, Kotlin, Scala, Lua, Dart, Elixir, and more — extracting functions, classes, methods, interfaces, types, enums, imports, and call sites.

Trust guard

40 lines. Read them yourself.

src/pruner/guard.ts — the non-negotiable rule:

Every non-annotation line in the pruned output
must appear verbatim in the raw output.
If it doesn't, the raw is shipped instead.
No exceptions. No heuristics. No silent rewrites.

Code, shell commands, and error text are included-or-excluded wholesale — never altered. Safety first, optimization second.

Evolution & measurement

Warden doesn't just prune — it measures itself and evolves its memory.

Task reports

warden task-report --all
# WARDEN PROJECT REPORT — ALL TIME
# Total prune calls:     143
# Tokens saved (gross):  186,038
# Reduction:             77.9%
# WARDEN OVERHEAD
#   Processing time:      34ms
#   Overhead tokens:      34 (est.)
#   Net tokens saved:     186,004

Per-task or project-wide. Includes overhead timing — Warden measures its own cost and subtracts it from gross savings to report net tokens saved.

Memory lifecycle

Decisions aren't static. They evolve:

warden_memory_save({ category: "decision", title: "Use PostgreSQL", body: "...", sourceType: "documentation", evidence: ["docs/arch.md"] })
warden_memory_reaffirm({ id: 42 })     // decision confirmed again — boosts confidence
warden_memory_supersede({ oldId: 42, newId: 55 })  // old decision replaced
warden_memory_archive({ id: 42 })      // no longer relevant
warden_memory_mark_contested({ id: 42 }) // someone disagrees

Failed approach tracking

When something doesn't work, Warden remembers:

warden_memory_save({ category: "failed_approach", title: "Redis for sessions", body: "Lost persistence in deploy. Do not retry.", outcome: "failure" })
// Later, when starting a similar task:
warden_memory_failed_approaches({ query: "session storage" })
// → WARNING: Redis for sessions — failure. Do not retry.

Sufficient context — one call, everything you need

warden_sufficient_context({ task: "fix auth token expiry", tokenBudget: 2000 })
// → FILES (3 files, categorized, with git churn)
// → PAST DECISIONS (2 recalled decisions)
// → FAILED APPROACHES (1 warning — don't use Redis for this)
// → VOLATILITY NOTES (auth.ts: 8 commits — volatile, expect recent changes)
// → TOKEN ACCOUNTING (budget=2000, used=1847, trimmed=yes)

Combines file recommendations, past decisions, failed approach warnings, git volatility, and token budget trimming into a single response. Replaces warden_context_select when you want the full picture.

Works with 35+ agents

| | | | | | |:---:|:---:|:---:|:---:|:---:| | Claude Code | Claude Desktop | Cursor | Windsurf | Codex CLI | | Cline | Roo Code | Continue | VS Code Copilot | Zed | | JetBrains | Amazon Q | Gemini CLI | Antigravity | Aider | | Goose | OpenHands | opencode | Augment Code | Warp | | Cody | Tabnine | Replit AI | + more | |

If your agent supports MCP, Warden works with it.

Commands

| Command | What it does | |:--------|:-------------| | warden init | Register in all agents + write rules + build index + compress files | | warden serve | Run MCP server over stdio (called by agents automatically) | || warden proxy <cmd> [args] | MCP proxy — wrap any upstream MCP server: compress descriptions, schemas, responses; lazy-loading meta-tools (--fields, --level, --debug, --prune-responses, --lazy, --lazy-level, --compress-schema) | | warden status | Rules, confidence, tokens saved, recent memories | | warden hud | Live terminal HUD (Ctrl+C to exit) | | warden dashboard | Web UI at http://localhost:7878 | | warden doctor | Health check — 16 checks, clear pass/fail | | warden benchmark | Run actual benchmarks on real files — see benchmarks/README.md | | warden compress <file> | Compress a memory file (max compression) | | warden index | Index project code structure | | warden graph <fn> | Query call graph: who calls X / what X calls | | warden impact <file> | Impact analysis: blast radius of changes | | warden architecture | Project overview: languages, packages, entry points | | warden handoff | Generate session handoff for next session | | warden handoff --read | Read previous session's handoff | | warden ccr | CCR cache stats | | warden ccr retrieve <hash> | Retrieve original output (--around, --lines) | | warden memory list | List all stored memories | | warden memory recall <query> | Search memories | | warden task-report | Per-task report: tokens saved, overhead, outcomes (--all, --since, --until, --task) | | warden git-context <file> | Git history, blame, churn metrics for a file (--start, --end, --blame) | | warden sufficient-context <task> | Unified context: files + memories + failed approaches + git volatility (-b budget) | | warden rules | Write agent rules files |

MCP tools

32 tools. All called automatically by your agent via the rules file.

| Category | Tools | |:---------|:------| | Tool wrappers | warden_grep · warden_file_read · warden_run_tests · warden_run_command | | Context & intelligence | warden_context_select · warden_sufficient_context · warden_index · warden_call_graph · warden_impact · warden_architecture · warden_search_symbols · warden_dead_code | | Memory | warden_memory_save · warden_memory_recall · warden_memory_list · warden_memory_forget · warden_memory_failed_approaches · warden_memory_reaffirm · warden_memory_archive · warden_memory_mark_contested · warden_memory_reject | | Git context | warden_git_context — history, blame, churn metrics | | Eval & outcomes | warden_record_outcome · warden_outcome_stats · warden_task_report | | Status & audit | warden_status · warden_report · warden_prune · warden_compress | | CCR (reversibility) | warden_retrieve · warden_ccr_status | | Session continuity | warden_handoff — read: true at start, generate at end |

Privacy

No cloud. No API server. No telemetry. No analytics. No phone-home.
Your code, tool outputs, and pruning decisions stay in a local SQLite
file on your machine. It works on a plane.

The only network code: localhost-only dashboard — bound to127.0.0.1, no external access.

Audit it yourself — the full source is public. The trust guard is 40 lines in src/pruner/guard.ts.

Requirements

• Node.js >= 22.5 (uses built-in node:sqlite)
• Any MCP-compatible AI coding agent (30+ supported)

Tech stack

| Component | Technology | |:----------|:-----------| | Runtime | Node.js 22.5+ (built-in node:sqlite, no native deps) | | Language | TypeScript 5.x, ESM | | MCP protocol | @modelcontextprotocol/sdk | | Code parsing | tree-sitter WASM (30+ languages, no native compilation) | | Storage | SQLite (via node:sqlite) — FTS5 + semantic vector search (all-MiniLM-L6-v2, local ONNX) | | Build | tsup (esbuild) | | Tests | Vitest (568 tests, 36 files) | | Search | ripgrep (auto-detected, optional) | | Dashboard | HTTP server, localhost-only, CSP headers | | CLI | Commander.js | | License | PolyForm Shield1.0.0 |

License

PolyForm Shield1.0.0 — source-available, free for everyone including commercial use. See LICENSE and TRADEMARK.md.

Support Warden

Warden is free and always will be. No paywall, no license key, no gated features. If it saves you tokens, consider a donation:

| Amount | What it does | |:-------|:-------------| | $5 | Say thanks — a small thank-you for a tool you use daily | | $10 | Buy lunch — covers development time, the fair price for daily use | | $25 | Fund a feature — supports ongoing development and the features you want next |

PayPal: paypal.me/rynald0s

Bitcoin: 1Jt3kETWcWkAsNKrc6WsPLKnkkSTe3Uv5o

Honor system. Warden is fully functional without donating. No gated features, no license keys, no "pro" version. If it saves you tokens and you want to support development, donate. If not, use it free. That's the deal.