watchfire init

Initialize a new Watchfire project in the current directory.

Usage

watchfire init

Description

watchfire init sets up a new Watchfire project by creating the necessary configuration files and directory structure. It must be run from within a git repository (or it will initialize one for you).

What It Does

1. Checks for an existing git repository — initializes one if missing
2. Creates the .watchfire/ directory structure (including tasks/)
3. Generates an initial project.yaml with a UUID, project name, and selected project default agent
4. Appends .watchfire/ to .gitignore (creates the file if missing)
5. Commits the .gitignore change
6. Prompts for an optional project definition
7. Prompts for project settings, including which agent/backend the project should prefer

Interactive Prompts

During initialization, you'll be asked to configure:

Setting	Description	Default
Agent/backend	Project default agent written to .watchfire/project.yaml	Global default agent if set, otherwise claude-code
Project definition	A description of your project used as context for every agent session	Empty
Auto-merge	Automatically merge completed task branches	true
Auto-delete branches	Delete worktree branches after merge	true
Auto-start tasks	Start an agent when a task is set to ready	true

The selected backend is stored as default_agent in the project config. You can change it later in project settings.

If you leave agent selection unset at the project level, Watchfire resolves the effective backend using:

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

Examples

Initialise inside an existing repo

cd my-project
watchfire init

Run from the repo root. init detects the existing git repo, creates .watchfire/, appends an entry to .gitignore, and walks you through the interactive prompts. Example generated config:

project_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: my-project
default_agent: codex
sandbox: auto
auto_merge: true
auto_delete_branch: true
auto_start_tasks: true
definition: ""
next_task_number: 1

After running, your project directory will contain:

my-project/
├── .watchfire/
│   ├── project.yaml
│   └── tasks/
├── .gitignore          # Updated with .watchfire/
└── ...your files

Initialise with a non-default agent

mkdir new-tool && cd new-tool
git init
watchfire init

When prompted for Agent/backend, pick codex, opencode, gemini, or copilot — the choice is written to default_agent in project.yaml and inherited by every session in the project. You can change it later with watchfire configure.

Bootstrap definition and tasks immediately after

watchfire init
watchfire generate
watchfire plan

A common starter sequence: initialise, draft a definition from the codebase, then generate the first task list. Refine the definition with watchfire define between generate and plan for sharper output.

Common pitfalls

• Run from a parent directory — watchfire init initialises whatever directory it's run from, not the project you meant. Fix: cd into the project root first; the prompt confirms the project name before writing files.
• .gitignore not committed — the .watchfire/ line is appended but the change is left unstaged. Fix: init creates a commit for the .gitignore change automatically, but if the repo had no commits yet the commit may be skipped — verify with git log -1 --stat.
• Re-running on an existing project — watchfire init refuses to overwrite an existing .watchfire/project.yaml. Fix: edit settings with watchfire configure instead, or remove .watchfire/ first if you really want a fresh start.