Working in worktrees

A worktree is a second copy of your project's files, on its own git branch, that shares the same repository. Give a ticket its own and two agents can work at once without editing the same files.

This tutorial follows one real run on a small ToDo app, on canon 0.47.10 and Windows. You will add two tickets, run them side by side, close both, merge the second into the default branch and finish:

You need a project that uses git, with one closed ticket behind it, as at the end of the Quick start. A project without git has no worktree panel; see Projects without git. Ticket ids differ in your project; ours were t-80kz (CSV) and t-tko0 (timestamp). Both tickets change index.html, which is what a merge has to deal with.

Some steps need care, so they carry two kinds of box: a purple Check before you continue, and an amber Watch out for the traps we fell into.

1. Get the project ready before you add anything

A worktree only carries committed files. Commit your project's setup files (AGENTS.md, CLAUDE.md, .gitignore, and HANDOFF.md if canon has written to it) and track .tickets/ in git (see Registering skills). Leave the skill link folders, .claude/skills and .agents/skills, out of your commits; skills.sh add already ignores them.

Use the board's Terminal tab: type su and approve the operating-system prompt to get a full shell for 10 minutes. Cockpit and board explains it. Then:

git status git diff --stat git add AGENTS.md HANDOFF.md git commit -m "chore: commit setup files" git status
The Cockpit Terminal tab. git diff --stat shows AGENTS.md and HANDOFF.md changed, git add and git commit follow, and git status ends with nothing to commit, working tree clean.
Commit the setup files, then check the tree is clean. Click to enlarge.

On Windows, git add prints a warning that LF will be replaced by CRLF the next time Git touches the file. It is a line-ending notice, not an error: the commit line below it succeeded. If your project has a remote, git status may say your branch is ahead of it by one commit. You do not need to push for a worktree.

Check before you continue
  • git status says the working tree is clean. A few untracked files are fine, such as a ticket's cockpit-sessions.md session log.
  • You know your default branch. It may be main or master; this page says "the default branch", and in our run it was master.

2. Add two tickets nothing is started yet

Press + New at the top of the board. The New Ticket dialog has a title, a Type, a Priority, Tags, three Options (CI, Eval-only and Lite) and a description with Problem, Outcome and Constraints sections. There is no Worktree row: you choose where a ticket runs when you start it. We left all three Options off.

Our first ticket:

The New Ticket dialog with the title Export to CSV, Type Feature, Priority P2, no Options selected, and a description whose Constraints say one file, index.html, no libraries, and an Export CSV button next to Add that downloads todos.csv.
The first ticket. The Constraints say what the change may touch.

And the second:

The New Ticket dialog with the title Add timestamp to Todos, Detected Feature, Type Feature, Priority P2, and a Constraints section asking for the time each task was added, in the row next to its text.
The second ticket. Both tickets change the same row of the page.

The board now shows both tickets in Open, each with a Start button and a needs acc pill, because neither has an acceptance file yet.

The project board with two Feature tickets in the Open column: Add timestamp to Todos and Export to CSV, each at P2 with a needs acc pill and a Start button. Create a Todo app is in Done.
Two tickets in Open. The closed ticket from the Quick start is in Done.

3. Put the second ticket in a worktree before you start it

Open the timestamp ticket. The Worktree panel has a row for the Main checkout (current), a greyed GitHub row (it sends a ticket to a Claude cloud session once GitHub is set up; see GitHub and cloud sessions) and a + New button with a branch name already filled in: sprint/t-tko0. Edit the name first if you want a different branch.

The timestamp ticket's tab before it starts: the Worktree panel with Main checkout (current) selected, a GitHub row, a + New button and the branch name sprint/t-tko0, and a terminal with Claude Code chosen and a Run sprint button.
The Worktree panel. + New creates the worktree; the branch name is filled in. Click to enlarge.

Click + New. Canon asks you to commit the ticket first, because a worktree only contains committed files.

The dialog Commit the ticket before creating the worktree. Required: .tickets/t-tko0/ticket.md, ticked. Also uncommitted, not included: .tickets/t-80kz/ticket.md. The commit message is chore: add ticket t-tko0. The buttons are Commit & create worktree and Cancel.
The ticket's own file is ticked. The other ticket's file is listed and never included. Click to enlarge.

The dialog reads: "A worktree only contains committed files, and t-tko0 isn't fully committed. Commit it on the main checkout first, then create the "sprint/t-tko0" worktree." The commit message is fixed, chore: add ticket t-tko0. Press Commit & create worktree. The panel then says Working in: sprint/t-tko0 and the + New button is greyed.

