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
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.
| Event | Status | What 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.
| Mode | What lands in the worktree | When 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