Git Worktree Isolation

Watchfire uses git worktrees to isolate each task's work from the main working tree. Within a single project the agent runs one task at a time, but the worktree means even that single task is fully insulated from your branch, your uncommitted edits, and any other project running concurrently on the same daemon.

How It Works

When a task starts, the daemon:

1. Creates a new branch: watchfire/<task_number> (e.g., watchfire/0001)
2. Creates a worktree at .watchfire/worktrees/<task_number>/
3. The agent runs inside this worktree, not the main working tree
4. On completion, the worktree is merged back to the target branch

your-project/
├── .watchfire/
│   └── worktrees/
│       └── 0001/          ← Active task's agent works here
│           ├── src/
│           └── ...
├── src/                   ← Your main working tree (untouched)
└── ...

A project has at most one active worktree at a time (the one belonging to the currently running task). Worktrees are created when a task starts and removed after a successful merge — so the worktrees/ directory is usually empty between tasks, or holds one entry while a task is in flight.

Branch Management

Aspect	Behavior
Branch naming	watchfire/<task_number> (e.g., watchfire/0001)
Creation	Created from current HEAD of the checked-out branch
Stale branches	If a branch already exists, it's deleted and recreated from current HEAD
Cleanup	Branch deleted after successful merge (if auto_delete_branch is enabled)

Merge Behavior

When a task completes successfully:

1. The daemon merges the worktree branch into the currently checked-out branch
2. If the merge succeeds, the worktree and branch are cleaned up
3. If a merge conflict occurs:
   • git merge --abort restores a clean working directory
   • The chain stops (in Start All / Wildfire mode) to prevent cascading failures
   • You need to resolve the conflict manually

To review the changes a task produced before (or after) the merge, open the Inspect tab in the GUI or press d in the TUI.

Why Worktrees?

Isolation

Each task gets a complete, independent copy of the codebase. The agent can modify any file without affecting:

• Your main working tree
• Other running tasks
• Uncommitted changes you're working on

Cross-project Safety

The daemon runs one agent per project — within a project the queue is strictly serial — but multiple projects can run agents at the same time. Each agent works inside its own worktree, so there are no file conflicts even when the same machine is driving four repos at once.

Clean Merges

Since each task branches from the same point, merges are straightforward. Watchfire handles the merge automatically when auto_merge is enabled.

Easy Rollback

If a task produces bad results, you can simply discard the branch. Your main branch is never modified until a successful merge.

Pruning

The daemon periodically detects and cleans orphaned worktrees — worktrees that exist on disk but are no longer associated with an active task.