watchfire run

Run an agent session — chat mode, single task, or all ready tasks.

Usage

watchfire run [taskid|all]

Modes

Chat Mode (no arguments)

watchfire run

Starts an interactive chat session with the coding agent. The agent has access to your project but is not assigned a specific task. Equivalent to the old watchfire chat command.

Single Task

watchfire run <taskid>

Executes a specific task by its task number. The agent is spawned in an isolated git worktree on a dedicated branch (watchfire/<taskid>), with the task prompt and acceptance criteria injected into context.

When the agent marks the task as done, Watchfire automatically:

• Stops the agent session
• Merges the worktree branch (if auto-merge is enabled)
• Cleans up the worktree (if auto-delete is enabled)

All Ready Tasks

watchfire run all

Runs all tasks with status: ready sequentially. After each task completes, the next ready task is started automatically. This is equivalent to the Start All agent mode.

Flags

Flag	Description
--sandbox <backend>	Override the sandbox backend. Valid values: auto, seatbelt, landlock, bubblewrap, none.
--no-sandbox	Shorthand for --sandbox none — disables sandboxing entirely.

Sandbox priority: CLI flag → project setting (project.yaml) → global default (settings.yaml).

Agent Selection

watchfire run uses whichever backend Watchfire resolves for the session — it does not force a specific agent. Resolution order:

1. task.agent (for single-task runs, if set)
2. project.default_agent
3. Global default agent
4. claude-code

In run all mode, each task is launched independently, so tasks pinned to different backends in their own agent field will each run on their pinned backend.

See Supported Agents for the full list of backends and Projects and Tasks for the resolution rules.

Examples

Run a single ready task

watchfire run 3

The agent spawns in .watchfire/worktrees/3/ on a fresh watchfire/3 branch off your current HEAD. With auto_merge: true (the default in project.yaml), Watchfire merges and cleans up the worktree as soon as the task flips to done.

Drain the ready queue

watchfire run all

Runs every ready task one at a time, merging each completed branch before starting the next. The chain stops on a merge conflict so a failing task can't poison the rest.

Open a chat session in the project root

watchfire run

Equivalent to watchfire chat — no arguments means a free-form chat session, not a task. The agent runs in the project root, not a worktree.

Bypass the sandbox for a single task

watchfire run 7 --no-sandbox

Useful when the task legitimately needs to touch a path the sandbox blocks. The flag applies only to this session — it does not change the project's sandbox setting.

Common pitfalls

• Argument is not a task number — watchfire run all is a special argument; passing a non-numeric string that isn't all opens chat mode silently. Fix: check watchfire task list for the correct task number first.
• Task runs against an unexpected backend — the agent that starts isn't the one you used last week. Fix: the resolution order is task.agent → project.default_agent → global default → claude-code; pin agent: on the task or change the project default with watchfire configure.
• Chat mode edits leak into your branch — watchfire run (no args) writes to the project root, not a worktree. Fix: use a task instead when isolation matters — see Investigate a bug without disturbing your branch.