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 definition retrofit	Fold completed tasks back into the definition.
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 quick	Batch-create from a bulleted list (`--ready`, `--draft`, `--stdin`).
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 integrations add telegram	Store the bot token, enable the Telegram bridge.
watchfire telegram pair	One-time code + deep link to pair your phone.
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.
Retrofit Def.	Fold tasks shipped since the last retrofit back into the definition.

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

Telegram bridge

docs →

just type	Talk to a chat agent — one auto-starts if idle; replies stream back.
/use <name>	Pick the project this chat talks to.
/status [all]	Project detail, or one line per project for the fleet.
/run <n>\|all	Run a task / drain ready tasks. Replaces the running agent.
/wildfire [off]	Start/stop the loop; watch relays a milestone feed.
/stop	Stop whatever is running (chains end too).
/new	Fresh chat session — clears context.
/login	Re-auth Claude from your phone: link out, code back.
/screen	Plain-text snapshot of the live session.
/say <text>	Type into a working session explicitly.
/watch on\|off	Live conversation relay — on by default.
/mute on\|off	Pause/resume pushed events.

Pair first: watchfire telegram pair. Unpaired chats get silence.

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.md and 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.