The worktree is a folder next to your project. It is named after the project with -worktrees added, here ToDo-Demo-worktrees, and holds one subfolder per branch. A / in the branch name becomes a -.

A file manager window at Documents, ToDo-Demo-worktrees, containing one folder, sprint-t-tko0.
The branch sprint/t-tko0 lives in ToDo-Demo-worktrees, in the folder sprint-t-tko0.

Choose your agent and press Run sprint. The session starts inside that folder: the pane header shows it, and the agent's first move is sprint start t-tko0.

The timestamp ticket's terminal: the pane header shows the worktree folder, Claude Code is running sprint start t-tko0, and the Worktree panel says Working in sprint/t-tko0 with the session listed in the Agents list.
The session runs in the worktree folder, not the main checkout. Click to enlarge.

The agent writes the ticket's plan and stops with a brief. Ours ended with a question about something the ticket left open: the app does not save todos across reloads, and the agent asked whether to add that. We typed approve, and the agent took that as "no". Read the plan, answer any question it asks, then approve.

The end of the timestamp agent's brief: the files, the approach, three criteria, a manual test plan and an open question about persistence, with the Ticket details pill reading Acceptance written.
The brief, with its open question. Approving answered it.
Check before you continue
  • The pane header shows the worktree folder, not your main project folder.
  • The Worktree panel names the branch you chose.

4. Start the first ticket in the main checkout, while the other one runs

Open the CSV ticket. This time no row is selected: the terminal says "Select a worktree above to continue — Run sprint is disabled until a row is selected." The panel lists the timestamp ticket's worktree under "1 worktree unavailable", because that ticket is using it. A red note says the ticket is not committed yet: "t-80kz isn't committed yet — a new worktree won't contain it. + New will offer to commit it first." That matters only for a worktree.

The CSV ticket's tab before it starts: the Worktree panel with Main checkout (current), a note that 1 worktree is unavailable, a GitHub row, + New with sprint/t-80kz, a red note that the ticket is not committed yet, and a terminal saying Select a worktree above to continue.
No row is selected, so Run sprint is disabled. Click to enlarge.

Click Main checkout (current), press Run sprint and approve the plan as before. Its pane header shows the main project folder. Now both agents are working, and both show in the Agents list.

The timestamp ticket's tab with the Agents list showing t-tko0 and t-80kz, both listed under ToDo-Demo, the Worktree panel for sprint/t-tko0 with a Change worktree link and an Unlock worktree button, and the agent's summary of its change.
Both agents running: one in the worktree, one in the main checkout. Click to enlarge.
Watch out

Admin says: "Idle sessions auto-save & end after 5m in a worktree and 30m in a project’s main checkout; any activity resets the timer, and a session that needs you is never ended." Its sessions table shows each session's countdown: ours read auto-save & end in 5m for the worktree and auto-save & end in 30m for the main checkout. The timer counts the agent's own terminal output as activity, so a session that is still printing is not idle. Answer your agents promptly all the same: our timestamp agent sat finished for about 8 minutes and was not ended, but we did not watch its timer and you should not count on that.

The Admin page's sessions table: t-tko0 Add timestamp to Todos in the worktree with the reaper reading auto-save and end in 5m, and t-80kz Export to CSV in the main checkout reading auto-save and end in 30m. Both are working.
Admin's sessions table, with each session's countdown.

5. Close both tickets they can close at the same time

Each agent builds its change and asks you to try it. Open the page yourself, add a couple of todos, tick one, and tell the agent what you saw. Ours was Looks good. All tested and works. The agent then asks you to confirm the close, and you answer yes. Two closes can run at once: the gates compare a snapshot of the repository before and after, and leave out any branch checked out in another worktree.

A close runs the reviewer first, which is advisory, then the evaluator, which is binding. Each runs as a subagent, and the sub figure in the pane header counts them (see the session header numbers in the Quick start).

The CSV ticket's terminal with the reviewer finished, the evaluator canon-evaluator running in the background, and the pane header reading 2 sub.
The reviewer has finished and the evaluator is grading. The header counts 2 sub.

The CSV ticket closed on the first run. Wrapup widened a guard in the CSV code, the reviewer said yes with nothing to act on, and the evaluator passed. The close report lists four commits on master, and then asks whether to push. Our project's origin is the project folder itself, so we answered No. Leave it local. Then we pressed End Session; for a closed ticket the dialog says there is nothing to save, as in the Quick start.

The CSV agent's close report: what shipped, the gates, four commits on master, a note that LEARNINGS.md has a new unpromoted row, and the question about pushing, answered No. Leave it local.
The close report for the CSV ticket, and our answer to the push question. Click to enlarge.

