A handoff needs a git worktree, a separate checkout Clawboo makes for one task. A run gets one only when it is started with
POST /api/runtimes/:id/run and a repoPath, or by an agent routine whose task template names a repoPath (set through the API; the routine dialog has no repository field). Team chat, rooms, delegations and tasks you start from the board never get a worktree, so they never write a handoff.Before you begin
- Two of these runtimes connected: Clawboo Native, Claude Code, Codex, Hermes. OpenClaw cannot take part:
/api/runtimes/openclaw/runanswers404withunknown runtime 'openclaw'. See Providers and runtimes. - A git repository on this computer with at least one commit, and its absolute path.
- The server address. The examples use
http://127.0.0.1:18790;clawbooprints the address it actually uses. Add the access cookie to eachcurlcommand, as shown under Authentication.
How it works
Steps
1
Create the task without an assignee
todo. Keep its id.Leave out assigneeAgentId. A task created for an agent goes straight to the team’s chat engine, which runs it without a worktree, and your run in the next step then gets a 409. The teamId is optional (GET /api/teams lists your teams’ ids): with it, the task shows on that team’s board and its spend counts toward the team’s budget.2
Start the task on the first runtime
keepForResume: true(the boolean) makes the run pause at the end instead of finishing.repoPathis the repository the worktree branches from. The run’skinddefaults tocode, which needs it. Read-onlyresearchandreviewruns get no worktree.assigneeAgentIdbecomes the run’s identity. Memory and the board credit the work to it, and Clawboo Native, Codex and Hermes keep a home folder per identity. Use the id of an agent on the task’s team (fromGET /api/agents), or leave it out to use the runtime’s id. Only letters, digits,-and_are allowed.
~/clawboo-work/worktrees/ on a new branch, clawboo/task-<task-id>, in your repository. The agent works there. At the end, Clawboo writes AGENT_HANDOFF.json into the worktree, with the agent’s summary as the next step, and puts the task back in To do. The worktree stays, and no check runs on a pause.You should get a 200 whose JSON includes "ok": true, "status": "todo", "usedWorktree": true and the agent’s summary.3
Read the handoff (optional)
ok, workspace (including worktreePath, the folder, and branch), resume (what the next runtime will read: done, broken, next, and lastRuntime), and handoff (the parsed AGENT_HANDOFF.json). The handoff is structured data, so the next runtime reads fields rather than prose.4
Finish the task on the second runtime
Send the same Clawboo finds the task’s worktree and reuses it. If the folder was removed by a cleanup, Clawboo rebuilds it from the branch, which is why the second run needs
taskId and repoPath to the other runtime, without keepForResume:repoPath too. Codex starts from the handoff: what is done, what is broken, and what to do next.5
Let the check decide where the task lands
When the second run ends, Clawboo compares the worktree with its starting point:
The request returns once that is settled. Unless the task’s team has a work check, the worktree starts with a placeholder verify command, and a placeholder counts as a failed check, which is why the task description in step 1 asks the agent to set
VERIFY_CMD. With a work check, the check runs the team’s command instead, whatever init.sh says. See How work is checked.6
Review and merge the work
Clawboo never merges or pushes. The work stays on the branch Replace
clawboo/task-<task-id> in your repository, and in the worktree folder:main with the branch you started from. An agent may leave its changes uncommitted in the worktree folder. Clawboo commits them once the verify command passes, when you pause the workspace, and before a cleanup removes the folder. If the branch shows nothing new, look in the folder from workspace.worktreePath.Check that it worked
- After the first run,
GET /api/board/<task-id>shows the task intodo, and the workspace response showsresume.hasHandoff: truewithlastRuntimeset toclaude-code. - After the second run,
GET /api/board/<task-id>/executionslists a run by each runtime. - The task ends in
doneorblocked, andgit -C /absolute/path/to/repo branchlistsclawboo/task-<task-id>unless the run changed nothing.
Variations
Troubleshooting
The run answers 409
The run answers 409
What it means: Clawboo could not claim the task. It is not in To do, it already has an assignee (for example because you created it with
assigneeAgentId), or you closed the connection before the claim.Fix: check the task with GET /api/board/<task-id>. Do not retry in a loop. To run a task that is assigned or Blocked, move it back to To do first with PATCH /api/board/<task-id> and {"status":"todo"}, which also clears the assignee.The run answers 422 and the task has a [blocked: no isolation] comment
The run answers 422 and the task has a [blocked: no isolation] comment
What it means: the run changes files, so it needs a worktree, and Clawboo could not make one. The comment reads “This task changes files, so it needs an isolated git worktree, but no repository path was provided for it.” when
repoPath is missing, or names the path when Clawboo could not create the worktree there. The task goes back to To do.Fix: pass repoPath with the absolute path of a git repository that has at least one commit. For read-only work, send "kind":"research" or "kind":"review" instead.The run answers 404 unknown runtime 'openclaw'
The run answers 404 unknown runtime 'openclaw'
What it means: OpenClaw agents cannot be run this way. The run route accepts
clawboo-native, claude-code, codex and hermes.Fix: use one of those runtimes.curl seems to hang
curl seems to hang
What it means: the run is still going. The request returns only when the run ends.Fix: leave it open. If you stop it, Clawboo cancels the run, and the task goes back to To do with the worktree kept.
The first run finished instead of pausing
The first run finished instead of pausing
What it means: the run body did not carry
"keepForResume": true as a boolean, so the run went on to the check.Fix: send true, not "true". A task that reached Done cannot be reopened, so create a new task for the rest of the work. A Blocked task can go back to To do with PATCH /api/board/<task-id> and {"status":"todo"}.The task ended Blocked
The task ended Blocked
What it means: the check failed on every attempt. A placeholder verify command in
init.sh always fails.Fix: read the task’s comments with GET /api/board/<task-id> to see what failed. Set VERIFY_CMD in the worktree’s init.sh, move the task back to To do, and run it again with the same repoPath.Next steps
- Worktrees and handoff: the files in a task’s worktree and what each one is for.
- How work is checked: the verify command, the review run, and when a task lands Blocked.
- Runtimes API: every field and status of
POST /api/runtimes/:id/run. - Board API: the task and workspace routes used here.
- Mix runtimes on one team: put agents on different runtimes in team chat.