watchfire task

Manage tasks in your Watchfire project.

Usage

watchfire task <subcommand> [arguments]

Subcommands

task add

Create a new task interactively.

watchfire task add

Opens interactive prompts to set the task title, prompt, acceptance criteria, status, and (optionally) the agent backend to run this task on. The task is saved as a YAML file in .watchfire/tasks/.

If you skip the agent prompt, the field is omitted and the task uses the project's default agent at execution time.

task list

List all tasks in the project.

watchfire task list
watchfire task ls          # alias

Displays tasks grouped by status (draft, ready, done). Soft-deleted tasks are excluded by default.

Flag	Description
--deleted	Include soft-deleted tasks in the listing

task <number>

Edit an existing task interactively.

watchfire task 1
watchfire task 3

Opens the specified task (by task number) for interactive editing. You can modify the title, prompt, acceptance criteria, status, and agent override.

task delete

Soft-delete a task.

watchfire task delete <number>
watchfire task rm <number>    # alias

Sets the deleted_at timestamp on the task. The task file is preserved but hidden from task list by default.

task restore

Restore a soft-deleted task.

watchfire task restore <number>

Clears the deleted_at timestamp, making the task visible again.

Task Agent Override

Each task YAML may include an optional agent field to pin the backend used for that task:

task_id: a1b2c3d4
task_number: 2
title: "Refactor docs search"
agent: gemini
prompt: |
  Replace the existing search index with a fuzzy matcher.
acceptance_criteria: |
  - Search returns results for partial matches
  - Existing tests pass
status: ready

When agent is omitted, Watchfire resolves the effective backend in this order:

1. task.agent
2. project.default_agent
3. Global default agent
4. claude-code

See Projects and Tasks for the full schema and Supported Agents for the available backends.

Examples

Add a focused task from the CLI

watchfire task add

The interactive prompt produces a YAML file in .watchfire/tasks/:

task_number: 4
title: "Fix off-by-one in pagination cursor"
prompt: |
  Cursor in `lib/paginate.ts` returns one fewer row than
  `limit` on the first page. Fix and add a regression test.
acceptance_criteria: |
  - First page returns exactly `limit` rows
  - Existing tests pass
status: ready

Setting status: ready triggers the agent immediately when auto_start_tasks: true (the default). Keep prompts focused — narrow scope is what stops the agent from drifting.

List ready tasks

watchfire task list

Sample output:

DRAFT
  5  Document deploy runbook

READY
  4  Fix off-by-one in pagination cursor
  6  Bump pino to 9.x

DONE
  1  Add tests for lib/parser.ts          (success)
  2  Refactor docs search                 (success)
  3  Diagnose 500s on POST /api/orders    (success)

Tasks are grouped by status and sorted by position then task_number. Add --deleted to include soft-deleted tasks.

Pin a task to a different backend

watchfire task add

When prompted for the agent, set gemini (or any of claude-code, codex, opencode, copilot, cursor). The resulting YAML carries the override:

task_number: 7
title: "Refactor docs search"
agent: gemini
status: ready

task.agent wins over project.default_agent and the global default. See Projects and Tasks → Agent Selection.

Stop a runaway agent

watchfire task delete 7

Soft-deleting a ready task removes it from the queue. To stop an actively running agent, use the TUI/GUI session controls (Ctrl+C in the foreground session, or the stop button in the Chat panel) — task delete only affects the task definition, not the session.

Common pitfalls

• Empty task list — watchfire task list prints nothing because the project has no ready tasks (deleted ones are hidden by default). Fix: run watchfire task list --deleted to see soft-deleted tasks, or add new ones with watchfire task add / watchfire generate.
• Editing a done task does not re-run it — watchfire task <number> lets you change fields, but flipping status from done back to ready does not always re-trigger the agent. Fix: if you want a fresh run, add a new task instead of resurrecting a completed one.
• agent: value rejected — only the six supported backends are valid. Fix: use claude-code, codex, opencode, gemini, copilot, or cursor — see Supported Agents.