When a task gets a worktree
A task gets a worktree only when the task runner runs it with a repository path:- an agent routine whose task template names a
repoPath, which you set through the Schedules API; - a run started with
POST /api/runtimes/:id/runand arepoPath.
POST /api/board/:taskId/workspace. The task runner uses it when it later runs that task.
Everything else runs without a worktree:
- Team chat. Chats, hand-offs and the Board tasks a team works on never get one, on any runtime.
- Routines made in the dashboard. The Routines dialog has no repository field, so an agent routine made there runs as a research task, without a worktree.
- OpenClaw agents. They work in their own workspace, which the OpenClaw Gateway manages. Clawboo never gives them a worktree.
A task-runner run of a kind that needs a worktree, with no repository path, is refused rather than run somewhere else. The task gets the comment
[blocked: no isolation] This task changes files, so it needs an isolated git worktree, but no repository path was provided for it. and goes back to To do.
What a worktree is
- A separate checkout. It lives in the work folder, at
worktrees/<hash of the repository path>/<task id>. Your own checkout and its working files are not touched, thoughgit worktree listandgit branchin your repository show the extra checkout and its branch. - Its own branch. The branch is
clawboo/task-<task id>, cut from your repository’s currentHEAD. A caller that creates the worktree through the API can name another commit or ref. - A starting commit. Before the agent starts, Clawboo commits five bookkeeping files to the branch, with the message
clawboo: scaffold task <id>. The agent’s changes are measured from that commit, so the bookkeeping never counts as work.
The files in a worktree
Each file answers a question that a runtime picking the task up cold needs answered from the checkout alone:
Clawboo writes the first five when it creates the worktree.
AGENT_HANDOFF.json appears when the first run in it finishes successfully.
init.sh starts with placeholder commands that only print a reminder to set them. The verify command is the exception when the task’s team has a work check: init.sh starts with that command, and the verification check runs the team’s command in place of whatever init.sh says. Otherwise the agent, or you, has to replace the placeholder with a real command, and until it is set the verification check cannot pass the task. See Verification for when that check runs.
The cross-runtime handoff
When a task-runner run in a worktree finishes successfully, Clawboo writesAGENT_HANDOFF.json from the run’s report. It records who handed off and on which runtime, the run’s report (as what is done, or as the next step when the run pauses for another runtime), anything broken or unverified, and how to re-enter the work. If an earlier attempt on the task was interrupted, the handoff says so, so that the next runtime checks before it redoes anything with side effects.
The next run on that task, on any runtime, starts from the checkout alone:
- Clawboo reads
AGENT_HANDOFF.json, ortask-progress.mdwhen there is no handoff yet, and adds what is done, what is broken and the next step to the run’s prompt. TASK.mdtells the agent to run./init.shto confirm the starting point, then carry on from the next step.
- A run started through the API with
keepForResume: truewrites the handoff, keeps the worktree, and puts the task back in To do, ready for a different runtime to pick up. - The handoff also stores the runtime’s own session id. It is used only when the next run is on the same runtime, to resume that session. A different runtime works from the handoff alone.
- A person can write a handoff too, with
POST /api/board/:taskId/workspace/handoff. Itsruntimefield can behuman.
Getting the work back
Clawboo never merges. When a run in a worktree finishes, what happens next depends on whether it changed anything besides the bookkeeping files:- It changed files. The worktree and the
clawboo/task-<id>branch are kept, and the task goes to verification. Review the work and merge it into your own branch yourself. - It changed nothing. The worktree and its branch are removed, and the task lands Done without a verification check.
.env file or build output, for example), a commit no branch holds, a separate git repository, or anything git cannot read. The run does not start, and the task waits in Needs you with a comment that starts [blocked: worktree kept] and names the folder. Commit or copy what you need from it, or remove it, then move the task back to To do. If git does not answer when Clawboo checks the folder, the run does not start either: nothing is changed, and the task goes back to To do with a [not started: worktree unchecked] comment.
Cleanup
When the Clawboo server starts, it removes worktree folders that are older than 72 hours, or beyond the newest 25 for a repository. Tasks that are in progress or in review are skipped. Before removing a folder, Clawboo commits any uncommitted work to the branch. Files git ignores, such as.env files and node_modules, are never committed, so they are removed with the folder; copy out anything you need before a task’s worktree sits unused for 72 hours. A folder git does not list as a worktree is removed only when it holds nothing. A folder git cannot be asked about, because git worktree list failed, is always kept, and so is a separate repository or a checkout whose commit no branch holds. In the work folder, the cleanup removes only checkouts this install’s board records or that carry its .<task id>.owner marker, so a work folder two installs share is safe. The branch itself is kept, so the committed work is not lost: if the task runs again, Clawboo rebuilds the checkout from the branch.
Branches are never deleted by cleanup. Delete the clawboo/task-<id> branches you no longer need with git.
A task’s own folder, where a task with no worktree runs, has no branch to keep its work, so the cleanup at start removes it only when it is empty and the task is finished. See Task folders.
Under the hood
Under the hood
- Clawboo’s commits on a task branch use the messages
clawboo: scaffold task <id>,clawboo: checkpoint task <id>(after the verify command passes, before the reviewer),clawboo: pause task <id>,clawboo: gc autosave task <id>andclawboo: save work before moving task <id>(before the move into the work folder). PATCH /api/board/:taskId/workspacewith{ "action": "pause" }commits the work, removes the folder and keeps the branch.{ "action": "complete" }runs the empty-or-changed decision above and, for changed work, the verify command without the reviewer.POST /api/board/:taskId/workspacerefuses aresearchorreviewkind with422 no_isolationandisolation: 'folder', since those kinds run in the task’s own folder, and a folder at the task’s path that holds uncommitted changes, or that git cannot read, with409 unsafe_to_rebuild.- The reviewer works in a detached checkout at the committed work, under
reviews/<install>/<hash>/<short sha>in the work folder, where<install>is a folder of this install’s own. The checkout has no branch of its own. - Clawboo reads and writes the task files at the top of a checkout or team folder (
AGENT_HANDOFF.json,init.sh,task-progress.md,VERIFICATION.md) without following a link or a hard link an agent put there. A linked file reads as missing, and a write replaces the name instead of writing through it. The verification check’s evidence is the one exception that adds to a file rather than replacing it: whenVERIFICATION.mdis a link or a hard link, the check leaves it as it is and skips the evidence, and its verdict on the task stands. - If
AGENT_HANDOFF.jsoncannot be read or parsed, or is a link, Clawboo treats it as missing and falls back to the## Doneand## Blockedsections oftask-progress.md. - Every git call Clawboo makes has a 60-second timeout.
- The lifecycle functions are documented in @clawboo/worktrees, and the run loop in Executor runner.
Related
- What agents can do: what each runtime can reach, with or without a worktree.
- Verification: when finished work is checked, and what a failing check does.
- Cross-runtime handoff guide: pause a task on one runtime and resume it on another.
- How routines run: why routines made in the dashboard get no worktree.
- Board API: the
/api/board/:taskId/workspaceroutes.