> Warden

Multi-provider / Terminal-native / MIT licensed

A lean, multi-provider, terminal-native LLM coding agent.

Single-binary CLI in Python 3.14. 21 builtin tools. Full MCP client and server mode. 6 permission modes with an 8-source precedence chain. 22 hook event types. A strictly layered architecture that keeps the internals from rotting into spaghetti as it grows.

Notify me when v0.1.0 ships Read the launch post →
warden -p "what is 2+2?" 
 $ warden -p "what is 2+2?" > what is 2+2?
The answer is 4.
[anthropic/claude-sonnet-4-6] cost: $0.00009 | 7 in / 5 out $ warden auth login --provider gemini [ok] credentials stored. $ warden -p "what is 2+2?" --provider gemini
4
[gemini/gemini-2.5-pro] cost: $0.00004 | 7 in / 1 out # Same tool. Three providers. One cost ledger.

Why multi-provider matters

Provider choice is configuration, not architecture.

POINT 01

Vendor lock-in is the new lock-in.

Switch providers per task, per session, per turn.

When the day-1 client only speaks one provider, your workflow is hostage to that vendor’s pricing, rate limits, and uptime. Warden treats provider choice as configuration you can change, not architecture you are stuck with.

POINT 02

Different models excel at different work.

Send prose to Claude, refactors to GPT-5, and quick draws to Gemini Flash.

Per-model cost tracking with hard USD caps. 80% / 100% threshold warnings before bills surprise you. 24 model entries across seven providers; pick the right one for the turn.

POINT 03

When one provider rate-limits, your work shouldn’t stop.

Re-target a session at a different provider mid-conversation.

Three providers fully wired today (Anthropic, OpenAI Platform + Responses, Gemini). Three more scaffolded (Bedrock, Vertex, Foundry) raising explicit NotImplementedError until they ship.

Provider matrix

Seven providers. Four wired. Three scaffolded.

24 model entries registered across the seven providers (19 platform + 5 OpenAI Responses). Scaffolded providers raise NotImplementedError on construction, so you can't reach for one by accident. When they ship, they ship.

Anthropic

Full

API key, OAuth (PKCE)

OpenAI (Platform API, Chat Completions)

Full

API key

OpenAI Responses API

Full

OAuth (PKCE port 1455) or device-code; subscription-billed

Gemini

Full

API key

Bedrock

Scaffolded

(planned) AWS SigV4

Vertex AI

Scaffolded

(planned) GCP ADC

Azure Foundry

Scaffolded

(planned) Azure AD

21 builtin tools

Same tool surface as the proprietary clients. Open source. MIT.

File read/edit/write, notebook edit, bash + PowerShell, web fetch + search, MCP resource access + auth, plan-mode controls, ask-user-question, agent spawning, task management. Every tool ships with its own permission rule grammar entry and runs under the same 8-source precedence chain.

Agent AskUserQuestion EnterPlanMode ExitPlanMode FileEdit FileRead FileWrite ListMcpResources McpAuth NotebookEdit PowerShell ReadMcpResource Shell SkillInvoke TaskCreate TaskGet TaskList TaskStop TaskUpdate WebFetch WebSearch

MCP, both directions

Most clients speak MCP in one direction. Warden speaks both.

Client mode

warden → other MCP servers

Connect Warden to filesystem servers, search servers, GitHub servers, or your own custom tooling. Anything that speaks MCP works. Each connected server's tools land in Warden's tool pool under the same permission grammar as builtins.

stdioSSEstreamable-HTTPin-process SDK

Server mode

other clients → warden tools

Run warden mcp serve and Warden re-exposes its 21 builtin tools to any MCP-speaking client. Bridge from another agent, hook Warden into a custom REPL, or build a multi-agent choreography where one Warden's tools drive another's turns.

FastMCP-backed

Permissions engine

Six modes. Five grammar shapes. Eight-source precedence chain.

Fail-closed by default. Two-stage LLM auto-classifier with explicit fall-back: structural deny → LLM-suggested deny → ask. Workspace-trust gate enforces a one-time per-directory acknowledgement before destructive actions. Hooks can override or augment any decision.

Permission modes

default acceptEdits plan bypassPermissions workspace-trust readonly

Stack-ranked at startup; bypassPermissions is intentionally loud and never sticky across sessions.