The timestamp ticket failed its first evaluator run. The time followed the browser's locale, and the agent reported that a browser set to British English would show 8:24 with no AM or PM, while the ticket's criterion said 12-hour. The agent stopped the close, reported that the failure count was 1 of the 3 allowed, and offered two fixes. We chose the one-line code change, forcing a 12-hour clock.

The timestamp agent's report that the evaluator gate failed on criterion 1, with the reason, two options (force 12-hour, or reword the criterion) and the reviewer's narrow-screen and contrast notes left as notes.
A failed gate stops the close. The agent lists the options. Click to enlarge.

The agent made the change, committed it and started a fresh evaluator on the new head. It passed. The close then stops again to say what it left undone: the close files were not committed yet, and nothing was pushed or merged.

The timestamp agent after its fix: a fresh evaluator re-grade of the new head running in the background, with the pane header counting 3 sub.
A fresh evaluator grades the new head. Click to enlarge.

We answered Commit the close files. Don't run the merge, I'll use Check & merge on the board. The agent committed them with Closes: t-tko0 in the body, and the tree was clean. Then we pressed End Session again.

The timestamp agent's close report: both gates, the failed first run and the fix, three open notes, and the commit of the close files with the working tree clean.
The close report for the worktree ticket. Click to enlarge.
Check before you continue
  • Read each close report. This is where a failed gate, a skipped check or a reviewer note shows up.
  • Answer the push question for your own project. Ours had no real remote, so we declined.
  • Both sessions are ended. Closing a ticket in a worktree means it closed on its branch. It does not mean the branch is merged.

6. Check & merge and what to do when it refuses

Both cards are now in Done, and the worktree ticket's card has a Check & merge button. Hover it: "Check sprint/t-tko0 and merge it into master here after your confirmation".

The board with three tickets in Done. The timestamp ticket's card has a Check & merge button and a tooltip reading Check sprint/t-tko0 and merge it into master here after your confirmation.
The Check & merge button on the worktree ticket's card.

Press it. Canon checks the branch before it merges anything, and it refuses, without changing anything, when the evaluator did not pass on the branch's head, when the worktree has uncommitted changes, when the branch is already in the default branch, when the default branch is checked out in another worktree, or when the merge conflicts. Ours conflicted.

The Check & merge dialog: sprint/t-tko0 does not merge into master here, conflicts in LEARNINGS.md, and the next steps: in the worktree run git merge master, resolve and commit, then tkt reopen the ticket and close it again so the evaluator grades the new head, then Check & merge. Nothing was run or changed.
The merge is refused, and the dialog says why and what to do. Click to enlarge.

The conflict was in LEARNINGS.md, not in index.html. Closing a sprint can write into that file: the learnings step adds a row and rewrites the learnings-sweep last run: line. Two tickets closed in different checkouts both changed it. The change to index.html merged cleanly.

The dialog names the way out, and it is a few commands in the Terminal, run inside the worktree:

cd ../ToDo-Demo-worktrees/sprint-t-tko0 git merge master cat LEARNINGS.md
The Terminal in the worktree folder: git merge master prints Auto-merging LEARNINGS.md, CONFLICT (content): Merge conflict in LEARNINGS.md, Auto-merging index.html, and Automatic merge failed. The prompt now shows the branch with MERGING.
git merge master. Only LEARNINGS.md conflicts. The prompt shows MERGING.

The file has two conflict blocks. The first is the last run line, with a different time on each side: keep the newer one only, or the file ends up with two such lines. The second is the table of rows, one row from each ticket: keep both.

LEARNINGS.md printed in the Terminal with conflict markers: a block around two learnings-sweep last run lines, and a block around the t-tko0 row and the t-80kz row.
Two conflict blocks: the last run line (keep the newer) and the rows (keep both).

We deleted the older line and the three kinds of marker line with one command. The date and time in it are ours: use the older of your two last run lines.

sed -i -e '/^learnings-sweep last run: 11-07-2026 14:30/d' -e '/^<<<<<<< /d;/^=======$/d;/^>>>>>>> /d' LEARNINGS.md cat LEARNINGS.md grep -c '^<<<<<<<\|^=======$\|^>>>>>>>' LEARNINGS.md
The Terminal after the fix: LEARNINGS.md shows one learnings-sweep last run line, and a table with the t-tko0, t-80kz and t-c662 rows. grep -c prints 0.
One last run line, three rows, no markers. grep prints 0.

Then commit the merge and reopen the ticket, so that the evaluator can grade the merged head:

