Skip to main content
Use this recipe to start a code change on one runtime, for example Claude Code, pause it, and have another runtime, for example Codex, finish it in the same git checkout. The second runtime learns what is done and what is next from files in that checkout, not from a chat history. This is a developer recipe: you drive every step through the REST API.
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.
What you’ll build: one task, started by Claude Code with a pause at the end, then finished by Codex in the same checkout, with the result left on a branch for you to merge. Time: about 20 minutes, plus however long the two runs take.

Before you begin

  • Two of these runtimes connected: Clawboo Native, Claude Code, Codex, Hermes. OpenClaw cannot take part: /api/runtimes/openclaw/run answers 404 with unknown 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; clawboo prints the address it actually uses. Add the access cookie to each curl command, as shown under Authentication.
A worktree keeps a task’s file changes apart from your own checkout. It is not a sandbox. Claude Code and Codex run with their approval prompts turned off, Hermes asks only before the commands its own policy flags, and all three can read and change any file your user account can. See What agents can do.

How it works

Steps

1

Create the task without an assignee

The response holds the new task, in status 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

The request stays open until the run ends, which can take minutes. Keep it open, and call the server directly rather than through a proxy with a short timeout: closing the connection cancels the run and its process, and the task goes back to To do.What the fields do:
  • keepForResume: true (the boolean) makes the run pause at the end instead of finishing.
  • repoPath is the repository the worktree branches from. The run’s kind defaults to code, which needs it. Read-only research and review runs get no worktree.
  • assigneeAgentId becomes 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 (from GET /api/agents), or leave it out to use the runtime’s id. Only letters, digits, - and _ are allowed.
Clawboo claims the task and makes the worktree: a folder under ~/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)

The response has four parts: 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 taskId and repoPath to the other runtime, without keepForResume:
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 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 clawboo/task-<task-id> in your repository, and in the worktree folder:
Replace 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 in todo, and the workspace response shows resume.hasHandoff: true with lastRuntime set to claude-code.
  • After the second run, GET /api/board/<task-id>/executions lists a run by each runtime.
  • The task ends in done or blocked, and git -C /absolute/path/to/repo branch lists clawboo/task-<task-id> unless the run changed nothing.

Variations

Troubleshooting

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.
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.
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.
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.
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"}.
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

Last modified on November 14, 2026