Warden – run a fleet of coding agents without losing your mind

Warden is a free, self-hosted Go binary that orchestrates fleets of coding agents in isolated git worktrees, tracking costs and token savings without a database or telemetry. The tool supports multiple agent backends, a live TUI and web dashboard, and an MCP server for agent-driven coordination, with an autopilot mode that autonomously manages worker agents through CI and PRs.

📖 Docs & guide: https://srjn45.github.io/warden/ Run a fleet of coding agents without losing your mind. warden is a single Go binary warden , aliased wd that spawns, monitors, and tears down coding-agent sessions — each in its own isolated git worktree — while tracking exactly what every agent costs and how many tokens its lifecycle features keep out of context. It drives multiple agent backends Claude Code by default — see Agent backends agent-backends---backend , backed by a local daemon and a file-based JSON store: no database, no SaaS, no telemetry. Orchestrate, don't babysit — spawn many agents in parallel, watch them in a live TUI cockpit or web dashboard, and talk to any one of them. Write-type agents get their own worktree by default, so parallel agents never collide on the same tree. See what it costs — warden spend prices each agent's real model usage into dollars with a budget gate priced for the Claude backend; bring-your-own-model backends report tokens , and warden savings is an append-only ledger of the tokens warden keeps out of agents' context, with a without-vs-with A/B benchmark you can screenshot. Self-hosted and free — one binary, a loopback REST API, and a JSON store on disk. Run it on your laptop or a box. By default nothing leaves your machine — no telemetry, no SaaS. Opt-in features webhook/Slack alerts, remote access, and warden savings --calibrate send data only where you explicitly configure them. Driven by an agent itself — warden mcp exposes the whole fleet as MCP tools, so an orchestrator agent e.g. a Claude session can spawn, query, and coordinate the fleet for you. go install github.com/srjn45/warden/cmd/warden@latest or grab a release binary see Install warden setup --yes install missing deps tmux, claude, … ; warden doctor just checks warden tutorial guided tour of the core loop: spawn → watch → commit → tear down warden start "review the auth module for security issues" spawn your first agent warden tui open the cockpit go install gives you the CLI / daemon / TUI / MCP server. For the embeddedweb dashboard, use a release binary or build with make release — see Install . Architecture — one binary, multiple faces warden daemon is the single writer to the on-disk session store, serving a loopback REST API and running a background poller. warden ls|status|start|done|attach|send|tail are thin HTTP clients to the daemon. warden mcp is a stdio MCP server that bridges MCP tool calls to the same REST API, enabling an orchestrator agent session e.g. Claude to query agents and talk to a specific running agent. A short alias wd a symlink to warden is installed alongside it. alias agents=warden New here?See docs/USAGE.md for a task-oriented guide to running agents day to day, docs/FEATURES.md for a complete catalog of what warden can do, and FEATURES.md for the at-a-glancecoverage matrix which of CLI / MCP / skill / web / TUI can drive each feature . The sections below cover build, install, and contributor setup. Capability highlights from recent releases full notes on the releases page https://github.com/srjn45/warden/releases ; the complete catalog lives in docs/FEATURES.md /srjn45/warden/blob/main/docs/FEATURES.md : Autopilot — a goal-directed, long-running autonomous mode. Author a plan file autopilot.plan.yaml , run warden autopilot init to scaffold the config, then warden autopilot on to start. A manager agent role autopilot drives a fleet of worker agents role worker , one per task in isolated worktrees, gates their PRs through CI, and lands them into autopilot/integration — all without human intervention, spawning a resolver role brain on demand to unblock a stuck worker. A guardian heal loop keeps the manager alive through stalls, a daemon-internal overwatch nudges it to tend idle/waiting workers, and a cost-tier backend ladder escalates from free Antigravity to subscription Claude, Codex when rate-limited. The kill switch is warden autopilot off . The switch is per-repo — warden autopilot on enables only the current repository add --repo <root to target another , the enabled set is persisted so repos come back up across a daemon restart, and the manager marks its plan status: complete in place when it finishes so a done run is never re-run. See Autopilot guide https://srjn45.github.io/warden/guides/autopilot/ and Autopilot concepts https://srjn45.github.io/warden/concepts/autopilot/ . Live config hot-reload — edit ~/.warden/config.yaml and warden applies it with no daemon restart : the autopilot template, auto approve policy, token/context guard tokens. , rails. , model default , default permission mode , hint gates, and notify. /webhook all re-apply on the next tick or spawn. A bad edit keeps the last-good config and alerts you rather than falling back to defaults; keys that genuinely need a restart addr , data dir , timers, loop cadences are logged as changed-but-pending. See Configuration /srjn45/warden/blob/main/docs/FEATURES.md 12-configuration-yaml-config-file . Agent roles — attach a named, persistent --role persona to an agent at spawn warden start … --role reviewer or switch it on a running agent warden set-role <id reviewer , which relaunches to re-inject . Five built-in roles — general default, no persona , orchestrator , implementer , auto-merger , reviewer — each carrying a persona plus default spawn flags e.g. reviewer defaults --type pr-review , auto-merger turns on auto-approve . warden role list shows the catalog; the TUI new-agent form has a ctrl+r role picker and the web + New agent modal a Role dropdown. See Agent roles warden-role-list--warden-set-role . Resilience & ergonomics round-up — warden recover re-registers archived-but-alive agents tombstone-reaper safety net ; the web /tui cockpit self-heals validated and auto-rebuilt if wedged; warden tui --rebuild-web-cockpit forces it ; warden tui inside an existing tmux session lays out as a native tmux window instead of erroring --tmux-native ; wd push --force-with-lease for safe force-pushes; rate-limit auto-resume now also answers Claude's wait-menu and monthly spend cap rate limit.spend retry interval ; and all daemon stores sessions, pipelines, schedules, snapshots, context, mailbox run on an embedded ScrivaDB — still no database server. Isolation guardrails v5.0, breaking — write-type agents code / docs / website / debug-ci / tests now spawn into their own worktree by default --in-repo opts out , backed by PreToolUse hooks that deny-redirect raw git /test commands to the first-class warden commit / push / sync / check tools. See Lifecycle commands & boundary enforcement lifecycle-commands--boundary-enforcement . Interactive mode — a terminal REPL with a real line editor history, a live warden repl / -command menu, Tab completion, guided argument forms, colour that drives the fleet via deterministic / commands no model or natural language a local-LLM conductor that turns operator intent into confirmed warden tool calls without spending cloud-model tokens ; optionally hosts the cockpit master pane. Pipelines, end to end — DAG pipelines are now drivable from the MCP tools create/start/show/list/cancel , ship four built-in --template starters, and support run if conditional steps. Agent sub-trees in the TUI — agents spawned by another agent nest under their parent as a collapsible sub-tree ▸ / ▾ , indented per depth ; deleting a parent with live children leaves a muted terminated tombstone header so the children never orphan, reaped once the sub-tree finishes. Fleet at scale — full-text warden search + tags, a warden history archive, warden export / import , an append-only warden audit log , spawn preset s and variabled prompt-template s browse both via warden library , and web batch operations. Observability — per-agent metrics & performance history warden stats , crash/anomaly detection, the context-size guard, and webhook/Slack notifications. Token-savings ledger — a real, append-only ledger of the tokens warden's lifecycle features keep out of agents' context, with an warden savings --benchmark A/B headline without-vs-with warden, % reduction, $ saved you can screenshot. Cost governance — the REAL model spend warden measures from agents' transcripts, priced per model into dollars and rolled up per-agent/repo/day priced for the Claude backend; bring-your-own-model backends report tokens , plus a warden spend budget gate that softly warns before a spawn pushes daily/weekly spend over a configured $ cap a $ column in warden ls and a live per-agent cost card on the web Metrics tab round it out . Native scheduler — opt-in cron/at triggers that fire an agent or a pipeline on the daemon's own timer; no external crontab. warden schedule Snapshots & insights — warden snapshot checkpoints a worktree + transcript for rollback; warden insights mines agent history for patterns and parallelization wins. Branch tracking — opt-in monitor of each agent's CI status and standing vs warden branches origin/main , with non-blocking inbox/desktop alerts. Extensibility — a warden plugin system custom task types + lifecycle hooks over JSON-stdio and an interactive OpenAPI/Swagger UI at /api/docs . Web — real URL routing /cockpit , /tui , /pipelines , /metrics , /archive , /others , /agent/<id — deep-linkable, back/forward, shareable , a Cockpit home with a Fleet header, a highlighted top-bar ▢ TUI launcher that opens the literal warden tui full-screen the whole three-pane cockpit — same panes, shortcuts, real shells and live agent sessions — edge-to-edge over the viewport, Ctrl+Q to exit so you can drive the fleet from a laptop exactly as you do locally, a dedicated Metrics tab per-agent and fleet-total CPU / memory, per-agent context, fleet size, tokens saved — two columns on desktop, single column on mobile , dark-mode theming, global keyboard shortcuts, Cockpit agent grouping, and an Archive tab plus an Others catch-all last . Remote access — bearer-token auth warden token … and a Docker/compose deployment. First-run tutorial — a guided walkthrough of the core loop, with a one-line nudge until you've taken or skipped the tour. warden tutorial Go 1.26+ — to build the binary only needed for go install or building from source tmux — every agent session runs in a detached tmux window git — worktree creation and guarded cleanup Claude Code claude on PATH — the default agent runtime launched in each session Aider aider on PATH, optional — only needed to spawn agents with --backend aider ; bring-your-own-model works with local Ollama models, $0 OpenCode opencode on PATH, optional — only needed to spawn agents with --backend opencode ; bring-your-own-model works with local Ollama models, $0 . Install: npm install -g opencode-ai https://opencode.ai https://opencode.ai GitHub CLI — required for gh pr-review sessions to check out the PR branch, and for warden done --create-pr Ollama optional — only needed if you enable the local-LLM features local llm or the warden repl REPL; warden falls back to Claude when it's off or unreachable Tip:once you have the warden binary, runto check these dependencies and warden doctor to install whatever is missing Homebrew on macOS; apt/dnf/pacman on Linux; official installers for Claude Code and Ollama . warden setup warden setup --yes does it non-interactively. warden is one self-contained binary. Pick whichever fits: Grab the archive for your OS/arch from the latest release https://github.com/srjn45/warden/releases/latest , extract warden , and put it on your PATH . Released binaries have the web dashboard embedded. example: macOS arm64 adjust the version/arch curl -fsSL https://github.com/srjn45/warden/releases/latest/download/warden 8.16.3 darwin arm64.tar.gz | tar -xz sudo mv warden /usr/local/bin/ or any dir on your PATH warden --version macOS Gatekeeper:downloaded binaries are unsigned, so the first run may be blocked. Clear the quarantine flag once: xattr -d com.apple.quarantine $ which warden or right-click → Open . Building from source — option 3 — avoids this. Every release also ships native packages all with the wd alias included and the web dashboard embedded : macOS — Homebrew tap clears the Gatekeeper quarantine for you brew install --cask srjn45/tap/warden Debian / Ubuntu curl -fsSLO https://github.com/srjn45/warden/releases/latest/download/warden 8.16.3 linux amd64.deb sudo apt install ./warden 8.16.3 linux amd64.deb Fedora / RHEL sudo dnf install https://github.com/srjn45/warden/releases/latest/download/warden 8.16.3 linux amd64.rpm Arch AUR yay -S warden-bin Adjust the version/arch in the URLs; the .deb / .rpm pull in tmux and git as recommended packages. go install github.com/srjn45/warden/cmd/warden@latest This installs the warden binary CLI + daemon + MCP server + TUI . Note: go install does not bundle the web dashboard the UI is built from web/ and embedded at release time, and isn't committed to the repo . The CLI, daemon API, TUI, and MCP server all work; for the embedded web GUI use a release binary option 1 or build from source option 3 . git clone https://github.com/srjn45/warden.git cd warden make build CLI/daemon/TUI only → bin/warden make release builds the web UI first, then embeds it → full GUI warden supports shell completion for Bash, Zsh, Fish, and PowerShell. Generate the completion script for your shell and install it to the appropriate location: Bash: System-wide installation: warden completion bash | sudo tee /etc/bash completion.d/warden User-only installation: warden completion bash ~/.bash completion Zsh: System-wide installation: warden completion zsh | sudo tee /usr/local/share/zsh/site-functions/ warden User-only installation: mkdir -p ~/.zsh/completion warden completion zsh ~/.zsh/completion/ warden Then add to your ~/.zshrc: fpath= ~/.zsh/completion $fpath autoload -Uz compinit && compinit Fish: warden completion fish ~/.config/fish/completions/warden.fish PowerShell: warden completion powershell warden.ps1 Then add to your PowerShell profile After installing the completion script, restart your shell or source the file for completions to take effect. The recommended setup on macOS installs warden as an auto-starting launchd daemon and links the Claude skill + registers the MCP server . See the next section. Install with the script — it builds the release, installs the binary to ~/.local/bin/warden , renders and loads the launchd plist, links the Claude skill, and registers the MCP server: ./scripts/install.sh or: make install The daemon then starts automatically at login and restarts on crash KeepAlive = true , listening on 127.0.0.1:8765 by default. ~/.local/bin must be on your PATH to run warden from the shell — the installer warns if it isn't. The launchd daemon is the macOS TCC responsible process for the agents it spawns and for its own directory picker, so reads of protected folders Downloads, Documents, Desktop, the Music/media library surface as "warden would like to access…" prompts. Granting Full Disk Access once silences them — but macOS ties the grant to the binary's code identity, and an unsigned Go binary gets a new identity on every rebuild, which brings the prompts back. Run the one-time setup to give the binary a stable self-signed identity: ./scripts/codesign-setup.sh creates a self-signed code-signing cert once ./scripts/install.sh reinstall so the binary is signed Then grant access once: System Settings → Privacy & Security → Full Disk Access → "+" and add ~/.local/bin/warden . Because the signing identity is stable, the grant survives future rebuilds. install.sh / reinstall.sh sign automatically when the cert exists; without it they warn and leave the binary unsigned. Redeploy after a code change replaces make release && ./bin/warden daemon : ./scripts/reinstall.sh rebuild UI + binary, redeploy, restart ./scripts/reinstall.sh --no-build redeploy the existing build only or: make reinstall / make reinstall NO BUILD=1 Uninstall stops and removes the service, binary, skill link, and MCP registration; preserves your session store at ~/.warden and the logs : ./scripts/uninstall.sh or: make uninstall ./scripts/uninstall.sh --keep-binary leave ~/.local/bin/warden in place Logs: - stdout: /tmp/warden.daemon.log - stderr: /tmp/warden.daemon.err Notifications:off by default. When enabled set notify.enabled: true in the config file, or the deprecated notify: true , the daemon posts a macOS notification when an agent enters waiting for input , idle stuck , orphaned , or errored . These appear only when the daemon runs in your GUI login session a terminal, or a launchduser agent ; a headless/system daemon logs them instead. The same install script detects Linux and registers a systemd user service instead of a launchd plist. It builds the release, installs the binary to ~/.local/bin/warden , writes ~/.config/systemd/user/warden.service , enables it, and links the Claude skill and MCP server: ./scripts/install.sh or: make install The daemon starts automatically at each login session and restarts on crash Restart=always , listening on 127.0.0.1:8765 by default. ~/.local/bin must be on your PATH — the installer warns if it isn't. Persistent daemon: install.sh calls loginctl enable-linger so the systemd user service keeps running after you close your terminal or SSH session equivalent to launchd RunAtLoad on macOS . This requires systemd 219+ and is a no-op on most modern distros. Redeploy after a code change: ./scripts/reinstall.sh rebuild UI + binary, redeploy, restart ./scripts/reinstall.sh --no-build redeploy existing build only or: make reinstall / make reinstall NO BUILD=1 Uninstall stops and removes the service, binary, skill link, and MCP registration; preserves ~/.warden : ./scripts/uninstall.sh ./scripts/uninstall.sh --keep-binary leave ~/.local/bin/warden in place Logs go to the systemd journal the unit sets StandardOutput=journal / StandardError=journal , so they survive reboots even where /tmp is a tmpfs Fedora, Arch, … : journalctl --user -u warden -f follow live journalctl --user -u warden -n 100 last 100 lines Notifications:off by default. Set notify.enabled: true in the config file to enable the deprecated notify: true also works . The daemon calls notify-send libnotify when it's on PATH ; install it with apt install libnotify-bin Debian/Ubuntu or dnf install libnotify Fedora . Degrades to log-only if notify-send is not found. The repo ships a multi-stage Dockerfile /srjn45/warden/blob/main/Dockerfile and a . The image is a lean Alpine runtime static /srjn45/warden/blob/main/docker-compose.yml docker-compose.yml CGO ENABLED=0 binary plus tmux + git with the web dashboard baked in. State lives in a ~/.warden volume so it survives container restarts, and the daemon binds 0.0.0.0:8765 for remote access. Build the image run from the repo root . docker build -t warden:latest . A non-loopback bind REQUIRES a bearer token — the daemon refuses to start without one. Generate it locally or use any secret and run: export WARDEN TOKEN=$ warden token generate docker run -d --name warden \ -p 8765:8765 \ -e WARDEN TOKEN \ -v warden-data:/home/warden/.warden \ warden:latest Or with compose reads WARDEN TOKEN from your environment : export WARDEN TOKEN=$ warden token generate docker compose up -d builds the image on first run The dashboard/API is then reachable at http://<host :8765 ; the browser prompts for the token on first load. Don't expose the port directly to the public internet — front it with Tailscale or a Cloudflare Tunnel see Remote access remote-access . tmux is required.warden runs every agent inside a tmux session, so the image installs tmux and git , for worktree-isolated agents even though the container's primary job is to host the daemon, REST API, and dashboard. Spawning agents that actually call Claude additionally needs the claude CLI and its credentials inside the container — the base image deliberately omits these to stay lean; layer them on and mount ~/.claude if you want the container to drive live agents rather than just manage/observe sessions. The hook script posts lifecycle events SessionStart , Notification , Stop , SubagentStop , SessionEnd to the daemon so it can update agent status in real time without polling. SessionEnd marks the session done terminal when claude exits. Merge hooks/settings.snippet.json into ~/.claude/settings.json . The snippet uses a WARDEN HOOK placeholder — substitute the absolute path to hooks/warden-hook.sh in your clone first: from the repo root, render the snippet with the real hook path: sed "s| WARDEN HOOK |$ pwd /hooks/warden-hook.sh|g" hooks/settings.snippet.json If ~/.claude/settings.json doesn't exist yet, write it directly: sed "s| WARDEN HOOK |$ pwd /hooks/warden-hook.sh|g" hooks/settings.snippet.json ~/.claude/settings.json If it already exists, merge the rendered "hooks" key into the root of your existing settings.json object. The hook fails soft — it never blocks or errors the agent, even if the daemon is down or the session is unknown. Warden supports per-agent model selection: Short aliases: opus , sonnet , haiku , fable Full model IDs: claude-opus-4-8 , claude-sonnet-4-6 , etc. Default: claude-sonnet-4-6 or the model default config setting Explicit model warden start "Complex task" --model opus Set the default model: edit ~/.warden/config.yaml model default: opus , then restart the daemon. warden config shows what's live. View model in agent list warden ls Shows MODEL column Warden drives Claude Code by default, but the agent layer is pluggable: pick the backend per agent at spawn time with --backend CLI or the backend param spawn agent MCP tool . Supported agents — status:warden is fully tested only withClaude Code.Codex CLIandAntigravity CLIareβ beta— live-verified state, approval, and transcript fidelity, still maturing. The remaining non- claude backends Aider, OpenCode, Crush, Goose, Cursor areexperimental / work-in-progress— functionality may be reduced or unverified. | Agent | Status | |---|---| | Claude Code | ✅ Stable — fully tested, reference backend | | Aider | 🧪 Experimental WIP | | OpenCode | 🧪 Experimental WIP | | Codex CLI | β Beta | | Crush | 🧪 Experimental WIP | | Goose | 🧪 Experimental WIP | | Cursor CLI | 🧪 Experimental WIP | | Antigravity CLI | β Beta | | Backend | --backend | Tier | Notes | |---|---|---|---| Claude Code default | claude | A | Full fidelity — digests, savings, priced spend, resume, all permission modes | Aider | aider | A | 🧪 Experimental. Bring-your-own-model pass --model , e.g. ollama chat/qwen2.5-coder:3b ; structured markdown transcript ⇒ real digests; no resume, no priced spend tokens only , runs an autonomous --message task that exits when done | OpenCode | opencode | A | 🧪 Experimental. Bring-your-own-model pass --model , e.g. ollama/qwen2.5-coder:3b ; structured JSON transcript via opencode export ⇒ real digests; resumes the worktree's last session opencode -c ; spend tokens-only BYO model | Codex CLI | codex | A | β Beta. BYO provider via Codex config / -m ; structured JSONL transcript rollout files ⇒ real digests; resumes dir-scoped codex resume --last , upgraded to exact-id via discover-then-pin; live state + approval detection; context injection via AGENTS.md ; spend tokens-only. See docs/agent-backends/codex.md | Crush | crush | A | 🧪 Experimental. BYO model config-driven TUI; headless crush run accepts -m ; structured JSON transcript via crush session show --json ⇒ real digests; resumes dir-scoped --continue ; initial prompt auto-typed into the TUI after launch via PromptSeeder ; context injection via CRUSH.md ; spend tokens-only. See docs/agent-backends/crush.md | Goose | goose | A | 🧪 Experimental. BYO provider GOOSE PROVIDER / GOOSE MODEL env ; structured JSON transcript via goose session export ⇒ real digests; resumes name-deterministic goose session -r --name <id ; no model flag on session launch; context injection via .goosehints ; spend tokens-only. See docs/agent-backends/goose.md | Cursor CLI | cursor | C | 🧪 Experimental. Hosted plan cursor-agent , billed to your Cursor subscription ; rich native permission modes plan / ask / auto-review / force ; resumes dir-scoped --continue ; live state + approval/trust detection; context injection via AGENTS.md . No structured transcript yet interactive store is unreadable SQLite ⇒ no digests; spend tokens-only. See docs/agent-backends/cursor.md | Antigravity CLI | antigravity | A | β Beta. Google-hosted free tier agy , multi-vendor model menu ; structured trajectory JSONL incl. tool calls / files changed ⇒ real digests; resumes dir-scoped agy -c ; live state + approval/trust detection; context injection via AGENTS.md ; spend tokens-only. See docs/agent-backends/antigravity.md | Drive Aider against a local Ollama model free, offline export OLLAMA API BASE=http://127.0.0.1:11434 warden start "implement the add function" --backend aider --model ollama chat/qwen2.5-coder:3b --dir . Drive OpenCode against a local Ollama model free, offline warden start "implement the add function" --backend opencode --model ollama/qwen2.5-coder:3b --dir . Drive Codex against a local Ollama model configure provider in ~/.codex/config.toml first warden start "implement the add function" --backend codex --dir . Drive Crush against a local Ollama model configure provider in ~/.config/crush/crush.json first warden start "implement the add function" --backend crush --dir . Drive Goose against a local Ollama model GOOSE PROVIDER=ollama GOOSE MODEL=qwen2.5-coder:3b \ warden start "implement the add function" --backend goose --dir . Backends differ in capabilities; warden degrades gracefully rather than crashing when one lacks a capability e.g. spend shows tokens-not-dollars for a bring-your-own-model backend; rotate/handoff re-spawn fresh when resume is unavailable . It also surfaces some backends' native superpowers as first-class verbs — warden review Codex's diff reviewer , warden models Antigravity/Cursor's live model menu , and warden fork branch a Codex session into a new managed agent — see warden fork warden-fork ; see Agent-native superpowers agent-native-superpowers--warden-review--warden-models . See the design docs/superpowers/specs/2026-06-27-pluggable-agent-backends-design.md , §5 and roadmap item 52.Warden reads all settings from a single YAML file default ~/.warden/config.yaml . Run warden config init to generate a fully-commented file, edit the values, then restart the daemon; warden config prints what's currently live. The --config <path flag points any command at an alternate file, and --addr <host:port overrides the daemon address for a single command. | Setting | Default | Description | |---|---|---| addr | 127.0.0.1:8765 | Daemon listen address. Non-loopback requires WARDEN TOKEN bearer-token auth — see | data dir | ~/.warden | Directory for warden state: the embedded ScrivaDB session store sessions-db/ , with a one-time-imported read-only JSON backup in sessions/ + closed/ , per-agent prompt files prompts/ , inbox, pipelines, and metrics | claude projects dir | ~/.claude/projects | Root of Claude Code transcript directories; the poller reads agent transcripts here to generate subjects and the context gauge | model default | claude-sonnet-4-6 | Default model for new agents a model id or alias: sonnet / opus / haiku / fable | default permission mode | auto | Default permission mode for new agents auto / default / acceptEdits / bypassPermissions / dontAsk / plan | notify.enabled | false | Desktop notifications when an agent needs attention | approvals | true | The approvals inbox: the daemon parses recognized Claude Code tool-permission prompts and surfaces them for answering. The web AttentionQueue shows one-click option buttons, the CLI exposes warden approvals / warden approve , and the TUI shows a pinned ⏳ Approvals row — answer it in place i , or enter on the row, then 1 - 9 ; tab cycles between waiting agents or from the web / warden approve . Unrecognized prompts always fall back to attach | tokens.guard | true | The context-size guard: the poller reads each live agent's context-window fill from its transcript, classifies it ok / warning / critical , and shows a state-colored token figure in warden ls , the TUI row, and the web tile. Master switch for the whole guard gauge, alert, auto-compact | tokens.warn alert | true | Fire a desktop notification when notify.enabled is on once per upward crossing into the warning or critical band | tokens.auto compact | true | When an agent is critical and idle/waiting, auto-send /compact to reclaim its context cooldown-guarded | tokens.force compact | false | When an agent goes critical while still working, interrupt it Escape , /compact once it idles, then send the resume prompt. Destructive — discards the in-flight turn — so off by default. Per-agent override via warden force-compact <id on|off|inherit | tokens.compact resume prompt | built-in | Message sent to a force-compacted agent once compaction lands so it resumes its work | tokens.warn | 200000 | Warning threshold in context tokens inclusive lower bound . If tokens.critical is not greater than this, both reset to the defaults | tokens.critical | 400000 | Critical threshold in context tokens inclusive lower bound — the auto- /compact trigger band | auto approve | false | Auto-answer recognized permission prompts. Bare on/off, or an allow/deny rule policy by tool / glob / regex / paths, with per-agent overrides — see warden auto-approve | notify.webhook enabled / notify.webhook url | false / empty | POST a JSON payload to webhook url on attention + context-size alerts a Slack incoming-webhook URL works out of the box ; runs alongside notify.enabled | collab.enabled / collab.interval / collab.hint | true / … / true | File-conflict detection across worktrees, scan interval, and the spawn-time coordination hint | rails.isolation guard / rails.git redirect / rails.check redirect / rails.git conventions | true | Boundary-enforcement hooks see | log.level / log.format info / text debug / info / warn / error and format text / json ; warden daemon --log-level / --log-format override local llm.enabled + .url / .model / .timeout false warden repl its / commands work without it local llm.repl false warden repl mode instead of a plain shell warden config lists every setting, including worktree.spawn gate / worktree.spawn gate max agents , tokens.budget gate / tokens.budget daily usd / tokens.budget weekly usd , metrics , allow nonloopback , pipeline.keep done / pipeline.hint , worktree.keep done / worktree.auto prune , the auto restart. and rate limit. knobs, and the REPL tier knobs local llm.tier / local llm.escalate / local llm.classifier . Related settings are grouped into namespaced blocks pipeline. , auto restart. , collab. , memory. , branch track. , rate limit. , http. , log. , plugins. , alongside the existing rails. / tokens. / notify. / worktree. / local llm. . The old flat keys collab enabled , log level , memory inject , … still load asdeprecated aliases— they work but emit a one-time deprecation warning; warden config rewrites them into the nested form. Config namespacing:Settings are grouped into five YAML blocks — rails , tokens , notify , worktree , local llm . Old flat keys e.g. token guard , local llm url , notify are still accepted as deprecated aliases and migrate to the namespaced form automatically when warden config init is re-run. Legacy env vars:the old WARDEN environment variables e.g. WARDEN ADDR , WARDEN NOTIFY , WARDEN TOKEN are no longer read — the daemon warns once at startup if any are still set. The per-agent IPC vars warden injects into each agent WARDEN SESSION ID , WARDEN PIPELINE ID , WARDEN JOB ID are not configuration and are unaffected. The simplest way to create an agent is to give it a plain prompt and let the system figure out the rest: warden start "review the auth module for security issues" spawned agent-a1b2 classifying… — attach with warden attach agent-a1b2 In the web GUI, + New agent opens a single prompt textarea — no type or repo fields. How it works: Runs in the caller's directory. Prompt-spawned agents run claude --dangerously-skip-permissions '<prompt ' or --permission-mode acceptEdits with --supervised in the directory you invoked start from or the --dir you pass — no per-agent directory is created. Point it elsewhere with --dir , and include any extra repo context in the prompt itself. Type is auto-assigned. Shortly after creation the daemon classifies the prompt with claude -p and updates the type label. It appears as "classifying…" until then. Requires claude on the daemon's PATH ; falls back to other if unavailable. Subject is auto-generated. Each agent has a one-line subject summarizing what it is currently working on. It is seeded from the first words of the prompt at spawn, then refreshed periodically by the poller: the poller reads the agent's Claude Code transcript looked up under the claude projects dir config setting or, if no transcript is found, captures the tmux pane, then asks claude -p for an ≤8-word phrase. Refreshes are throttled and only run when the pane content has changed. Managed worktrees still available. warden start TICKET --type development --repo … is unchanged — see the section below. To launch an agent in a directory other than your current one, pass --dir : warden start "summarize recent changes" --dir /path/to/repo When you need a managed git worktree e.g. a development branch tied to a Jira ticket , pass --type . The type controls whether a git worktree is created and determines how the session is set up. | Type | Worktree | Notes | |---|---|---| development | yes new branch | Creates .worktrees/<ticket on a new branch named after the ticket | pr-review | yes PR branch | Detached worktree; runs gh pr checkout <PR inside it. Requires --pr or --branch . Exempt from the write-type isolation default | analysis | opt-in --worktree | Runs in the repo by default; pass --worktree to get a scratch branch | spike | opt-in --worktree | Same as analysis | code | yes new branch | Isolated in .worktrees/<id ; pass --in-repo to share the repo | docs | yes new branch | Isolated in .worktrees/<id ; pass --in-repo to share the repo | website | yes new branch | Isolated in .worktrees/<id ; pass --in-repo to share the repo | debug-ci | yes new branch | Isolated in .worktrees/<id ; pass --in-repo to share the repo | tests | yes new branch | Isolated in .worktrees/<id ; pass --in-repo to share the repo | other | no | Catch-all; also used for unrecognized type strings | Every write-type agent code / docs / website / debug-ci / tests gets its own isolated worktree by default so parallel agents don't collide on the shared tree; pass --in-repo to opt back into the repo root. pr-review is exempt it already checks out the PR branch . This isolation is what makes the boundary-enforcement hooks see Lifecycle commands & boundary enforcement lifecycle-commands--boundary-enforcement meaningful. By default every agent runs claude --dangerously-skip-permissions — permission prompts are suppressed and the agent runs fully autonomously; the Notification hook still records them as events in the session doc. Pass --supervised to opt into a lighter permission mode --permission-mode acceptEdits : file edits and common filesystem commands auto-approve, but other tools bash writes, network calls, etc. surface the numbered permission prompt — which the approvals inbox captures and lets you answer from the web AttentionQueue one-click buttons , the TUI ⏳ Approvals row → i / 1 - 9 , or the CLI warden approve when approvals is on. A restored agent keeps its supervised setting. If a worktree for the ticket already exists on disk, the spawn adopts it reattaches claude to the existing branch instead of erroring. warden tui open the cockpit warden bare invocation — same thing warden tui or bare warden opens a tmux-composited cockpit — a dedicated tmux session with three panes: an agents list top-left , a terminal shell for running CLI commands bottom-left , and a full-height live detail pane right that opens the selected agent's interactive claude session. Browse the list freely with ↑ / ↓ without disturbing the detail pane; press Enter to open an agent in it. Agents spawned by another agent via the spawn agent MCP tool nest under their parent as a collapsible sub-tree ▸ / ▾ , indented per depth — the same affordance pipelines use , so you can see which agents an orchestrator fanned out. Deleting a parent that still has live children keeps it as a muted terminated tombstone header terminated · N running — no terminal/attach pane — so its children never vanish; the daemon reaps the tombstone once the whole sub-tree finishes. The cockpit requires tmux ≥ 3.1 it composites real tmux panes ; if tmux isn't installed it exits with an error. Launched from inside an existing tmux session , warden detects $TMUX and lays the cockpit out as a native tmux window in your current session instead of nesting your own keybindings, copy-mode, and resizing apply; q closes just the cockpit window . Force the native window with warden tui --tmux-native , or the classic own-session cockpit with env -u TMUX warden tui — see docs/USAGE.md §7 /srjn45/warden/blob/main/docs/USAGE.md . The list pane polls the daemon about once a second. The daemon must be running warden daemon before opening the TUI. Keys cockpit | Key | Action | |---|---| ↑ / ↓ or j / k | Move selection detail pane is unaffected | ← / → or h / l | Collapse / expand the pipeline or agent sub-tree under the cursor | Enter | Open the selected agent or running pipeline job in the right detail pane — a finished agent or tombstone shows its stored detail instead of attaching | n | New agent — opens a prompt textarea; ctrl+s to submit, esc to cancel | o | Open a directory as a group becomes the spawn target for n | s | Send a message to the selected agent — enter to send, esc to cancel | a | Attach — full-screen the agent's or running job's tmux session; press to return to the dashboard Ctrl-b Enter | d | Completion digest for the selected agent — scrollable overlay; d / esc to close | i | Answer pending approvals also enter on the ⏳ Approvals row — 1 - 9 to answer, tab for next | c | Shared-context + message-traffic inspector | r | Retry a failed / needs-attention pipeline job | x | Context-sensitive: terminate the selected agent / cancel a pipeline / close an opened dir confirm with y | D | Delete a stopped pipeline's record confirm with y | ? | Toggle help overlay | Alt+t | Toggle the bottom-left master pane between Claude and a shell both stay alive | q | Quit and tear down the cockpit | Move focus between panes with Alt+←/→/↑/↓ no tmux prefix ; toggle the bottom-left master pane between Claude and a shell with Alt+t . See docs/USAGE.md §7 /srjn45/warden/blob/main/docs/USAGE.md for the full cockpit guide and caveats around nested tmux. Open the live terminal cockpit. Also launched by bare warden with no subcommand. warden tui warden equivalent See the Terminal UI terminal-ui section above for the full key reference. Spawn a new agent session. Two modes: Prompt mode no --type — pass a quoted prompt; the type is assigned automatically: warden start "review the auth module for security issues" warden start "investigate why the nightly build is flaky" Managed worktree mode --type required — creates a git worktree for the ticket: Development agent for a Jira ticket: warden start PROJ-350 --type development PR review — checks out the PR branch in a fresh worktree: warden start --type pr-review --pr 1234 Debug CI — no worktree, runs in current directory: warden start --type debug-ci Spike with an optional scratch worktree: warden start --type spike --worktree Point at a specific repo and branch: warden start PROJ-350 --type development --repo /path/to/repo --branch my-branch Permission mode examples: Use acceptEdits mode for careful prompting on risky operations: warden start "refactor the auth module" --permission-mode acceptEdits Set a global default for all new agents: put default permission mode: acceptEdits in ~/.warden/config.yaml, then restart the daemon. warden start "debug the API rate limit" uses acceptEdits mode Override the global default for a specific agent: warden start "quick spike" --permission-mode auto bypass global setting Change permission mode for a running agent: warden set-permission-mode agent-abc123 dontAsk Flags: --type — task type; omit to use prompt mode auto-typed --repo — repo path default: current directory; managed worktree mode only --branch — new branch name development or checkout target pr-review --pr — PR number or URL pr-review only --dir <path — directory to run a prompt-spawned agent in default: current directory --worktree — opt-in worktree for analysis/spike --in-repo — write-type opt-out: run in the shared repo instead of an isolated worktree ignored for pr-review --model <model — per-agent model id or alias opus / sonnet / haiku / fable ; defaults to the model default config setting --role <role — built-in agent role: general default, no persona · orchestrator · implementer · auto-merger · reviewer . Injects the role's persona as a system-prompt addendum and fills its default spawn flags --type / --model / --permission-mode /auto-approve/tags for any you leave unset explicit flags still win . See warden role list --tags <a,b — attach tags lowercased, deduped ; searchable and filterable with warden ls --tag --preset <name — seed spawn defaults from a saved preset warden preset save ; explicit flags still override --prompt-template <name --set VAR=value — fill a saved prompt template warden prompt-template save into the spawn prompt; repeat --set per variable. A positional prompt still wins; free-form only no --type --auto-restart — opt this agent into daemon auto-restart on error tuned by auto restart config --permission-mode <mode — control Claude's permission level valid modes: acceptEdits , auto , bypassPermissions , default , dontAsk , plan ; defaults to the default permission mode config setting default: auto --supervised — legacy alias for --permission-mode acceptEdits ; risky tools prompt and the approvals inbox surfaces them see the approvals setting List all active agent sessions with their type, status, working directory, and subject. warden ls ID TYPE STATUS AGE DIR SUBJECT PROJ-350 development working 2m PROJ-350 refactoring auth middleware prreview-a1b2 pr-review idle 5m prreview-a1b2 reviewing PR 1234 agent-c3d4 … working 1m agent-c3d4 investigate flaky nightly build DIR shows the base name of the agent's working directory. SUBJECT is the auto-generated one-line summary of what the agent is currently doing empty until the first poller refresh . Use --json for machine-readable output a JSON array of full session objects; an empty fleet prints . Useful for scripts and for Claude driving the CLI: warden ls --json Other flags: --watch / -w — live-update the table on every agent state change over the daemon's SSE stream Ctrl+C to exit ; combine with --json to stream one JSON snapshot per change. --tag <tag — filter to agents carrying every given tag AND semantics; repeatable or comma-separated . Tags are set at spawn with warden start --tags backend,urgent and are part of the search haystack. Show full detail for one session: working directory, subject, worktree, branch, PR, all events. warden status PROJ-350 Add --json to emit the full session as a single JSON object including the events array : warden status PROJ-350 --json Register an existing Claude session into warden. Plain shell — finds the newest Claude conversation for the directory and resumes it under a new tmux session claude --resume . Inside tmux — registers the current tmux session live without relaunching claude. warden adopt newest session for cwd, resume under tmux warden adopt --session-id <uuid pick a specific Claude conversation warden adopt --dir /path/to/project target a different directory Attach your terminal to the agent's tmux session interactively. warden attach PROJ-350 The single umbrella teardown verb. By default warden stop <TICKET does a full teardown : terminate the tmux + claude session, clear archive the record, and remove the git worktree + branch asking for confirmation first, unless --yes . Subtractive flags keep parts around; --pr opens a GitHub PR first while the agent is still intact. Safe order is always PR → terminate → clear record → remove worktree, so a failed push leaves the agent running. warden stop PROJ-350 full teardown asks before removing the worktree warden stop PROJ-350 --yes ...without the confirmation prompt warden stop PROJ-350 --keep-worktree terminate + clear record, keep the worktree == done warden stop PROJ-350 --keep-record terminate + remove worktree, keep the record warden stop PROJ-350 --hard purge the record instead of archiving warden stop PROJ-350 --pr --base main open a GitHub PR first, then tear down The four older verbs are kept as thin aliases — each is just stop with a fixed flag combo: | old verb | equivalent | |---|---| wd terminate <T | wd stop <T --keep-record --keep-worktree | wd delete <T --hard | wd stop <T --keep-worktree record only | wd remove-worktree <T | wd stop <T --keep-record worktree only | wd done <T --hard|--create-pr | wd stop <T --keep-worktree --hard|--pr | wd stop <T | terminate + clear record + remove worktree | Terminate the agent kill its tmux + claude session and clear its stored record in one step. It does not remove the git worktree — that is a separate, explicitly-confirmed step remove-worktree . Equivalent to terminate followed by delete , i.e. stop --keep-worktree . warden done PROJ-350 terminate + clear record worktree kept warden done PROJ-350 --hard purge the record instead of archiving it warden done PROJ-350 --create-pr --base main push the branch + open a GitHub PR first --create-pr pushes the agent's branch and opens a GitHub PR via gh — titled from the agent, bodied from its digest, targeting --base default main — before terminating, so a failure leaves the agent running to retry; an existing PR for the branch is reported, not re-created. Stop an agent: kill its tmux + claude session, but keep the record and worktree. This is the safe "stop this agent" default — it is reversible with warden restore . Alias for stop --keep-record --keep-worktree . warden terminate PROJ-350 Recreate and resume a lost/orphaned agent's tmux + claude session claude --resume . Use only when the agent's tmux session is gone status orphaned . warden restore PROJ-350 The safety net for the tombstone reaper which auto-archives a parent record once its whole sub-tree goes terminal : a stale orphaned status racing a daemon restart could previously let a genuinely-live session's record get archived out from under it. Bare warden recover scans archived records and only reports the ones whose tmux session is confirmed still alive; --apply re-inserts each candidate into the active store under its original id — any children linked via parent id , untouched by archiving reconnect automatically. warden recover report candidates only dry run warden recover --apply actually revive them warden recover --json scripting Clear an agent's stored record archives by default; --hard purges . Does not touch tmux or the worktree. Alias for stop --keep-worktree record only . warden delete PROJ-350 warden delete PROJ-350 --hard Remove an agent's git worktree and branch. Destructive. It refuses if the agent is still running terminate it first or if the worktree has uncommitted changes or unpushed commits — use --force to override the guard. Alias for stop --keep-record worktree only ; always asks unless --yes . warden remove-worktree PROJ-350 warden remove-worktree PROJ-350 --force Type a message into the agent's claude session and press Enter. warden send PROJ-350 "run the unit tests and fix any failures" Print the recent terminal output of the agent's claude session. warden tail PROJ-350 warden tail PROJ-350 --lines 80 Summarize what an agent accomplished — files touched, branch, number of turns, and a short narrative best-effort, via claude -p . Also available as a web Digest panel and, in the cockpit, the d key opens a scrollable digest for the selected agent . warden digest PROJ-350 warden digest PROJ-350 --json The approvals inbox on by default; the approvals setting . When a --supervised agent hits a tool-permission prompt, the daemon recognizes it and surfaces the numbered options so you can answer without attaching. warden approvals list pending permission prompts with their options warden approve PROJ-350 1 answer prompt for that agent with option 1 e.g. "Yes" Unrecognized prompts always fall back to attach. Also surfaced in the web AttentionQueue one-click buttons and the TUI ⏳ Approvals row. Preflight checks — required binaries tmux , git , claude , optional ones gh , ollama , warn-only , daemon reachability, and the data directory. It also prints a one-line hardware-aware local llm model recommendation for the REPL. warden doctor Verifies the install with the same checks as doctor , then installs whatever is missing — idempotent, so it only touches deps that aren't already on PATH. It prints the exact install command for each missing dependency and prompts before running it; --yes installs everything without prompting for automation . Required deps tmux , git , claude come first, then optional ones gh , ollama . Package managers are auto-detected — Homebrew on macOS never auto-bootstrapped and apt / dnf / pacman on Linux — and Claude Code and Ollama use their official installers. After installing, it re-runs the checks and prints a doctor-style report. setup is CLI-only it installs host packages and is not exposed over MCP. warden setup confirm-each install of anything missing warden setup --yes non-interactive: install all missing deps Recommends local models for the REPL warden repl , sized to this machine. It auto-detects two figures from the same memory pool — total memory the bound and average free memory sampled to smooth spikes — using NVIDIA VRAM nvidia-smi , Apple unified memory, or Linux MemAvailable . It scores a curated, tool-calling-forward catalog Qwen3, gpt-oss, Mistral Small, Qwen2.5 by conductor suitability — not raw size or coding skill, since the REPL routes tool calls and never writes code. Scores are calibrated against the Berkeley Function-Calling Leaderboard https://gorilla.cs.berkeley.edu/leaderboard.html BFCL v4 , weighted toward the multi-turn subcategory that matches the REPL's tool-call loop. Each model is marked fits now / free memory first / too large . The ★ pick is the best-scoring model that runs comfortably now with headroom for your real workload Docker, DBs, IDE, Claude sessions, the daemon . It only ever recommends — you set local llm model yourself. warden llm suggest auto-detect and rank warden llm suggest --samples 8 average more free-memory samples warden llm suggest --total-gb 48 --free-gb 30 what-if for another machine warden llm suggest --json A guided tour of the core loop spawn → watch → commit → tear down . Until you've taken or skipped it, warden prints a single non-blocking stderr hint nudging you toward it suppressed for piped/non-interactive use . warden tutorial run the walkthrough, then mark it complete warden tutorial --skip mark complete without running it warden tutorial --reset clear the marker so the tour and hint run again Disable the hint entirely with tutorial: false in the config. Run inside an agent session to retire a long-lived, context-heavy agent and hand off to a fresh successor in the same workdir/worktree. Phase 1 is driven by the /warden skill the agent writes a handoff file + resume prompt and shows you ; on your go-ahead it spawns the successor and reaps itself. warden handoff --retire --confirm \ --resume-file "${TMPDIR:-/tmp}/warden-rotate-handoff-$WARDEN SESSION ID.md" \ --resume-prompt "Continue the migration from where the notes leave off" warden rotate --confirm … is an exact alias. The handoff file lives at a unique, per-agent temp path so concurrent rotations never clobber each other; the successor deletes it once read and /tmp self-clears . Spawn-before-reap is fail-safe: if the successor fails to spawn, the current agent keeps running. Rotation reuses the worktree by cwd and never removes it. --retire is mutually exclusive with --to . Define a DAG of agent jobs in YAML and let the daemon run them: jobs with no dependencies start first, and each job's emit publishes its output and unblocks its dependents. The daemon owns the cheap "await + fire" so the lead Claude stays off the critical path. warden pipeline validate -f review.yaml check the spec DAG/refs/cycles ; exit 0/1, no daemon warden pipeline create -f review.yaml validate + register does not start warden pipeline list-templates list the built-in starter templates + their placeholders warden pipeline create --template analyze-implement-review --set REPO=. render from a template warden pipeline start <id spawn jobs with no dependencies warden pipeline show <id jobs, status, branches, and emitted output warden pipeline list warden pipeline edit-job <id <job ... edit a not-yet-started job's fields warden pipeline retry <id <job re-run a failed/needs-attention job warden pipeline pause <id stop spawning new jobs in-flight keep running warden pipeline resume <id resume a paused pipeline warden pipeline cancel <id terminate running jobs warden pipeline delete <id remove the record cancel first if live Four go:embed -bundled templates ship in the binary — analyze-implement-review , parallel-tasks , test-fix-verify , research-synthesis . Render one with warden pipeline create --template <name , substituting placeholders via {{NAME}} / {{REPO}} auto-filled and --set KEY=VALUE . A minimal analyze → implement → review spec job prompts must not mention emit — the daemon auto-appends it and auto-injects upstream outputs : name: auth-refactor jobs: - id: analyze prompt: "Analyze the auth module and list the concrete refactors needed." - id: implement depends on: analyze worktree: fresh prompt: "Implement the refactors identified upstream." - id: review depends on: implement prompt: "Review the implementation branch for correctness and regressions." Jobs can be made conditional with run if: success default | failure | always — e.g. a run if: failure rollback/notify step that only runs when an upstream job fails. Pipelines have full TUI and web visibility a ▸ Pipelines section / a Pipelines tab . See docs/USAGE.md /srjn45/warden/blob/main/docs/USAGE.md for the full authoring guide. Fire an agent spawn or a pipeline on the daemon's own timer — no external crontab. Opt-in: set scheduler enabled: true in the config and keep the daemon running schedules only fire while it is up . Recurring agent spawn 5-field cron; @daily etc. supported : warden schedule create daily-review --cron "0 9 " \ --type pr-review --repo . --prompt "Review yesterday's merged PRs" Single-shot spawn RFC3339 or 2006-01-02T15:04, local time : warden schedule create launch --at 2026-06-27T09:00 --prompt "Kick off the release checklist" Fire a pipeline on a schedule each run gets a timestamped name : warden schedule create nightly --cron "0 2 " --pipeline ci.yaml warden schedule list kind, mode, spec, enabled, next run, last error warden schedule delete daily-review Missed runs are not backfilled — on daemon startup each next-fire is recomputed from the wall clock. The reconcile loop fails soft a bad fire is recorded in last error , never crashes the loop . list schedules exposes the same read-only view over MCP. The substrate pipelines are built on, usable directly so agents can collaborate: Shared context: a namespaced key/value blackboard all agents can read/write warden ctx set build.status "green" --as agent-4f2a warden ctx get build.status warden ctx list --prefix build. Directed messages: per-agent inbox; sending wakes a parked idle/waiting agent warden msg send agent-9c1d "the API contract changed — re-check your client" warden msg inbox --as agent-9c1d warden msg wait --as agent-9c1d --timeout 120 block in the daemon until a message arrives The daemon watches each active agent's worktree fsnotify, with a git diff poll as a safety net and warns — via the inbox, deduplicated — when two agents edit the same file. Spawned agents also get a system-prompt hint to check before editing shared files, so they coordinate rather than overwrite. warden collab conflicts current cross-agent file conflicts warden collab who-is-editing <file which agents if any are touching a file Tunable via the collab.enabled / collab.interval / collab.hint config settings; also exposed as the get collaboration status / who is editing file MCP tools and a File conflicts card on the dashboard. First-class, deterministic commands that move git and test/lint/build work off the agent and return compact results instead of raw tool-spam. PreToolUse hooks config-gated, fail-open steer agents toward these and deny-redirect the raw escapes — see Lifecycle commands & boundary enforcement lifecycle-commands--boundary-enforcement . warden commit stage + commit the agent's worktree message auto-filled if omitted warden commit -m "fix: …" warden push push the worktree's branch warden push --force-with-lease safe force after a rebase/amend warden sync rebase-sync against the upstream refuses on a dirty tree warden check name run the project's .warden/check.yml checks; reports only failures Rails: no commit/push on main / master , no dirty-tree sync, pre-commit-hook failures surfaced as a result. Force pushes are always --force-with-lease never a bare --force , so a rebased branch can't clobber a teammate's push. All four are also MCP tools. Some backends ship native capabilities Claude Code doesn't, and warden surfaces them as first-class verbs added on top — never a restriction . Like warden check , these exec in the agent's worktree with no daemon round-trip , so they are CLI-only by design no MCP twin . warden review the backend reviews its OWN uncommitted diff and streams findings warden review --base main review the branch's changes against a base instead warden review --prompt "focus on error handling" warden review --json neutral machine-readable findings: {summary, verdict, findings } warden models the backend's LIVE model menu one id per line; --json for an array — the agent-native counterpart to warden review warden check configured test/lint and a pr-review agent a whole reviewer session : it runs the backend's own one-shot reviewer against the worktree. Codex implements it codex review ; backends without a native reviewer e.g. Claude exit non-zero pointing you at warden check / pr-review . --json runs the structured form codex exec review and normalizes the backend's native output into one neutral findings shape; review quality rides the backend's configured model.— the live runtime model menu vs warden's static warden models opus / sonnet / haiku / fable aliases . Antigravity agy models and Cursor cursor-agent --list-models implement it; the ids feed --model verbatim. Listing is a metadata read, so it spends no quota. Backends with a static model set Claude degrade non-zero "pass --model with a known id" . Both take --backend <id to target a specific backend default: the current agent's . See Agent backends agent-backends---backend . warden owns one committed, backend-neutral project memory — .warden/memory.md beside .warden/check.yml , keyed implicitly by the repo root and holding durable cross-agent facts "where X lives", "run Y via warden check ", project invariants . The point: the next agent — any backend — doesn't re-pay the rediscovery tax the last one already paid. warden memory show the resolved path + the rendered view injected into agents warden memory --raw print the file verbatim warden memory --edit open it in $EDITOR auto-creates it first warden memory --path just the resolved path scriptable; no auto-create At every spawn warden projects the budgeted, navigational render into the agent's system prompt through the same seam the collab/pipeline/git hints ride: Claude via --append-system-prompt file-backed, so it never bloats the launch line , codex / cursor / opencode / antigravity via their AGENTS.md warden block, crush via CRUSH.md , goose via .goosehints ; aider degrade-skips. 7 of 8 backends project with zero new adapter code. It is config-gated by memory.inject default on — off, or an empty/absent file, makes the launch byte-identical to no injection. warden reads but never rewrites your CLAUDE.md/AGENTS.md/CONVENTIONS.md; .warden/memory.md is warden's own. warden memory is CLI-local like warden check / warden review no daemon round-trip, no MCP twin . Auto-curation memory.curate, default OFF . warden can also propose memory for you: on the existing completion-digest hook, a debounced extraction pass reads finished agents' digests + the current memory and writes durable, reusable facts back as - unverified · <date · <provenance <fact . It is deliberately never authoritative — proposals land in the working tree only warden never commits and never pushes them, so the committed diff is the human review gate , promote to trusted only when corroborated by a second agent or a human, supersede older contradicting facts struck with a tombstone , age out past a TTL, and get flagged stale when a named path vanishes. It prefers the $0 local model and never sits on a paid critical path. This is the core defence against memory poisoning : one agent's wrong belief can never silently mislead the fleet. Local grounding memory.ground, default ON . In warden repl you can also ask this memory a question — /memory <q /mem / /ask , or the model-callable project memory tool — and warden answers "where does X live?" / "how do I run Y?" locally from .warden/memory.md . This is the token- removing lever of the feature: unlike projection which adds input tokens per turn , grounding removes a cloud round-trip by serving the answer from the local model. It is read-only never creates or writes memory , cites each entry's trust unverified / trusted / human + provenance so a stale hint reads as a hint, stays on the local tier only structurally $0 — it can never escalate to a paid model , and with no local model configured degrades to returning the matching entries verbatim. An absent/empty file answers "not in project memory". warden search auth backend AND every term across active sessions; --closed folds in the archive warden history --since 7d --type development --limit 20 browse the archived closed store search matches case-insensitively over id/name/ticket/type/subject/prompt/branch/tags/last-pane; --json on either prints raw records. The web dashboard carries a live search box and a 🗄 Archive tab mirrors history . Serialize session metadata not worktrees/branches/tmux to JSON for backup or moving between machines. warden export fleet.json active records; --all also dumps the archive warden import < fleet.json idempotent by id; --merge overwrites colliding records An append-only trail of the daemon's meaningful actions spawn , terminate , delete , approve , pipeline start / pipeline cancel written to ~/.warden/audit.jsonl 0600 . Read directly from the file, so it works even while the daemon is down. warden audit log newest last default tail 50 warden audit log --action spawn --since 24h --json warden audit log --target PROJ-350 --tail 0 0 = all Save reusable spawn defaults under a name and replay them with warden start --preset <name . warden preset save fast --model haiku --permission-mode acceptEdits --auto-restart warden preset list warden start "quick fix" --preset fast explicit flags still override the preset --type / --model / --permission-mode / --auto-restart / --worktree / --in-repo are persisted to ~/.warden/presets.yaml ; per-invocation inputs ticket, branch, PR, dir are not. Where a preset stores reusable flags , a prompt template stores a reusable prompt body with {{VAR}} placeholders. Save one, then fill it in at spawn time alias pt . warden prompt-template save bugfix --prompt "Fix the bug in {{FILE}} described by {{TICKET}}" warden prompt-template list each template + its variables warden start --prompt-template bugfix --set FILE=server.go --set TICKET=WARD-42 Variables are auto-derived from the body and persisted to ~/.warden/prompt-templates.yaml . Every declared variable must be supplied a typo'd --set is rejected , and an explicit positional prompt still wins. --prompt-template is free-form only no --type . One umbrella over all three kinds of reusable launch config — saved spawn presets , saved prompt templates , and the built-in pipeline templates . warden library list presets + prompt templates + pipeline templates, labeled sections alias: wd lib list warden library save-preset fast --model haiku delegates to warden preset save warden library save-prompt bugfix --prompt "Fix {{FILE}}" delegates to warden prompt-template save Purely additive: it reuses the existing preset store, the prompt-template store, and the embedded template catalog, so warden preset , warden prompt-template , and warden pipeline list-templates keep working unchanged. Pipeline templates are embedded/read-only no save-template ; author one with warden pipeline create -f <spec.yaml . Also exposed over MCP as library list returns {presets, prompt templates, templates} . CLI view of the resource metrics per-agent process-tree RSS/CPU, system memory/pressure, daemon self-stats . warden stats live snapshot warden stats --history per-agent performance history + anomaly warnings warden stats --history --agent PROJ-350 One umbrella over warden's two financial views: spend the real dollars agents billed to the model provider and savings the tokens — and the dollars they represent — warden kept out of context . warden cost with no subcommand prints a combined at-a-glance summary of both. warden cost combined: SPEND section + SAVINGS section warden cost spend same as warden spend all flags wired through warden cost savings --benchmark same as warden savings --benchmark Purely additive: it reuses the existing spend rollup and savings ledger and their render logic, so the top-level warden spend and warden savings keep working unchanged they remain available as aliases . Resource footprint — memory/CPU/pressure — is a different axis; see warden stats . Read back the token-savings ledger — the tokens warden's lifecycle features kept out of agents' context windows. A real, append-only record, not an estimate. Gated by the savings config setting default on . Also reachable as warden cost savings . warden savings per-feature table saved/raw tokens, events warden savings --benchmark headline A/B: without-vs-with warden, % cut, $ saved, trend sparkline warden savings --since 7d scope to a window 24h/7d/2w or a date warden savings --json structured summary warden savings --audit raw-vs-kept provenance samples needs savings samples warden savings --calibrate measure this workload's bytes/token vs Claude count tokens needs ANTHROPIC API KEY Two axes are reported separately and never blended: the context axis how much leaner context stayed, in % and $ and the offload axis cloud-model work moved off entirely onto the local LLM, in $ . Each figure states its basis — CALIBRATED or the 4-bytes/token HEURISTIC . See docs/FEATURES.md §29 /srjn45/warden/blob/main/docs/FEATURES.md . The cost side of the ledger: the REAL billed model spend warden measured from agents' transcripts, priced per model into dollars and rolled up per agent / repo / day. Dollar pricing currently covers the Claude backend ; bring-your-own-model backends report tokens only. Gated by the same savings config setting. Also reachable as warden cost spend . warden spend total / today / this week, then per-agent/repo/day $ tables warden spend --by agent just one rollup: agent, repo, or day warden spend --json structured rollup A budget gate off by default turns this into a guardrail: set budget daily usd / budget weekly usd and flip budget gate: true , and a spawn that would push measured spend over the cap warns first re-run with --force to proceed — mirroring the memory-pressure spawn gate. warden ls also gains a COST column, and the web Metrics tab a live per-agent cost card. See docs/FEATURES.md §30 /srjn45/warden/blob/main/docs/FEATURES.md . Opt-in, read-only view of each active agent's branch health: its GitHub CI status latest gh run list in the worktree and its standing vs origin/main commits behind/ahead, merged? . warden branches table of per-agent CI + base-branch standing warden branches --json The daemon monitor behind it enable with branch track.enabled delivers non-blocking alerts — an inbox note to the agent and a desktop ping to you on a new CI failure, an inbox nudge on a merged or far-behind branch. Every gh /git call fails open. Also exposed via GET /api/v1/collab/branches and the get branch status MCP tool. Mine archived agent history for patterns — recurring task shapes, slow/failure-prone work, and parallelization opportunities — as a deterministic report optionally narrated by the local LLM . Gated by insights default on . warden insights warden insights --json Checkpoint an agent's worktree changes + session transcript and roll back later. Gated by snapshots default on . warden snapshot create name -m "before risky refactor" capture a checkpoint warden snapshot list name --all list checkpoints warden snapshot restore <id --force re-apply onto its worktree Restore reapplies the captured stash onto the recorded worktree; it refuses a dirty/conflicting tree rather than clobbering, and a failed apply leaves the snapshot intact. Also available as the snapshot create / snapshot list / snapshot restore MCP tools. Two layers control auto-approval: Per-agent toggle — opt one agent into evaluation even when the global policy is off: warden auto-approve agent-abc123 on warden auto-approve agent-abc123 off Rule policy — a real allow/deny engine. A recognized prompt is auto-answered only when it matches an allow rule, matches no deny rule, and isn't on warden's built-in destructive deny-list which always wins . Rules match by tool name, a case-insensitive glob/substring --pattern , a Go regexp --regex over the prompt, and/or path globs --paths . A per-agent override --agent , keyed by name or id gets its own rule set that replaces the default. Changes take effect immediately and persist to config. warden auto-approve rules show the live policy warden auto-approve enable turn the policy on warden auto-approve allow --tool Read auto-approve all Read prompts warden auto-approve allow --regex '^Bash\ git status|diff|log \ ' warden auto-approve deny --tool Bash --pattern rm warden auto-approve allow --agent reviewer --tool Grep warden auto-approve clear --agent reviewer drop reviewer's overrides With no rules configured, an enabled policy keeps the simple legacy behavior: it auto-answers every recognized, non-destructive prompt selecting the least-privilege affirmative . Multi-select / text-entry / unrecognized prompts always fall back to manual. Also available as the set auto approve toggle and set auto approve policy rules MCP tools. Change a running agent's permission mode acceptEdits / auto / bypassPermissions / default / dontAsk / plan ; preserved on restore. warden set-permission-mode agent-abc123 dontAsk A role is a named, persistent system-prompt persona attached to an agent, plus a set of default spawn flags. Every agent has exactly one role; the default is general , which injects no persona and behaves exactly as agents do today. The role set is a fixed built-in catalog no user-defined roles : | Role | Persona | Default flags | |---|---|---| general | none — plain agent | — | orchestrator | coordinates a fleet of warden agents; plans and delegates, doesn't write feature code itself unless trivial | --permission-mode auto | implementer | implements a task end-to-end on its own branch code, tests, checks, commit, PR | --type development | auto-merger | owns getting an open PR merged: watches CI, fixes failures/conflicts, merges when green | --permission-mode auto , auto-approve on | reviewer | reviews a branch/PR for correctness, coverage, and style; produces findings + a verdict, no fixes unless asked | --type pr-review | The persona is injected through the same system-prompt seam warden already uses for its collab/git/pipeline hints Claude via --append-system-prompt , the injecting backends via their rules file ; only the role name is persisted, so the persona re-resolves from the registry at every re launch — nothing persona-shaped is stored on disk. Role default flags fill only the fields you left unset explicit start flags win ; default tags are unioned in. List the built-in roles and their descriptions warden role list Spawn an agent with a role its default flags apply unless you override them warden start "review PR 1234 for correctness" --role reviewer Switch a running agent's role — relaunches to re-inject the new persona warden set-role agent-abc123 reviewer Clear the persona back to a plain agent warden set-role agent-abc123 general Roles are also drivable from the UIs TUI new-agent ctrl+r picker, web + New agent Role dropdown and over MCP spawn agent 's role param, set role , list roles — see Orchestrator MCP orchestrator-mcp . set-role relaunches the agent its in-flight turn is discarded because a persona only takes effect at re launch, mirroring how set-permission-mode persists a value but a persona additionally needs a fresh launch. The umbrella for warden's worktree operations — list and prune : warden worktree list warden-owned worktrees same as worktree list warden worktree list list worktrees under .worktrees, joined to records alias: ls warden worktree prune reclaim orphaned worktrees prompts; --force overrides guards warden worktree prune --include-archived widen scope to archived records warden prune remains as a top-level alias for warden worktree prune same flags, prompts, and output . Retention is policy-driven via the worktree.keep done / worktree.auto prune config settings; dirty/unpushed worktrees are always kept. Reclaiming whole orphaned worktrees is distinct from warden remove-worktree , which tears down one agent's worktree. The single verb for passing work to another agent, with three modes. Default mode spawns a fresh delegate in its own isolated worktree; --to <id delivers the handoff into an existing agent's inbox waking it — both keep the source running and inline the handoff content into the recipient's prompt/message. --retire requires --confirm is the self-succession mode: it spawns a successor in the calling agent's same worktree and reaps the caller — exactly what the warden rotate alias runs see above . --retire and --to are mutually exclusive. Phase 1 writing the handoff is /warden -skill-driven. Shorthand for warden start --fork-from <agent — fork an existing agent's recorded session into a new managed agent. A fork branches the source's conversation/reasoning Codex's session rollout into a divergent session and continues it as its own agent: a fresh sibling worktree off the source's branch HEAD, seeded with the source's uncommitted tracked changes dirty-tree carry; untracked/ .gitignore 'd build artifacts are not carried , with its own tmux session warden manages and tears down. The source agent keeps running, untouched — fork branches sideways , unlike snapshot rewinds one timeline or rotate / handoff carry the task, drop the conversation . warden fork agent-7 fork agent-7, continue its conversation warden fork agent-7 "now try X" fork and seed a divergent first prompt Only backends with a native session fork are forkable — Codex today codex fork ; forking one without e.g. Claude reports a clean "cannot fork". The source's backend session id must already be pinned let it run a turn first . The fork inherits the source's repo + backend; --type defaults to development . Unlike warden review / warden models , fork is a managed spawn that crosses the daemon, so it has MCP + CLI parity — the fork agent MCP tool is the orchestrator twin a thin wrapper over spawn agent with fork from set, no new endpoint . Manage the bearer token that gates non-loopback remote access — see Remote access remote-access . warden token generate mint a 256-bit token persisted to ~/.warden/token.env, 0600 warden token show print the current token paste into a remote client warden token rotate regenerate in place + restart the daemon warden token show --readonly print the read-only token WARDEN READONLY TOKEN The WARDEN TOKEN env var overrides the file so the secret can stay off disk. Read-only token. Set an optional second token, WARDEN READONLY TOKEN , to hand out view-only access e.g. a shared dashboard or a teammate . A read-only token may read everything — all GETs plus the live event stream — but is denied every state-changing action and the interactive attach. Mint one with warden token generate and export it as WARDEN READONLY TOKEN it only works alongside a primary WARDEN TOKEN ; the daemon refuses to start with a read-only token but no primary one . warden's interactive mode : a proper terminal REPL to drive the fleet, with a real line editor arrow keys, persisted history, reverse-search, a live /-command menu that filters as you type, Tab completion , colourised prompt that closes cleanly with Ctrl-D. It drives the fleet two ways: Deterministic — / commands no model /agents , /spawn <prompt , /tell <id <text , /memory <question , /pipelines , … Typing / pops a live, filtering menu of matching verbs each with its summary ; /help lists them all. These keep working even when the local model is slow or wrong. When a command needs more input, a guided argument form collects it — numbered pick-lists for known fields model, permission, type , free text for the rest — opening automatically for a missing required arg or on a + -suffixed verb /spawn+ ; a local model, if present, pre-fills each field with a suggestion you can accept, override, or clear. Natural language local LLM — any other line is planned into confirmed warden tool calls without spending cloud-model tokens. It conducts; it never implements — all code work is delegated by spawning an agent. Local project grounding — ask a project question "where does the spawn gate live?", "how do I run the tests?" via $0 /memory <q /mem / /ask or the project memory tool and warden answers it locally from .warden/memory.md , citing each entry's trust + provenance. It removes a cloud round-trip rather than adding tokens like injection ; read-only, degrades to the matching entries verbatim with no local model, default on via memory.ground . It starts without a local model the / commands and -shell always work ; only the natural-language half needs local llm: true . Every mutating action passes a mandatory confirm gate. Run standalone, or as the cockpit master pane via the repl config / --repl flag Alt+t toggles it with a raw shell . See docs/FEATURES.md §17 /srjn45/warden/blob/main/docs/FEATURES.md . warden repl aliases: warden interactive, warden i Inspect the plugin registry — external executables that extend warden with custom agent task types and lifecycle hooks over a versioned JSON-over-stdio protocol . Default off plugins: true to enable, since plugins run external code . warden plugin list registered plugins: paths, custom task types, subscribed hook events, config errors Hooks pre/post-spawn , pre/post-commit , pre/post-check are advisory and fail-open — a missing, slow, or crashing plugin is logged and skipped, never blocking an agent. Configure via plugins.enabled + a plugins.registry list in ~/.warden/config.yaml ; a worked example lives under examples/plugins/ /srjn45/warden/blob/main/examples/plugins . See docs/FEATURES.md §26 /srjn45/warden/blob/main/docs/FEATURES.md . Run the daemon HTTP API + background poller . Normally managed by launchd macOS or systemd Linux ; run manually for debugging. warden daemon warden daemon --addr 127.0.0.1:9000 Run the MCP stdio server so an orchestrator agent session e.g. Claude can manage agents via tool calls. warden mcp warden mcp --addr 127.0.0.1:8765 Tools exposed: list agents , get agent , spawn agent , adopt agent , send to agent , get agent output , stop agent , terminate agent , restore agent , delete agent , remove worktree , ctx set , ctx get , ctx list , ctx cas , ctx append , send message , read inbox , wait for message , list approvals , approve , commit , push , sync , check , get collaboration status , who is editing file , get branch status , create pipeline , start pipeline , show pipeline , list pipelines , cancel pipeline , list schedules , snapshot create , snapshot list , snapshot restore , insights , savings , spend . Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell. warden completion bash generate bash completion script warden completion zsh generate zsh completion script warden completion fish generate fish completion script warden completion powershell generate PowerShell completion script The completion script should be redirected to the appropriate location for your shell. See the Shell Completion shell-completion section for installation instructions. Register warden mcp as an MCP server in your orchestrator agent's MCP config. For a Claude Code orchestrator that's ~/.claude/claude desktop config.json or the project-level .claude/mcp.json ; other MCP-capable agents use their own config path: { "mcpServers": { "warden": { "command": "warden", "args": "mcp" } } } warden mcp connects to the daemon at the addr config setting default 127.0.0.1:8765 ; to point it elsewhere use "args": "mcp", "--addr", "host:port" . Once registered, the orchestrator session can call these tools directly: | Tool | Description | |---|---| list agents | List all active agents with their status, working directory, and subject | get agent | Get full detail status, workdir, subject, events, worktree for one agent | spawn agent | Spawn a new agent — pass a prompt for a quick auto-typed agent, or type + repo for a managed worktree; set supervised: true for --permission-mode acceptEdits instead of full bypass; pass role to attach a built-in role persona + its default flags | set role / list roles | Switch a running agent's built-in role relaunches to re-inject the persona; general /empty clears it / list the fixed built-in role catalog name + description for a picker | adopt agent | Register an existing Claude session: resume newest-for-dir under tmux, or live-register a running tmux session | send to agent | Type a message into a specific agent's claude session | get agent output | Return the recent terminal output of a specific agent | stop agent | Umbrella teardown. Default = full teardown terminate + clear record + remove worktree . keep record / keep worktree subtract steps keep worktree alone == the old done ; hard purges the record; pr / base open a GitHub PR first while the agent is intact; force / delete adopted branch for the worktree guards. Destructive when it removes the worktree — only after explicit user confirmation | terminate agent | Stop an agent kill tmux + the agent process ; keeps the record and worktree. Reversible via restore agent — the default "stop this agent" action | restore agent | Recreate and resume a lost/orphaned agent's session claude --resume | recover agents | Safety net for the tombstone reaper: revive archived records whose tmux session is confirmed still alive. apply:false default only reports candidates; apply:true re-inserts each one under its original id, reconnecting any children automatically | delete agent | Clear an agent's stored record archives by default; hard purges . Does not touch tmux or the worktree | remove worktree | Remove an agent's git worktree + branch — destructive; refuses while the agent runs or has uncommitted/unpushed work unless force | ctx set / ctx get / ctx list / ctx cas / ctx append | Read/write the shared-context key/value blackboard agents collaborate through with compare-and-swap and append | send message / read inbox / wait for message | Send a directed message to an agent wakes it if parked / read this agent's inbox / block until a message arrives | list approvals / approve | List recognized pending tool-permission prompts / answer one by option number | commit / push / sync | Git lifecycle on the agent's pinned worktree staged commit with auto-message, push — force uses --force-with-lease , rebase-sync returning compact structs instead of raw git output | check | Run the project's .warden/check.yml checks, returning pass/fail with output for only the failing ones | get collaboration status / who is editing file | File-conflict view across the fleet / who if anyone is editing a given file | create pipeline / start pipeline / show pipeline / list pipelines / cancel pipeline | Drive a DAG pipeline — create from a YAML spec, start entry jobs, inspect, list, cancel | Pipeline MCP tools are thin wrappers over the same daemon routes the CLI uses, so an orchestrator session can run a multi-stage workflow analyze→implement→review without shelling out. Lifecycle controls pause pipeline , resume pipeline , delete pipeline , edit pipeline job , retry pipeline job are available over MCP too, mirroring the warden pipeline … CLI. Example orchestrator prompts: - "What is PROJ-350 doing?" — calls get agent to fetch current status and events - "Tell PROJ-343 to run the tests" — calls send to agent with "run the tests" - "List all my agents" — calls list agents - "Spin up an agent to research SSE reconnection" — calls spawn agent with a prompt auto-typed - "Spawn a debug-ci agent in /path/to/repo" — calls spawn agent with type + repo - "Stop PROJ-350" — calls terminate agent reversible ; "clear its record too" — then delete agent Beyond raw tool access, install the packaged Claude Code skill so a Claude orchestrator session knows how and when to manage your fleet triage, create-from-prompt, relay "tell X to do Y", terminate-with-confirmation, daemon-down handling . Other MCP-capable orchestrators drive the same tools directly without the skill: make install-skill symlinks skills/warden into ~/.claude/skills/warden With the MCP server registered above and the skill installed, just talk to a Claude session: "list my agents" , "spin up an agent to research X" , "what is agent-4f2a doing?" , "tell agent-4f2a to run the tests" , "kill the idle ones" — it drives the MCP tools falling back to the warden CLI if the MCP server isn't registered . The daemon must be running. warden moves deterministic responsibilities off agents — git and checks — onto the first-class warden commit / push / sync / check commands CLI + MCP , and enforces the worktree boundary with PreToolUse hooks delivered through a per-agent claude --settings file Claude Code backend . Each hook fails open a hook error never blocks the agent and is individually config-gated default on : | Layer | Setting | What it does | |---|---|---| Prompt steer | git conventions | A system-prompt hint steering agents toward wd commit / push / sync / check over raw git/test Bash — the gentle first layer | Isolation guard | isolation guard | Denies an isolated agent's Edit/Write that escapes its worktree into the shared repo | Git-guard | git redirect | Deny-redirects raw git commit / push / pull / rebase to the warden tools reads stay allowed | Check-guard | check redirect | Deny-redirects a raw test/lint/build command registered in .warden/check.yml to wd check focused -run invocations pass through | The default write-type isolation each code / docs / website / debug-ci / tests agent gets its own worktree unless --in-repo is what makes the isolation guard meaningful and fixes parallel-agent collisions. See docs/FEATURES.md §22 /srjn45/warden/blob/main/docs/FEATURES.md for the full model. 1. Start the daemon once — then managed by launchd ./scripts/install.sh install + start as a background launchd service recommended make run-daemon foreground, for debugging only blocks the terminal; ctrl-C to stop 2. Spawn an agent for a ticket warden start PROJ-350 --type development 3. Watch what it's doing warden ls warden status PROJ-350 4. Drop into its terminal if needed warden attach PROJ-350 5. Clean up when done warden done PROJ-350 make build go build -o bin/warden ./cmd/warden make test go test ./... includes fuzz seed corpora make lint go vet ./... make run-daemon build + start daemon in the foreground debugging only make test-integration build-tagged end-to-end suite real daemon subprocess + CLI make bench run the Benchmark suite store I/O, pipeline, approvals make fuzz deeper fuzz sweep of the YAML/pane/session parsers make cover whole-repo statement coverage prints the total% The README coverage badge is a static snapshot of make cover 's total — refresh it when coverage moves materially. All unit tests run without Docker or any external services: go test ./... The integration suite make test-integration , build tag integration boots a real warden daemon against an isolated HOME ; its spawn-lifecycle test self-skips unless tmux and claude are installed, so it stays CI-safe. The repo ships version-controlled hooks in .githooks/ . Wire them once with: make install-hooks git config core.hooksPath .githooks or: ./scripts/install-hooks.sh scripts/install.sh the service installer also does this automatically. Once wired: pre-commit runs make fmt-check lint gofmt + go vet — fast, so a formatting/vet slip is caught before the commit lands. pre-push runs make verify-fast gofmt/vet/web/release build — the CI subset that doesn't need an isolated machine. Bypass either in a pinch with git commit --no-verify / git push --no-verify . Because core.hooksPath is a relative path, the hooks work across git worktrees too. The daemon embeds a React dashboard Astro + React and serves it at http://localhost:8765 alongside the REST API — no separate server required. make release 1. builds the Astro UI web/ , 2. embeds it via go:embed, 3. builds bin/warden warden daemon start the daemon as usual Then open http://localhost:8765 in a browser. Note:the UI is baked into the binary at build time. After changing anything under web/ , re-run make release or make ui to rebuild only the frontend and restart the daemon for the changes to take effect. The dashboard is a routed mission-control shell . Tabs are real URLs History-API routing — back/forward, refresh, and shareable deep links all work , so each surface has its own address: | Route | Tab | What's there | |---|---|---| /cockpit | ⊞ Cockpit | The home view / redirects here . A slim Fleet header totals · busy · waiting · errored, pressure, dirs above the full agent grid. | /others | ▦ Others | The former Overview, now a catch-all: Needs you attention queue , File conflicts, and Recent activity. | /pipelines | ⛓ Pipelines | Pipeline list + live DAG / job drawer. | /metrics | 📊 Metrics | Per-agent and fleet-wide charts — see below. | /archive | 🗄 Archive | Ended sessions with since/type filters. | /agent/<id | <id | A pinned agent's live terminal one closeable tab per pinned agent . | Cockpit is the home — / redirects to /cockpit . It carries the Fleet summary header moved out of the old Overview above the canonical agent grid; the redundant Quick spawn widget and the duplicate All agents mini-grid were removed. Metrics tab — a scrollable column of uPlot chart cards: /metrics CPU per agent , Memory per agent GiB , Cost per agent live measured model spend in $, with a total/today/this-week headline and a sorted per-agent cost bar chart — top-N costliest, rest folded into an others row , Context per agent a client-accumulated time series of each agent's live context fill, legend dot colored by ok / warning / critical ; in-session only — resets on full reload , Number of agents fleet size over time , and Tokens saved daily bars from the savings ledger + a headline saved-tokens/$ figure . When the savings ledger is disabled the savings/cost cards show a "set savings: true " hint instead of an empty chart. A Live footprint card carries the former Resources panel. Context & Messages — no longer a tab; opened from a small 🗒 button in the header as a dismissible overlay Esc to close . Agent tabs — pin any agent to its own tab to get a live, interactive terminal AttachTerminal — a real tmux attach bridged to the browser over a WebSocket, so you can type into the agent and watch it respond in real time. Create agent — + New agent opens a prompt box with a directory picker and a Supervised checkbox . Type the task and press Create or Cmd/Ctrl+Enter ; the type label is assigned automatically. Tick Supervised to launch with --permission-mode acceptEdits instead of full bypass. For a managed worktree, use the CLI: warden start TICKET --type development --repo … . Terminate — surfaces the git guard 409 → Force + optional hard-delete when there's uncommitted/unpushed work. Agent grouping — the Cockpit grid buckets agents into collapsible panes by Directory / Type / Status / Tag choice saved to LocalStorage . Batch operations — per-tile checkboxes Shift-click range select raise a bulk action bar offering Message… , Terminate , and Delete across the selection. Search & Archive — a live search box filters the fleet client-side; the 🗄 Archive tab browses ended sessions with since/type filters. Theme toggle — header control cycles System → Light → Dark defaults to System; persisted, applied before first paint . Keyboard shortcuts — a global layer: ? help overlay, n new agent, / focus filter, r refresh, 1 – 9 jump to a tab, j / k next/previous tab, Esc close/blur also closes the Context overlay . Browser notifications — opt in to get a desktop notification when an agent enters waiting for input gated so they only fire while the tab is hidden . The dashboard is mobile-responsive and can be reached from your phone or another machine. Generate a token export WARDEN TOKEN=$ warden token generate , bind a non-loopback address warden daemon --addr 0.0.0.0:8765 , and expose it over Tailscale recommended or a Cloudflare Tunnel. The daemon refuses to bind non-loopback without a token; the browser prompts for it on first load. See docs/USAGE.md → Remote access /srjn45/warden/blob/main/docs/USAGE.md remote-access-phone-tablet-another-machine for the full walkthrough. Run two terminals in parallel — no rebuild loop needed while iterating on the UI: Terminal 1 — daemon REST API + SSE on :8765 warden daemon Terminal 2 — Astro dev server :4321, proxies /api/ REST + /api/v1/.../attach WS + /api/v1/events SSE and /healthz to :8765 make ui-dev Open http://localhost:4321 . Edits under web/src/ trigger HMR instantly; the browser stays on the same origin as the real daemon API so SSE and all REST calls work without CORS configuration. make web-test Vitest — frontend unit tests status mapping, API client go test ./... Go suite — covers daemon hub, SSE endpoint, static embed, and all existing routes The frontend Vitest suite lives in web/src/lib/ alongside the source files status.test.ts , api.test.ts . The Go daemon tests cover the broadcaster hub test.go , the SSE handler sse test.go , and the static file serving with SPA fallback static test.go . Issues and pull requests are welcome. See CONTRIBUTING.md /srjn45/warden/blob/main/CONTRIBUTING.md for licensing, the DCO sign-off git commit -s , and dependency/notices rules. Before opening a PR: gofmt -l $ git ls-files ' .go' must be empty CI enforces gofmt make lint go vet ./... make test go test ./... make web-test frontend unit tests CI build, test, lint runs on every push and PR to main — see .github/workflows/ci.yml /srjn45/warden/blob/main/.github/workflows/ci.yml . Licensed under the Apache License, Version 2.0 . See LICENSE /srjn45/warden/blob/main/LICENSE and NOTICE /srjn45/warden/blob/main/NOTICE . Third-party dependency licenses are listed in THIRD-PARTY-NOTICES.md /srjn45/warden/blob/main/THIRD-PARTY-NOTICES.md . warden is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, Google, Cursor, Block, or any other agent-backend vendor. "Claude" and "Claude Code" are trademarks of Anthropic, PBC; "Codex" of OpenAI; and all other product and company names are trademarks of their respective owners, used here for identification only. warden is a local orchestrator: it drives agent-backend CLIs and services using credentials you supply . You are responsible for complying with the terms, usage policies, and rate limits of every backend and account you connect. warden grants no rights to any third-party service and makes no representation that a given automation or concurrency pattern is permitted under your plan. Copyright 2026 Srajan Pathak Licensed under the Apache License, Version 2.0 the "License" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0