Skip to main content
@clawboo/worktrees gives a file-changing task its own git worktree and branch, writes the working files any runtime can resume the task from, and records a structured handoff when a run ends. It is server-only, because it runs git and writes files. The board decides what runs; this package is only the git and file mechanism, and the database bookkeeping (the task’s workspaces row) lives in apps/web/server/lib/worktrees.ts. Use this page when you change how task runs are isolated, paused, resumed or cleaned up. The model behind it is on Worktrees and handoff. A worktree keeps parallel teammates’ file changes apart, but it is not a sandbox: see What agents can do.

When a task gets a worktree

isolationForTask(kind) returns folder for research and review tasks and worktree for code and any unknown kind; it never returns container. The IsolationLevel type is 'folder' | 'worktree' | 'container'. folder means no worktree: the server runs the task in its own plain folder, <team folder>/tasks/<task id>, which this package does not make. Worktrees are made by the task runner (a run of POST /api/runtimes/<id>/run, or an agent routine that names a repository) and by POST /api/board/<taskId>/workspace; team chat never makes one. The task runner refuses a file-changing task with no repository path (workspace_unavailable) rather than run it without isolation; see The executor runner. The package’s default root is <repo>/.clawboo/worktrees, but the server always passes its own: task worktrees live at <work folder>/worktrees/<hash of the repo path>/<task id> and review checkouts under <work folder>/reviews/, so nothing is created inside your repository (see The work folder). Each task gets the branch clawboo/task-<task id>. The server also acts on a task worktree the board records under <clawboo home>/worktrees/, where older versions made them, and on one the work folder move kept at its old place.

The lifecycle

Clawboo never merges a task branch; finished work waits on clawboo/task-<task id>.

The working files

SOR_FILES names the system-of-record files, which any runtime (or a person) reads to pick a task up cold: writeScaffold writes the first five. reconstructState(path) rebuilds what is done, what is broken and what comes next from the handoff (falling back to task-progress.md) and init.sh, with no access to chat or the board, which is what lets a different runtime resume the task. The agent owns the folder these files sit in, so it could swap one for a link, or a hard link, to a file the server can open, such as its database. readHandoff, writeHandoff and reconstructState therefore never follow one, and the server uses the same helpers for VERIFICATION.md:
  • readTaskFile(dir, name, maxBytes?) returns the text of name directly under dir. It opens the file without following a link and throws unless it is a regular file with no other name and at most maxBytes (TASK_FILE_MAX_BYTES, 1 MiB, by default). readHandoff reads a refused file as missing.
  • replaceTaskFile(dir, name, content) writes a new file and renames it over the name, so a link at the name is replaced, never written through.
  • appendTaskFile(dir, name, content) appends to the file, creating it when missing, and refuses a link, a hard link or anything but a regular file.
  • UnsafeTaskFileError is what they throw for a refused file (its filePath names it). Nothing was read or written. The scaffold’s VERIFY_CMD is a placeholder, and TASK.md’s steps tell the agent to set it: until the agent sets a real command, the verification gate reports that no verify command is configured and the attempt fails.

Path safety

These functions remove folders recursively and run commands, so every path they act on is checked first:
  • Task ids are one path segment. assertSafeTaskId accepts only ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$ and throws for anything else rather than rewriting it. branchNameForTask, worktreePathFor and the lifecycle functions all go through it.
  • Worktree folders stay under the root. worktreePathFor(repo, taskId, rootDir) resolves the task’s worktree folder and throws if it would land anywhere but one segment below the root.
  • Removal rebuilds the path. Before their recursive remove, pauseWorktree and completeWorktree rebuild the folder from the root and the task id, and throw if the stored record points somewhere else. rootDir may be a list of roots, and then the record has to be the task’s worktree folder under one of them; an empty list refuses every record. The server passes the work folder’s root, the state folder’s, and any root the work folder move kept a checkout under.
  • A replace never loses work. Resume and a provision’s clean-up of leftovers delete a task’s worktree folder only when it is missing, empty, or a checkout of the task’s repository at a commit a branch holds, with nothing in git status --ignored. Anything else throws UnsafeWorktreeError and the folder is left exactly as it was: uncommitted changes, files git ignores (an .env, build output), a detached commit no branch holds, a separate repository (its own .git, whose commits would go with it), or a folder git cannot read.
  • GC goes by registration. For a checkout git lists, GC commits any uncommitted changes to its branch, then removes the folder; files git ignores are not committed and go with it. It skips a listed checkout that is a separate repository, has its commit on no branch, or has changes on a detached HEAD. A folder git does not list is removed only under the rule above, and a folder whose registration git could not report is always kept. With owns, GC leaves alone, and does not count, any folder the callback rejects; the server passes it for the work folder’s roots and accepts only checkouts its board records there or that carry this install’s .<task id>.owner marker, so two installs can share a work folder.
  • Review checkouts stay in the review folder. removeReviewWorktree(repo, worktree, rootDir) throws before it removes anything unless the record’s path is exactly one segment below the review root (rootDir, else <repo>/.clawboo/reviews). Pass the rootDir the checkout was provisioned with. provisionReviewWorktree checks its own path the same way. Its repoPath may be a bare repository, such as the history the server keeps of a team folder (see How work is checked).
  • Verify commands run in Clawboo’s folders only. The server’s verification gate runs VERIFY_CMD only in a task or review checkout or a team folder under the work folder’s worktrees/, reviews/ and teams/, in a folder under Clawboo’s state folder (older layouts), or in a checkout the work folder move kept at its old place. It refuses anything else, including the work folder itself, its other folders, and a link whose real path leaves those places, before it runs the command in that real path.

Helpers you will reach for

  • KeyedMutex. mutex.run(key, fn, { acquireTimeoutMs }) serializes work per key and throws MutexAcquireTimeoutError when the wait runs out. The lifecycle functions lock per worktree path, the task runner locks each agent’s persistent home (the wait is CLAWBOO_HOME_MUTEX_ACQUIRE_MS), and the OpenClaw routine dispatcher locks per agent.
  • execGit(cwd, args). Runs git with a timeout and an output cap and throws GitError with the command’s stderr and args. The Computer tab’s git status and file diffs use it.
  • Diffs. diffStat and worktreeDiff compare a worktree with its baseline, and isDetached confirms a review checkout has no branch.
  • Registration. worktreeRegistration(repo, path) answers registered, unregistered, or unknown when git worktree list itself failed. isWorktreeRegistered is the yes-or-no form, with unknown as no; anything that removes a folder on the answer uses the three-way form.

Who uses it

Only the server: the task runner, the board’s workspace routes, the verification gate and critic, the Routines dispatchers, and the Computer tab’s file view. Agent chat and team chat import only MutexAcquireTimeoutError, to recognise a busy agent home.

Test it

Run pnpm --filter @clawboo/worktrees test. The suite creates real git repositories in temporary folders, so it needs git on your PATH; CI also runs it on Windows and macOS.
Last modified on November 14, 2026