git add LEARNINGS.md git commit --no-edit git status --short tkt reopen t-tko0
The Terminal: git add, git commit --no-edit printing Merge branch master into sprint/t-tko0, an empty git status, and tkt reopen t-tko0 printing t-tko0: open.
The merge commit, a clean tree, and the ticket reopened.

tkt reopen puts the ticket back in Open, with a Start button. Press it, check that the Worktree panel shows sprint/t-tko0, and press Run sprint. The agent runs sprint start on a ticket that is already built and closed, so say plainly what you want. We typed: Branch sprint/t-tko0 now has master merged in (045d314). Do not change any code. Run sprint complete so the merged head is graded.

The board with the t-tko0 card back in the Open column with a Start button, and the other two tickets in Done.
The reopened ticket is in Open again.
The agent after sprint start on the reopened ticket: it reports the ticket was already built and closed and nothing new was planned, lists three choices, and our reply asking it to run sprint complete without changing code.
The agent starts, reports what it found, and follows our instruction. Click to enlarge.

The agent did not ask for confirmation this time. It ran the reviewer and the evaluator on the merged head, and both passed. Its report says the time does not leak into the export, which still contains only task,done. It skipped the code-simplifier, security-review, doc-audit and mutation-test gates and said the first close had covered them.

The timestamp agent's second close report: the reviewer said yes, the evaluator passed after rendering the page in headless Chrome, the time does not appear in the CSV, a note about the evaluator's run-id timing, and the open notes.
The second close, on the merged head. Click to enlarge.

Commit the status change the same way, end the session, and press Check & merge again. With no test script in the project the button reads Merge (no tests) into master, and the log says the branch head is the graded head plus late docs only. Add a scripts/test.sh if you want the tests to run on the merged result first.

The Check & merge dialog ready to merge: the log says the head is graded-head plus late docs only, lists the files, 10 files changed, and ready: no test command. The buttons are Merge (no tests) into master and Cancel.
Ready: nothing from the branch runs until you press the button. Click to enlarge.

Press it. The dialog says Merged.

The Merged dialog: sprint/t-tko0 is merged into master here, Next: Finish pushes it to origin and resets the worktree, each after its own confirmation, with the merge commit and the buttons Finish and Close.
Merged into master. Finish comes next. Click to enlarge.

7. Finish push the default branch, reset the worktree

Finish… has two steps, each after its own confirmation. The first pushes the default branch to origin, and the dialog reads what origin already has first. In our run it printed finish: push: master is already on origin, because our origin is the project folder, so there was nothing to send. With a real remote, this is where the merge goes up.

The second step resets the worktree. It puts the worktree back at origin's default branch so the next ticket starts clean, and it refuses uncommitted work.

The Reset the worktree dialog: it puts the worktree back at origin's master so the next ticket starts clean, and refuses uncommitted work. The log says master is already on origin and the worktree is still on sprint/t-tko0. The buttons are Reset the worktree and Not now.
The reset dialog. Click to enlarge.

The result lists what the reset changed. It dropped no commits and changed no files. The worktree is not deleted: it keeps its folder and its branch name, now at the merge commit, ready for sprint start on the next ticket.

The reset result: sprint/t-tko0 now at the merge commit, the commits it drops (none), the files it changes (none), a notice that the stash and other worktrees are not touched, and that the worktree keeps its folder and branch.
The reset result. Nothing was dropped. The worktree stays for the next ticket. Click to enlarge.
Done

Both tickets are merged and the worktree is ready for the next one. All three tickets are in Done and no agents are running.

The project board with the side panel open: no agents running, the three tickets in Done, the recent commits starting with Merge branch sprint/t-tko0, and a Git badge reading 3 modified.
Everything landed on master. Click to enlarge.

Open the app from the main checkout. It now has the Export CSV button and the time on each todo, and the exported file has no times in it.

The ToDo app in a browser with an Export CSV button and two todos, one ticked, each with a time beside it, and an editor showing the exported file with the header task,done and two rows.
The merged result: the time on each todo, and the exported file.

The Git badge on the board says 3 modified. In our run they were .tickets/t-tko0/ticket.md, where canon recorded the merge, HANDOFF.md, and the ticket's session log, which is untracked.

git status --short git diff .tickets/t-tko0/ticket.md git log --oneline -6
The Terminal on master: git status --short lists ticket.md and HANDOFF.md as modified and cockpit-sessions.md as untracked, and git log shows the merge commit on top, then the close commits, the reopen commit and the merge of master into the branch.
The three files canon changed, and the log of the whole run.

To remove the worktree instead of reusing it, use git: git worktree remove on its folder, then git branch -d on its branch. We did not run those in this run.

For the red note about a ticket that is not committed yet, see Troubleshooting.