Quick Start

Two commands to go from zero to autonomous coding agents.

1. Initialize a Project

Navigate to your project directory and initialize Watchfire:

cd your-project
watchfire init

This will:

1. Check for git (initialize a repo if missing)
2. Create the .watchfire/ directory structure
3. Create an initial project.yaml with a generated UUID
4. Add .watchfire/ to .gitignore
5. Prompt you for a project definition and settings

Project Settings

During initialization, you'll configure:

• Auto-merge — Automatically merge completed work to your default branch
• Auto-delete branch — Clean up task branches after merge
• Auto-start tasks — Start the agent when a task is set to ready
• Default branch — The branch to merge completed work into (default: main)

2. Launch Wildfire

Let Watchfire take it from here:

watchfire wildfire

Wildfire mode is the fastest way to go from an empty project to working code. It autonomously:

1. Generates a project definition from your codebase
2. Creates tasks based on the definition
3. Executes each task in isolated git worktrees
4. Merges completed work back to your default branch
5. Loops — refining drafts and generating new tasks as needed

Sit back and watch your project take shape.

Going Further

Add tasks manually

You can also create tasks yourself:

watchfire task add

You'll be prompted to enter:

• Title — A short description of the task
• Prompt — Detailed instructions for the AI agent
• Acceptance criteria — How to verify the task is done

Tasks are stored as YAML files in .watchfire/tasks/:

task_id: a1b2c3d4
task_number: 1
title: "Setup project structure"
prompt: |
  Create the initial project structure with...
acceptance_criteria: |
  - Directory structure matches spec
  - All config files present
status: draft

Configure secrets

Store API keys, environment setup, and service credentials in .watchfire/secrets/instructions.md. Watchfire injects these into the agent's system prompt automatically — so agents can access external services without you hardcoding secrets into task prompts.

See Secrets & Setup Instructions for details.

Launch the TUI

Start the interactive TUI to manage tasks and monitor agents:

watchfire

The TUI shows a split view with your task list on the left and the agent terminal on the right:

┌──────────────────────────────────┬──────────────────────────────────┐
│  Task List                       │  Agent Terminal                  │
│                                  │                                  │
│  Draft (2)                       │  > Starting session...           │
│    #0001 Setup project structure │                                  │
│    #0002 Implement login flow    │  Claude Code v2.1                │
│                                  │  ~/source/my-project             │
│  Ready (0)                       │                                  │
│  Done (0)                        │  > Working on task...            │
├──────────────────────────────────┴──────────────────────────────────┤
│ Ctrl+q quit  Ctrl+h help  Tab switch panel       a add  s start    │
└─────────────────────────────────────────────────────────────────────┘

Run tasks from the CLI

# Run a single task
watchfire run 1

# Run all ready tasks sequentially
watchfire run all

# Interactive chat mode
watchfire run

Next Steps

• Secrets & Setup Instructions — Give agents access to external services
• Agent Modes — Learn about Chat, Task, Wildfire, and more
• Projects and Tasks — Understand the YAML schemas
• CLI Reference — Full command reference