~2 min read

A two-minute tour of Watchfire.

Name: Watchfire
Author: Watchfire

Six annotated screens, one screen per step. By the end you'll know what a project, a task, a worktree, and Wildfire mode are — and how the TUI and GUI fit together.

Start tour Skip to install

Step 1Define your project

Tell Watchfire what you’re building.

watchfire init drops a project.yaml in your repo. It pins the default agent, the sandbox policy, and a plain-English definition the agent reads on every task — so context arrives the same way every time.

YAML

# .watchfire/project.yaml
project_id: a1b2c3d4-e5f6-...
name: my-project
default_agent: claude-code
sandbox: auto
auto_merge: true
auto_start_tasks: true
definition: |
  Marketing site for Watchfire.
  Next.js + Tailwind. Fire palette.
  Reuse existing SVG components.
next_task_number: 5

definition

A short brief in your own words — stack, conventions, goals. The agent re-reads it on every task, so context doesn’t drift.

default_agent

Which CLI runs your tasks: claude-code, codex, opencode, gemini, copilot, or cursor. A task can override it.

auto_merge

When the agent finishes, the worktree branch is merged back into main automatically. Set to false to review first.

Full schema in /docs/quickstart.

Step 2Add tasks

Each unit of work is one YAML file.

A task is a title, a prompt, acceptance criteria, and a status. Tasks flow draft → ready → done. The daemon never starts a draft; only ready tasks get an agent.

YAML

# .watchfire/tasks/0042.yaml
task_id: a1b2c3d4
task_number: 42
title: "Fix pagination cursor"
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
position: 1

prompt

What the agent should do. Be specific — point at files, name functions, link existing patterns to follow.

acceptance_criteria

How the agent (and you) know it’s done. Bullet-list the user-visible outcomes, not the implementation.

position

Sort order in the task list. Start All and Wildfire pick tasks in this order.

Build one interactively at /playground, or copy a template.

Step 3Launch the TUI

Drive the whole thing from the terminal.

watchfire opens a Bubbletea TUI: task list on the left, live agent terminal on the right, status bar at the bottom. Everything is keyboard-driven and works the same over SSH.

Task list

Every task in the current project, grouped by status. Press j/k to move, s to start the selected one. CLI docs →

Agent terminal

The right pane streams the running agent’s PTY — exactly what you’d see if you ran the CLI by hand. shortcuts →

Status bar

Daemon state, current project, and a hint for the next keystroke. ? opens the full key map.

Project switcher

Press Ctrl+f for the cross-project fleet view to jump between repos without leaving the TUI.

Step 4Pick an agent mode

Six modes, one mental model.

Each mode wires the agent to a different scope of work — from a single conversation to a fully autonomous loop. Pick one in the TUI with a single keystroke, or pass it to watchfire run.

Chat

Interactive session in the project root — pair-program, ask, iterate.

Task

Run one task in its own worktree on branch watchfire/<n>.

Start All

Drain every ready task sequentially, one worktree per task.

Wildfire

flagship

Autonomous loop — execute, refine drafts, generate new tasks, repeat.

Generate Definition

One-shot: scan the codebase and write project.definition.

Generate Tasks

One-shot: read the definition and create new task files.

Plain-English definitions of every mode in /glossary.

Step 5Watch it run

One worktree per task. The daemon is the conductor.

When a task starts, the daemon creates a fresh git worktree on watchfire/<n>, sandboxes the agent inside it, and streams its terminal. When the agent finishes, the branch merges back to main.

Isolated worktrees

Each task gets its own directory and branch. Tasks can’t step on each other’s files even when they run in parallel.

Sandboxed agents

On macOS the agent runs under sandbox-exec; ~/.ssh, ~/.aws, and .env are off-limits.

Auto-merge

When success: true lands in the task file, the daemon merges the branch back to main and deletes the worktree.

Architecture deep-dive: /docs/components/daemon.

Step 6Multi-project

Run many projects, each in its own window.

Watchfire.app is an Electron client over the same daemon — a mission-control home window for the whole fleet, plus an independent window per project with the agent chat as the wide main pane and a tabbed reference panel beside it.

Home window

Every registered project on this machine, rolled up in the dashboard — what’s running, what needs attention. Click a project to open it in its own window.

Chat up front

The agent terminal is the wide left pane of each project window. Pick a backend, start any mode — Wildfire included — and watch it stream.

Reference tabs

Tasks, Definition, Insights, Secrets, Trash, Settings — a tabbed panel on the right. Hide it when you want the chat full-width.

Full GUI walkthrough: /docs/components/gui.

That’s the tour

What’s next?

Three ways to keep going — install the binary, read the long form, or grab the one-page cheatsheet.