Worktrees

Every task gets its own git worktree: an isolated directory on its own branch. Work on several tasks at once without branch switching, stashing, or agents overwriting each other.

How tasks map to worktrees

Git worktrees let one repository check out several branches into separate directories at the same time. Ouijit creates one per task when the task starts, so each piece of work has its own directory and branch. 

~/Ouijit/worktrees/
  my-project/
    T-42/                # Worktree for task 42
    T-43/                # Worktree for task 43

Task lifecycle

A task has one of four statuses: To Do, In Progress, In Review, Done. Each event below changes the status and can run a hook.

EventStatusWhat Ouijit does
Create → To Do Adds a task card to the To Do column.
Start To Do → In Progress Creates a branch (e.g. T-42) and a worktree at ~/Ouijit/worktrees/<project>/T-42, opens a terminal in it, runs the start hook.
Continue In Review or Done → In Progress Opens a new terminal in the existing worktree, runs the continue hook.
Review → In Review Runs the review hook.
Done → Done Runs the done hook.
Delete Task removed Moves the worktree to the trash, deletes the branch.

Merge targets

Each task has a merge target, the branch its work is destined for. It defaults to the repository's main branch and drives the default diff base. Set it per task to chain a task off a parent branch: 

ouijit task set-merge-target 43 T-42

Copy-on-write cloning

Ouijit clones worktrees with copy-on-write (APFS on macOS, btrfs/XFS reflinks on Linux):

  • Worktree creation is fast regardless of repository size.
  • Disk usage is proportional to your changes, not the full repository.
  • Gitignored files (dependencies, build caches) come along, so the worktree is ready to run.

Choose a creation mode

Each project picks how new worktrees are populated, under Project Settings → Worktree.

ModeWhat lands in the worktreeWhen to pick it
Quick start (default) Tracked files plus a copy-on-write clone of every gitignored path (node_modules, .env, build caches). You want a worktree that runs immediately, with no setup step.
Clean checkout Just git worktree add. Only tracked files appear. You want a reproducible setup driven by your start hook (e.g. npm ci), or you don't want gitignored secrets copied across tasks.

Sandboxed tasks always use clean checkout, regardless of this setting. Provision the VM-side environment with the sandbox setup hook.

Inspect worktrees manually

Ouijit manages worktrees for you, but they are standard git worktrees:

# List all worktrees
git worktree list

# From inside a worktree, check which branch it's on
git branch --show-current