Documentation

Commands

Warden’s everyday surface is three commands. Everything else either runs by itself inside the background server, moved to an MCP tool the agent calls from chat, or lives under --debug as a diagnostic.

Command	Description
`warden init`	Interactive setup — installs hooks, registers PATH, starts the background server
`warden watch [--no-browser]`	Open the live dashboard at localhost:7433 (optional — the advisor runs without it)
`warden uninstall`	Remove hooks, binary and config

`warden init`

Interactive setup wizard. Creates the ~/.warden/ directory structure, installs Warden to PATH, detects missing CLI tools (rg, fd, bat, and the rest) and offers to install them, configures hooks for the assistant it detects, writes the default config, and starts the background server.

warden init

Run it again on an existing install and it detects what is already in place and skips those steps. Host detection is automatic — there is no separate per-assistant install step.

`warden watch`

Opens the live dashboard.

warden watch                # start the dashboard and open a browser
warden watch --no-browser   # start it, print the URL, don't open a browser

The dashboard is served by the background server at localhost:7433. If the server isn’t running, watch starts it first. The printed URL carries a session token, so use the URL watch prints rather than typing the bare host and port.

The port is fixed. It is baked into the hook URLs written at install time, so --port=N is accepted and ignored with a note.

watch is optional. The advisor, the hooks, and the background learning all run whether or not the dashboard is open. The dashboard is where the retired reporting commands went: diagnostics, session impact, live denials, learning statistics, the session scorecard, and the cross-project session list are all panels there.

`warden uninstall`

Removes hook registrations, stops the server, and optionally deletes all Warden data (~/.warden/).

warden uninstall

Your AI assistant keeps working normally afterwards — it just no longer has Warden in the path.

Flags

Flag	Description
`--version`	Print version
`--help`	Print the help text
`--update`	Check for and apply an update. Accepts `--check` (print only) and `--yes`/`-y` (skip the prompt)
`--debug <subcmd>`	Power-user tools (compile, doctor, state, replay, redb, and the rest)

warden --version
warden --update            # check, then prompt before applying
warden --update --check    # print what's available, change nothing
warden --update --yes      # apply without prompting

Configuration and session data are preserved across updates.

MCP tools

warden mcp serves these over stdio (JSON-RPC 2.0). They are the designated replacement for most of the retired commands: the agent calls them from chat, so the answer lands in context instead of in a terminal the agent cannot see.

Hooks vs MCP: hooks are automatic — they fire on every tool call without the agent doing anything. MCP is on-demand — the agent queries Warden when it wants guidance. Most sessions run entirely on hooks.

Tool	Arguments	Description
`session_status`	—	Session state: phase, quality score, turn count, anomaly alerts, token usage, recent errors.
`explain_denial`	—	Why the most recent command was blocked — the rule that fired, its category, and how to fix it.
`suggest_action`	—	What to do next, based on session state, error patterns, and phase.
`check_file`	`path`	Whether a file is safe and advisable to edit — known issues, co-change suggestions, recent error history.
`session_history`	—	The last 20 session events: edits, errors, milestones, denials.
`reset_context`	—	Signal a context pivot: clears session goal, action history, and working set.
`sprint_reset`	—	Sprint boundary reset for multi-agent harnesses. Returns a resume packet (key files, dead ends, verified state, conventions) and resets volatile session state.
`advisory_status`	—	Advisory budget visibility: how many advisories remain this turn, which categories are in cooldown, and the last budget adjustment reason.
`override_rule`	`rule_id`, `scope` (optional)	Disable a rule for the current session, or persist it to `.warden/rules.toml`. `scope` is `session` or `project`.
`phase_forecast`	—	Current phase, projected next-phase transition, and turns remaining before context pressure.

Diagnostics

When something looks wrong and the dashboard hasn’t answered it, these print what Warden currently believes. They are diagnostic output, not a stable interface — read them when troubleshooting, don’t build on them.

Command	What it tells you
`warden --debug doctor`	Whether the install is healthy, and what to fix if not
`warden --debug policy explain <path>`	Why a particular file is allowed or refused
`warden --debug logs [--tail <n>]`	This project’s recent log lines
`warden --debug explain-session`	Every intervention Warden made this session, in order
`warden --debug state`	The session state Warden is working from
`warden --debug benchmark`	Hook latency and savings measured on your own machine
`warden --debug server-status`	Whether the background server is running
`warden --debug restrictions list`	Every rule: its ID, category, severity, and whether you can disable it

restrictions list is the one to reach for when a deny message names a rule and you want to know what else that rule covers, or whether it can be turned off. --category <name> narrows it.