Spawn & watch agents

Two ways to spawn

Prompt mode (default — no worktree, auto-typed)

--role is required (general is the plain choice for prompt mode; see warden agent role list). Pass a quoted prompt. The agent launches in your current directory (or the --dir you pass) and assumes no worktree — it operates directly on whatever is in that directory. Use --dir to point it elsewhere.

warden start --role general "investigate why the nightly build is flaky"
warden start --role general "summarize the changes in /path/to/repo since last Friday"
# spawned agent-a1b2 (flaky-nightly) — name auto-resolved from the prompt

• Name is mandatory — omit --name and warden resolves one: role/pipeline conventions (AP:<plan>, wkr:<task>, brain:<target>, <pipe>:<stage>), else a 2–4 word kebab-case slug from the Fast-Brain engine (fast tier, 1.5s timeout) with adjective-noun codename fallback (swift-falcon), else a codename for prompt-less spawns. Auto-names disambiguate with -2, -3; explicit --name collisions still 409.
• Optional complexity routing — set router.use_fast_brain: true (default false) and a spawn that pins no --tier, --task, --role, --model, --aicli or --aicli has Fast-Brain rate the prompt: tier-1 (trivial tweaks), tier-2 (standard work) or tier-3 (deep refactors). It is the lowest-precedence input (explicit tier > task > role > router > default), applies only at confidence ≥ 0.8, falls back to the normal resolution on any failure, and is recorded as a tier-route event on the agent. Autopilot and pipeline spawns are never touched.
• Type is auto-assigned shortly after spawn (the daemon asks claude -p to classify the prompt; falls back to other if claude isn’t available).
• Subject is auto-generated — a ≤8-word phrase summarizing current work, seeded from the prompt and refreshed by the poller.

In the web GUI, + New agent opens a single prompt textarea — no role or repo fields.

Managed worktree mode (--role worker --repo)

When the work belongs to a real repo — especially a development branch tied to a ticket — pass --role worker --repo <path>. This is what creates and manages an isolated git worktree. (--type is deprecated; roles replaced it.)

# Development branch for a Jira ticket (new worktree + new branch):
warden start --role worker --repo . PROJ-350

# PR review (fresh worktree, runs `gh pr checkout`):
warden start --role worker --repo . --pr 1234

# Spike/analysis in a throwaway scratch worktree:
warden start --role worker --repo . --worktree "spike: try the new parser"

# Debug CI — run in the shared checkout instead of a worktree:
warden start --role worker --repo . --in-repo "debug the failing CI job"

# Be explicit about repo and branch:
warden start --role worker --repo /path/to/repo --branch my-branch PROJ-350

Observation & interaction

Command / feature	Description
ls	List active agents (type, status, age, dir, subject). --json for machine output.
status <id>	Full detail for one agent — workdir, subject, worktree, branch, PR, events. --json available.
attach <id>	Attach your terminal to the agent’s tmux session interactively.
send <id> <msg>	Type a message into the agent’s claude session and press Enter.
tail <id>	Print recent terminal output (--lines N).
digest <id>	Completion digest — files touched, branch, turn count, and a best-effort claude -p narrative. --json available.
Stuck / attention detection	Agents flagged waiting_for_input, idle (stuck), orphaned, or errored, surfaced across all interfaces.

warden ls shows ID TYPE STATUS AGE DIR SUBJECT. DIR is the base name of the working directory; SUBJECT is empty until the first poller refresh; TYPE shows … while a prompt agent is still being classified. Use --json for machine-readable output (a JSON array of full session objects; an empty fleet prints []).

warden ls
warden ls --json
warden status agent-a1b2          # full detail + event timeline
warden agent tail agent-a1b2 --lines 80
warden send agent-a1b2 "run the unit tests and fix any failures"
warden agent attach agent-a1b2          # Ctrl-b d to detach

Per-agent settings: agent set / agent get

One pair of verbs reads and changes the settings of a running agent:

warden agent get agent-a1b2                       # all settings
warden agent get agent-a1b2 role --json           # one key, machine-readable
warden agent set agent-a1b2 permission-mode acceptEdits
warden agent set agent-a1b2 compact inherit       # on | off | inherit
warden agent set agent-a1b2 role worker           # relaunches the agent
warden agent set agent-a1b2 auto-approve on

Keys are permission-mode, compact, role and auto-approve. Changing role relaunches the agent (its in-flight turn is discarded). To change a role’s default model tier use warden agent role tier set <role> <tier>.

Scripting: --json

agent start, fork, handoff, stop, terminate, role list and get take --json for machine-readable output (stop/terminate report the id and the steps that ran; --json never prompts, so removing a worktree needs --yes).

The older agent permission-mode set, agent compact set, agent role set, agent done, agent delete and agent remove-worktree still work as hidden aliases.