Tasks and 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

The board

A project's board, with tasks in To Do, In Progress, In Review and Done

Each project has a board with a column per status. Drag a card to another column to change its status. Open the board from the project's row in the sidebar, or press ⌘T.

Press ⌘N (Ctrl+N on Linux) for a new task. It takes a name and, optionally, a prompt for the agent. Images pasted into the prompt are there for the agent to read. Tasks are numbered (T-1, T-2), and the number names the task's branch and worktree.

Right-click a card, or the task in the sidebar, to start or resume it, open it in your editor, go to its pull request or issue, move it to another column or the trash, branch a new task from it, or rename it. Shells that don't belong to a task get a strip of their own on the board.

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, or Resume on a task already 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.
Trash Task removed Moves the worktree to the trash, deletes the branch.

Branch from

A new task branches from whatever the project has checked out. To start every task from the same place, pick a branch under Project Settings → Worktree → Branch from. A remote branch such as origin/main is fetched first, so tasks start from what was last pushed. If the fetch takes longer than five seconds, the last fetched copy is used. The task's branch does not track the remote one.

Merge targets

Each task has a merge target: the branch its work will merge into. By default it is the branch the task started from, or the local branch of a remote one (main for origin/main). It sets 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.

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