Skip to main content

Hand off from Claude Code to Codex at a usage limit

You end with Codex running the next task from the ledger, and the ledger shows who handed off, who picked up and who finished.

  • SpecWeave CLI
  • 1:18
  • Claude Code and Codex
  • Narrated, with captions

Recorded on SpecWeave 3.1.0, 18 October 2026, added 18 October 2026.

Before you start: Node.js 20.12 or later and git; SpecWeave installed with npm i -g specweave and a repo set up with specweave init; an increment whose spec.md lists tasks with their Files and Test.

Length 1:18Captions

Steps

  1. Turn on the usage guard once with specweave auto-handoff on. In the default suggest mode, the first time a session reaches 95% of a usage window it tells you a handoff is available and keeps working; nothing is said when every full window resets within 30 minutes.
  2. When you decide to move, tell Claude Code to hand off. It runs specweave handoff --reason "usage at 95% of the 5-hour limit", which releases its task claims and writes handoff.md and handoff.diff in the increment folder. With a Git remote it also pushes, so another machine can pick up.
  3. Read handoff.md: who stopped and why, which tasks are done with their evidence, the uncommitted files with the full diff beside it, and the exact next step.
  4. Open Codex in the same repo and say "pick up". Codex runs specweave pickup, which prints the next task with its acceptance criteria, files and test, and records a pickup line in ledger.jsonl.
  5. Codex claims the task with specweave task claim T-02 and makes the change.
  6. Codex runs specweave task done T-02 --run "npm test". The test runs again; the task is marked done only when it exits 0, and the ledger records who finished it, as codex@<host> (codex@demo in the recording), with the test output as evidence.
  7. Then run specweave verify to check the increment before you close it with specweave complete.

Transcript

Built from the caption file of the narration.

0:00 What you will do

Hand off from Claude Code to Codex at a usage limit.

0:05 The usage limit warning

With specweave auto-handoff on, Claude Code sends its usage to SpecWeave. Here we pass in a sample reading of 95% of the 5-hour limit. The guard says a handoff is available, and work continues.

0:19 specweave handoff --reason

When you are ready, tell Claude to hand off. It runs specweave handoff with a reason, releases its claim on T-02, and writes handoff.md.

0:29 What handoff.md carries

handoff.md says who stopped and why, and which tasks are done. It lists the uncommitted files, with the full diff beside it, and the exact next step.

0:40 specweave pickup in Codex

Now open Codex in the same repo and say "pick up". It runs specweave pickup, which reads the handoff and records the pickup in the ledger as codex@demo.

0:51 The next task and its acceptance criteria

Pickup names the next task, T-02, with its acceptance criterion, its files and its test. Codex claims it.

1:00 task done --run

With the change in place, task done --run runs the test again. Only a passing test marks the task done, and the ledger shows that Codex finished it.

1:11 Next: verify

Next, specweave verify checks the increment before you close it.

Read the handoff guide

Learning path

Run work across agents

Plan an increment, prove each task, hand off between tools and get a review from another model.

  1. Plan, prove and hand off a task with the CLI

    1:00, SpecWeave CLI

  2. Install SpecWeave and plan your first increment

    1:36, SpecWeave CLI

  3. Claim, prove, verify and complete a task

    1:30, SpecWeave CLI

  4. Hand off from Claude Code to Codex at a usage limit (this guide)

    1:18, SpecWeave CLI

  5. Review with the other model before you ship

    1:33, SpecWeave CLI

All tutorials