Warden Ai

Verified context for AI coding agents.

Your AI agent burns tokens on noise. Warden stops that.

Less context. More signal. Verified.

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:

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

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):

• 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

• 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.

Safety net — always on

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

If your agent supports MCP, Warden works with it.

Commands

MCP tools

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

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

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:

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.

Install · Website · GitHub · npm · Issues · Donate

Made with ⚡ by Rynaldo Stoltz