Quickstart

New here? Take the guided tour

Run warden tutorial for an interactive walkthrough of the whole loop (spawn → watch → commit → tear down). Until you’ve taken or skipped it, warden prints a one-line nudge. warden tutorial --skip dismisses it; --reset brings it back.

The fastest path is prompt mode: give a plain-English task and a role (--role is required; general is the plain choice) and let warden handle the rest. No repo needed.

warden start --role general "review the auth module for security issues"
# spawned agent-a1b2 (classifying…) — attach with `warden agent attach agent-a1b2`

What just happened:

• A new agent got an ID like agent-a1b2 and is launched in the directory you ran the command from (your current shell’s cwd) — no per-agent directory is created.
• It’s running claude on your prompt inside a tmux window.
• The type shows as classifying… for a moment, then the daemon labels it (e.g. analysis) automatically.

Now watch and interact:

warden ls                         # see it in the list
warden status agent-a1b2          # full detail + event history
warden agent tail agent-a1b2            # recent terminal output
warden send agent-a1b2 "also check the session cookie handling"
warden agent attach agent-a1b2          # drop into its terminal (Ctrl-b d to detach)
warden agent stop agent-a1b2 --keep-worktree            # tear it down when finished

That’s the whole loop. Everything else is variations on it.

The lifecycle of an agent

start ──▶ spawning ──▶ working ⇄ idle ⇄ waiting_for_input ──▶ done
                                                      └─▶ errored / orphaned

Status is driven by Claude Code lifecycle hooks plus the daemon’s poller. You don’t set it manually.

Typical workflows

Ad-hoc investigation (prompt mode):

warden start --role general "find and fix the flaky test in the payments suite"
warden ls
warden agent tail <id>
warden send <id> "skip the integration tests for now"
warden agent stop <id> --keep-worktree

Ticketed development (managed worktree):

warden start --role worker --repo . PROJ-350     # worktree + branch
warden status PROJ-350
warden agent attach PROJ-350                       # jump in when needed
warden agent stop PROJ-350 --keep-worktree                          # guarded teardown

Reviewing a PR:

warden start --role worker --repo . --pr 1234
warden agent tail prreview-...
warden agent stop prreview-... --keep-worktree