Worktrees

Overview

Flaio uses Git worktrees to isolate work per ticket. Each ticket gets its own worktree with a dedicated branch, keeping your main working directory clean.

How It Works

When Flaio creates a worktree for a ticket, it:

1. Creates a new Git worktree in the .flaio/worktrees/ directory.
2. Checks out a ticket-based branch (e.g., ticket/<ticket-id>).
3. Records the mapping in a manifest file.

The agent session runs inside the worktree, so your main branch and any uncommitted changes are unaffected.

Worktree Location

<repo>/.flaio/worktrees/<ticket-id>/

Each worktree is a full working copy of your repository on its own branch.

Manifest

Worktree-to-ticket mappings are tracked in:

<repo>/.flaio/worktrees/manifest.json

This file maps each ticketId to its worktreePath. File locks ensure safe concurrent access.

Branch Naming

Branches follow the pattern ticket/<ticket-id>, with names sanitized to lowercase alphanumeric characters and hyphens.

Configuration

Control worktree behavior through settings:

Setting	Description	Default
worktree.planning	Enable planning phase	false
worktree.interactivePlanning	Interactive planning mode	false
worktree.implementation	Enable implementation phase	true

Benefits

• Isolation — each ticket has its own branch and working directory
• No stashing — no need to stash or commit in-progress work on your main branch
• Parallel work — work on multiple tickets simultaneously without branch switching
• Safe concurrency — file locks prevent manifest corruption