Rule grammar

  • exact Shell(npm test)
  • prefix FileWrite(/etc/*)
  • wildcard Shell(*)
  • tool-wide WebFetch
  • MCP-server-only mcp__github__*

22 hook events

Subprocess transport. JSON-decision protocol. Non-zero exit blocks.

Each event spawns a subprocess with the event payload on stdin; the hook emits a JSON decision on stdout and signals via exit code. Sync transport handles synchronous gating like permission decisions, while async transport covers long-running side effects such as telemetry and notifications. Hooks compose, so a deny from any hook blocks the tool call.

PreToolUse PostToolUse PostToolUseFailure PermissionRequest PermissionDenied UserPromptSubmit SessionStart Setup Stop SubagentStop SubagentStart Notification PreCompact PostCompact SessionEnd Elicitation ElicitationResult CwdChanged FileChanged WorktreeCreate InstructionsLoaded StopFailure

Compaction

Auto-fires at ~187K tokens. Manual /compact any time.

Compaction is not summarization. It is surgical message-array editing that preserves tool-use / tool-result pairing, keeps thinking-block signatures intact, and never silently destroys load-bearing context.

0
187K / 200K

// auto-compact triggers when estimated tokens approach the model's context window

system-reminder dedup

Identical system-reminder blocks collapse to one, keyed by content hash.

image age strip

Older image content blocks downgrade to text placeholders.

tool-result age decay

Older tool-result payloads truncate with a marker; newest N stay intact.

mandatory orphan cleanup

Tool-use / tool-result pairing mismatches caused by truncation are reconciled before the next turn.

Architectural discipline

Strictly layered. Sibling imports forbidden.

Each layer may import from any layer below it, never sideways and never upwards. That rule is checked automatically on every change, so a tangled dependency can't creep in. Cross-layer collaboration goes through dependency injection at the composition root, and architecture violations don't ship.

Tier 13 warden.cli entry points
Tier 12 warden.bootstrap composition root
Tier 11 warden.output rendering
Tier 10 warden.skills · warden.commands user-facing commands
Tier 9 warden.system_prompt · warden.compactor turn shaping
Tier 8 warden.turn_loop central loop
Tier 7 warden.tools tool dispatcher + 21 builtins
Tier 6 warden.file_ops · shell · web · subagents · tasks tool implementations
Tier 5 warden.mcp · warden.hooks extension surfaces
Tier 4 warden.session · warden.permissions · warden.memory session state
Tier 3 warden.api_client · warden.providers wire layer
Tier 2 warden.settings · warden.cost · warden.token_budget · auth cross-cutting
Tier 1 warden.types · warden.utils · warden.exceptions foundation

Cost tracking

Per-model Decimal accounting. Hard USD cap. No surprise bills.

24 model entries across seven providers, each with input/output/cached rates and a per-turn cost computation in Decimal precision. The session-level USD cap is enforced before each call, with warnings at the 80% and 100% thresholds and a hard stop if a turn would exceed the cap.

warden /cost 
 $ /cost Session cost ledger ─────────────────────────────────────────
anthropic/claude-sonnet-4-6 $0.04217 12 turns
  openai/gpt-5 $0.01893 3 turns
  gemini/gemini-2.5-flash $0.00088 2 turns
───────────────────────────────────────── Total $0.06198 17 turns
Cap: $5.00 (1.2% used) Warn at: 80%       100%

Memory + Settings

Two systems. Same discipline.

Memory

4-tier WARDEN.md walker

  • managed: vendor-pinned defaults baked into the binary
  • user: ~/.warden/WARDEN.md per-machine
  • project: ./WARDEN.md at repo root
  • local: ./.warden/WARDEN.md per-checkout

@include directives + frontmatter-conditional paths: selectors compose deterministically. Auto-memory memdir records cross-session lessons with secret-scanned writes.

Settings

6-layer config, policy trumps flag

  • plugin → user → project → local → flag → policy
  • Deep-merge reads. Replace-arrays writes.
  • Three-layer cache (in-memory · process · disk).

The policy layer is the override of last resort: an admin-supplied JSON that wins over any CLI flag. Internal writes from one layer don't leak into the cache for another.

Session persistence

Resume any session. By UUID, by file, or by "most recent for cwd".

JSONL transcripts

Every turn appended as a newline-delimited JSON record. Parse with standard tools. Replay deterministically.

Per-session cost ledger

Cost continues to accumulate against the original cap on resume. No double-billing on resumed sessions.

File-history backups

Every FileEdit / FileWrite snapshots the prior state. /rewind restores to any prior snapshot.

Resume by reference

warden --resume <uuid>, --resume-file path.jsonl, or warden --continue for the most-recent session in the current cwd.

Pairs with

TheAuditor

Warden ships a first-class integration with TheAuditor's database-first code intelligence. See architecture/24-theauditor-integration.md for the shared SQLite contract.

Pre-Alpha v0.1.0 MIT

Status & disclosures

What ships, ships. The known gaps are documented.

Warden is Pre-Alpha. Post-v0.1.0 audit-coherence waves are landing on main as the codebase reconciles toward v0.2. The README and Architecture.md are verified against live source, not stale design docs. If we know about a gap, we say so on the homepage of the README itself.

  • Three providers fully wired (Anthropic, OpenAI Platform + Responses, Gemini); three scaffolded (Bedrock, Vertex, Foundry) raising NotImplementedError on construction.
  • WebSearch is currently Anthropic-only.
  • Native Windows is best-effort; WSL is the proven path.
  • API and on-disk layouts may shift between Pre-Alpha waves. No semver promises until v1.0.

The ecosystem

Better alone. Unfair together.

Five focused tools for shipping with AI agents. Each stands on its own; together they cover code, action, orchestration, memory, and proof.

TheAuditor

Don't let agents guess about your code.

theauditortool.com →

Warden

Let agents act safely, across any provider.

you are here

Arbiter

The command center for your AI operation.

arbitermcp.com →

Curator

Don't let agents guess about you.

curatormcp.com →

BenchProctor

The SAST benchmark you can't game.

benchproctor.com →

Launch notifications

Get notified when Warden v0.1.0 ships.

No marketing fluff. One email when the binary lands and you can try it.

We use Buttondown. No spam. Unsubscribe anytime.