Skip to main content
A worktree is a second checkout of your git repository, on its own branch, where one task’s agent makes its changes. It keeps two tasks that work on the same repository from editing the same files at once. It leaves you a branch to review when the work is done. It also carries a few files that let a different runtime, or a person, pick the task up where it stopped. Clawboo makes a worktree only in a few cases, and a worktree is not a sandbox. This page covers when a task gets one, what is in it, how a handoff works, and how you get the work back.

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/run and a repoPath.
You can also create one ahead of time with 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.
In the task runner, the task’s kind decides too: 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.
Without a worktree, coding agents start in the task’s folder or the team’s folder. A run on a task with no worktree (in team chat, from the Board, or a research or review run) starts Claude Code, Codex, Hermes and Clawboo Native in the task’s own folder, teams/<team id>/tasks/<task id> in the work folder (~/clawboo-work by default); see Task folders. A turn that holds no task, such as the lead’s turn or your message in team chat, and an agent’s own chat start in the team’s folder, teams/<team id>, which every member of the team shares. A task or an agent with no team uses teams/_no-team. The work folder is outside Clawboo’s data folder, so ../.. from a team folder does not reach the database. The folder only sets where Claude Code, Codex and Hermes start: they run with their own approval prompts turned off, so they can still open any file your user account can by its full path, Clawboo’s database and saved keys in ~/.clawboo included. See What agents can 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, though git worktree list and git branch in your repository show the extra checkout and its branch.
  • Its own branch. The branch is clawboo/task-<task id>, cut from your repository’s current HEAD. 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.
A worktree keeps one task’s file changes apart from another’s. It does not limit what the agent’s process can do: the process runs with your user account’s permissions, and it can read files outside the checkout, reach the network and start other programs. What agents can do covers what each runtime can reach.

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 writes AGENT_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:
  1. Clawboo reads AGENT_HANDOFF.json, or task-progress.md when there is no handoff yet, and adds what is done, what is broken and the next step to the run’s prompt.
  2. TASK.md tells the agent to run ./init.sh to confirm the starting point, then carry on from the next step.
Picking the work up needs no chat history and no access to the board. That is what lets a task move from one runtime to another, for example from Claude Code to Codex, or to a person.
  • A run started through the API with keepForResume: true writes 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. Its runtime field can be human.
The Cross-runtime handoff guide walks through it step by step.

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.
Changes can still be uncommitted in the worktree folder when a run ends. Clawboo commits them to the branch when the verify command passes on a task-runner run, when a worktree is paused, and before a cleanup removes the folder. To see the work in the app, open the Computer tab on the agent’s page, or the Files section of the task on the Board, which shows the changed files and the diff. When a task runs again and its folder has to be rebuilt from the branch, Clawboo first checks that the folder holds nothing the rebuild would lose. A checkout that is still on the task branch with nothing uncommitted is kept as it is, along with files git ignores. Any other folder is never replaced if it holds uncommitted changes, files git ignores (an .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.
  • 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> and clawboo: save work before moving task <id> (before the move into the work folder).
  • PATCH /api/board/:taskId/workspace with { "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/workspace refuses a research or review kind with 422 no_isolation and isolation: '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, with 409 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: when VERIFICATION.md is 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.json cannot be read or parsed, or is a link, Clawboo treats it as missing and falls back to the ## Done and ## Blocked sections of task-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.
Last modified on November 14, 2026