warden v0.10.1

A Claude Code plugin · v0.10.1

Your agent says the tests pass.
Warden checks.

Every task runs as a fixed list of steps, such as plan, implement, check, review and ship. Warden runs the checks and the code review itself, so nothing ships on the agent's word.

Get started View on GitHub

Warden is young and changes often.

example session
you/warden:compose add a dark mode switch to the settings page
agentType: feature
wardenwarden ran: lint (pass, 3.1 s), test (fail, exit 1, 12.4 s) on 1a2b3c4
wardenAPP-2: implement (2/5). Back from check: CODE.

Demo

See it in 30 seconds

What a run looks like on the warden site: the ticket board, a failed check going back to the agent, and only a proven commit shipping.

Music: "Blue Hill Valley" by Iros Young, from Uppbeat. uppbeat.io

The problem

An agent's word is not proof

An AI agent that writes code is fast. It will also, now and then, take a shortcut and tell you it is done.

  • It says the tests pass

    The report sounds sure. The tests are still red.

  • It pushes before review

    The change goes out before anyone has read the diff.

  • It changes the test

    A failing test gets "fixed" by editing the test, not the code.

How warden fixes it

Warden takes those calls away from the agent

Hooks block pushes and pull requests outside the ship step, and a step only ends when warden accepts its output. The review counts a weakened test or check as blocking.

  • Warden runs the checks

    Your test, lint and build commands run in the background. The proof is tied to the exact commit (its git SHA), so a later edit cancels it.

  • A second Claude reviews the change

    Blocking findings send the task back to implement. A change that weakens a test or a check counts as blocking.

  • Failures are sorted before they are fixed

    A failed check is triaged as CODE (the change broke it), OPS (the setup broke it) or UNCLEAR. Code failures go back to the agent; the others go to a separate fixer agent that works on its own branch.

  • Nothing ships unproven

    The ship step delivers the commit that passed the checks and the review, and nothing else.

How a run moves

One task, step by step

The agent asks warden what to do (warden next), does it, and hands in the result (warden done). Warden checks the result, moves the run on, and runs the gate steps itself.

Steps of the feature template: plan, implement, check, review, ship. A check that fails because of the change goes back to implement. A check that fails because of the setup, or for an unclear reason, goes to the fixer, then is checked again. Blocking review findings go back to implement. review: blocking findings check fails: CODE OPS or UNCLEAR check again planagent implementagent checkwarden runs your checks reviewa second Claude reads it shipPR or merge fixfixer agent, own branch ■ gate: warden runs it, not the agent
  1. 1

    plan agent

    The agent compares two or three options, picks one and writes a plan.

  2. 2

    implement agent

    The agent builds the change with tests and commits it.

  3. 3

    check gate: warden runs it

    Warden runs your check commands on that exact commit. Broken by the change (CODE): back to implement. Broken by the setup (OPS) or not clear (UNCLEAR): the fixer agent fixes it on its own branch; once the fix is on main, the check runs again. A flaky test does not go to the fixer: the run stops until someone fixes it and types retry.

  4. 4

    review gate: warden runs it

    A second Claude reviews the change. Blocking findings send the run back to implement.

  5. 5

    ship agent

    The commit that passed the checks and the review goes out as a pull request or a merge.

This is the feature template. The do template is only implement and check, chore is implement, check and ship with no review, bugfix adds reproduce and diagnose steps first, and you can build your own flow from seven step types. Workflows · How warden works

What you get

Key features

  • Workflows from templates

    do, chore, bugfix and feature, or your own flow built from seven step types.

  • Engine-run gates

    check and review steps are run by warden, not by the agent.

  • Self-healing checks

    Triage rules, a fixer agent and fix notes that the project keeps. See Gates and self-healing.

  • Human sign-off when you want it

    An approve step waits until a person types approve or reject: <why>.

  • Worktrees per task

    Each task gets its own git worktree and branch, so several tasks can run side by side.

  • Epics

    /warden:orchestrate works through a set of tickets in dependency order.

  • Project-owned tools

    Your project keeps its own tools (ticket tracker, code graph, pull requests) in .warden/tools/. Warden ships recipes and checks for them, not tool code. A project tools skill tells the agent which tools exist, and the retro counts what the agent ran, from Claude Code's own session records, to suggest the next tool.

  • A record of every task

    Steps, time and tokens are kept per task and shown on a local dashboard (warden site).

  • Periodic checks and retros

    Session start runs or offers the checks that are due.

  • Questions mid-step

    The agent can pause a step with warden ask; your next message is the answer. See Blocked and waiting runs.

  • Reports to the maintainers

    The agent can report a warden problem for you. Reports are kept on your machine; with write access to the warden repo they also reach the maintainers, and status changes and maintainer questions come back at session start. See Reports.

  • Guided upgrades

    Each version that changes your project's files ships an upgrade note, and /warden:upgrade applies it. See Upgrading.

  • Built for agents

    The agent loads the /warden:guide skill when it is unsure or refused; Guide for agents is the long form.

Quick start

Up and running in four steps

You need Claude Code, git, Bun 1.4 or newer (see Installation).

  1. Install the plugin, in a terminal or inside Claude Code (/plugin):

    bash
    claude plugin marketplace add thucxuong/warden#stable
claude plugin install warden@warden-marketplace

    Then restart Claude Code or run /reload-plugins.

  2. Open your project in Claude Code and set warden up:

    /warden:init

    It scans your stack, drafts context files and check commands, asks you to confirm, then writes .warden/. It also sets up the ticket tool: every run starts from a ticket, and without a tracker your tickets are Markdown files in backlog/.

  3. Commit the result and get it onto your main branch. warden start reads .warden/ from there.

    bash
    git add .warden .gitignore scripts/warden-setup.sh
git commit -m "chore: set up warden"
git push

    If your main branch is protected, push a branch, open a pull request with these files, and merge it before your first task.

  4. Start a task. Say what to do, or give the id of an existing ticket:

    /warden:compose fix the typo in the settings page title

    The agent creates the ticket with your ticket tool, picks a template, starts the run in its own worktree and works through the steps. When a step waits for you, the agent tells you what to type.

The quick start guide walks through a first feature task from start to ship.

Built for agents

Rules the agent can read

The agent in your project loads the /warden:guide skill when it is unsure or when warden refuses something. The guide for agents is the long form: the golden rules, the loop, how to hand in output, and what to do when blocked or waiting.

Read the guide for agents /warden:guide skill

The short versiondocs/for-agents.md

  • Warden decides the steps. You ask with warden next, do the step, and hand in with warden done.
  • Warden runs the checks and the code review itself. Your word that "tests pass" counts for nothing.
  • A person approves, rejects, retries and resets. You tell the user what to type.
  • When warden refuses something, it says why in a line that starts with warden:. Fix the cause. Do not look for a way around it.

Try it on your next task

Install the plugin, run /warden:init in your project, and start a task with /warden:compose.

Get started Read the docs

Type to search titles, headings and text.