One page

Watchfire cheatsheet.

Name: Watchfire
Author: Watchfire

Every CLI command, TUI binding, YAML field, agent mode, and gotcha in one tab. Print it (⌘P) and pin it above your monitor, or keep it open while you learn.

Want the long form? Start at /docs. Build a task interactively at /playground. Look up a term in /glossary.

CLI commands

docs →

Project

watchfire init	Initialize project in current dir. docs
watchfire status	Snapshot of project, daemon, active sessions. docs
watchfire define	Edit project definition in $EDITOR.
watchfire configure	Walk through every project setting.
watchfire update	Update all components to the latest release.
watchfire version	Show version of every component.

Tasks

watchfire task list	List tasks (alias `task ls`). Add `--deleted` for soft-deleted.
watchfire task add	Create a new task interactively.
watchfire task <n>	Edit task by number, interactively.
watchfire task delete <n>	Soft-delete (alias `task rm`).
watchfire task restore <n>	Un-soft-delete.

Run agents

watchfire run	Chat mode (no task).
watchfire run <n>	Execute one task in an isolated worktree.
watchfire run all	Drain every ready task sequentially.
watchfire wildfire	Autonomous Execute → Refine → Generate loop (alias `fire`).
watchfire generate	Generate project definition (alias `gen`).
watchfire plan	Generate tasks from definition.

Daemon & ops

watchfire daemon start	Start watchfired (usually automatic).
watchfire daemon status	Host, port, PID, uptime, active sessions.
watchfire daemon stop	SIGTERM — kills every session across projects.
watchfire integrations list	List configured outbound adapters.
watchfire metrics backfill	Rebuild per-task metrics files.
watchfire settings	Manage per-project settings non-interactively.

TUI keybindings

full list →

Global

Ctrl+q	Quit.
Ctrl+h	Toggle help overlay.
Ctrl+g	Global settings overlay.
Ctrl+f	Fleet (cross-project) insights.
Ctrl+e	Export report (CSV / Markdown).
Ctrl+i	Integrations overlay.
Tab	Switch left/right panel focus.

Task list

j / k ↓ / ↑	Move selection.
/	Incremental search.
Shift+↑/↓	Reorder within status group.
1 / 2 / 3	Tasks · Definition · Settings.

Task actions

a	Add task.
e Enter	Edit task.
s	Start agent on selected task.
S	Stop the running agent.
r	Set status → Ready.
t	Set status → Draft.
d	Mark Done · or open diff if already Done.
w	Wildfire mode.
!	Start all ready tasks.
i	Per-project insights overlay.
x	Soft-delete selected task.

Right panel

PgUp / PgDn	Scroll terminal or log content.
R	Resume agent after an issue banner.
Enter / Esc	Open / close log in Logs tab.

Task form

Tab	Next field.
Ctrl+s	Save and close.
Esc	Cancel.
Space / Enter	Toggle status · or cycle agent forward.
← / →	Cycle agent backend.

File layout

docs →

Per-project state lives under .watchfire/ (gitignored).

.watchfire/
├── project.yaml         project config (id, default_agent,
│                        sandbox, auto_merge, definition)
├── tasks/               one YAML file per task
│   ├── 0001.yaml
│   └── 0002.yaml
├── memory.md            persistent project knowledge
│                        (agents read + update across sessions)
├── secrets/
│   └── instructions.md  injected into agent system prompt
│                        — API keys, env, CLI auth notes
└── worktrees/
    └── <task_number>/   isolated git worktree, branch
                         watchfire/<task_number>

Global state: ~/.watchfire/projects.yaml lists every registered project; ~/.watchfire/settings.yaml holds global defaults and notification preferences.

Task YAML

playground →

Save as .watchfire/tasks/NNNN.yaml. Minimum: title, prompt, acceptance_criteria, status.

task_id: a1b2c3d4         # 8-char id (daemon assigns)
task_number: 1            # sequential, used for file name
title: "Fix pagination cursor"
agent: ""                 # optional — override project default
prompt: |
  Cursor in lib/paginate.ts returns one fewer row
  than `limit` on the first page. Fix + add a
  regression test.
acceptance_criteria: |
  - First page returns exactly `limit` rows
  - Existing tests pass
status: ready             # draft | ready | done
success: null             # null (pending) | true | false
failure_reason: ""        # set by agent when success: false
position: 1
agent_sessions: 0
# NEVER write created_at / started_at / completed_at /
# updated_at / deleted_at — the daemon fills these in.

status: draft · ready · done. success: null = pending, true = OK, false = explain in failure_reason.

Project YAML

docs →

Lives at .watchfire/project.yaml. Created by watchfire init.

project_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: my-project
default_agent: claude-code   # claude-code | codex | opencode |
                             # gemini | copilot | cursor
sandbox: auto                # auto | seatbelt | landlock |
                             # bwrap | none
auto_merge: true             # merge worktree on task done
auto_delete_branch: true     # delete branch after merge
auto_start_tasks: true       # start agent when task = ready
definition: |
  What the project is, the stack, key conventions.
  The agent reads this before every task.
next_task_number: 5

Agent resolution order: task.agent → project.default_agent → global default → claude-code.

Agent modes

docs →

Chat	Interactive session, no task context — agent runs in project root.
Task	Execute one task in an isolated worktree on branch watchfire/<n>.
Start All	Drain every ready task sequentially; stops on merge conflict.
Wildfire	Autonomous Execute → Refine drafts → Generate new tasks loop.
Generate Def.	One-shot: analyze codebase and write project.definition.
Generate Tasks	One-shot: read definition and create new task files.

See /glossary#wildfire for plain-English definitions of every mode.

Common gotchas

troubleshooting →

Never write timestamp fields in task YAML — created_at, started_at, updated_at, etc. are daemon-managed. Empty strings like started_at: "" make the YAML parser reject the file.
Never remove .watchfire/ from .gitignore — secrets, worktrees, and registered projects must stay out of the repo. Only ever append to .gitignore.
Secrets never enter git. Edit .watchfire/secrets/instructions.mdand tell the agent what services are pre-authenticated — don’t paste API keys into task prompts. See /docs/concepts/secrets.
Sandbox blocks credential dirs. Agents cannot read ~/.ssh, ~/.aws, ~/.gnupg, ~/.netrc, or .env files. Use the secrets file to pass what they actually need.
Don’t create or delete worktrees yourself. Watchfire manages .watchfire/worktrees/<n>/ and the matching watchfire/<n> branch.
Restart protection. Three consecutive same-task restarts cause Start All / Wildfire to bail to chat mode — usually rate limits or auth. Stop the agent and fix the root cause.

Need more? Read the full documentation, browse task templates, or try the playground.