Claude Code Hit Its Usage Limit Mid-Task. Hand the Same Worktree to Codex in 4 Commands

• Book: Prompt Engineering Pocket Guide
• The series: Pocket Guides for Developers — 8 short books on agents, RAG, prompts, observability, events, databases and system design — the whole series
• My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
• Me: xgabriel.com | GitHub

Claude Code is three files into a refactor when it shows "Usage limit reached · wrapping up." Anthropic's help article on Pro and Max plans explains what that means: you hit a usage limit mid-response (the five-hour session limit or the weekly one), so Claude may finish the step it is on. The wrap-up covers only that response, and Anthropic says it is rolling out gradually. It doesn't extend to new messages; to keep going before the reset, the article lists upgrading, usage credits or a Console account.

So you have a half-done branch with two red tests, and the plan for the rest lives in a conversation you can't continue until the limit resets. If you also have Codex set up, you can hand it the same worktree and keep going. It takes four commands, and the last two are the ones that tell you whether the handoff worked.

What crosses over, and what stays behind

Everything git can see crosses over. Codex starts in the same folder, so it also gets your .env and node_modules, which Claude Code was already using. That is the reason to hand over the same worktree instead of starting a fresh one. A new worktree holds only tracked files, so your ignored files would have to be copied over first.

Three things stay behind.

• The conversation. Codex doesn't start with anything Claude said. The plan for the next step, the dead end Claude already tried, the reason a test is red on purpose: all of it is gone unless you write it down.
• Claude's auto memory. Claude Code keeps notes it writes itself per repository, shared across worktrees. They belong to Claude. Codex doesn't read them.
• CLAUDE.md. Codex reads AGENTS.md from the project root down to the folder it runs in, plus any fallback names you list in project_doc_fallback_filenames. Filenames not on that list are ignored. A repo whose rules live only in CLAUDE.md gives Codex none of the project's rules.

Fix the last one once, before you ever need it. Move your build command, test command and house rules into AGENTS.md, and put one line at the top of CLAUDE.md so Claude Code imports the same file:

@AGENTS.md

The conversation and Claude's memory are what the handoff file replaces. Git already records what was done and the script below captures the test state, so the next step is the one line only you have to write.

The conversation stays with the first agent. The branch and a written note are what get passed on.

One-time setup: the handoff script

Save this as handoff.sh somewhere on your PATH, outside the repo, and make it executable with chmod +x. It prints Markdown, so you redirect it into a file:

#!/bin/sh
# usage: handoff.sh "next step" [base] > HANDOFF.md
next="$1"
base="${2:-main}"
tests="${TEST_CMD:-npm test}"

echo "# Handoff: $(git branch --show-current)"
echo
echo "## Next step"
echo "$next"
echo
echo "## Commits since $base"
git log --oneline "$base"..HEAD
echo
echo "## Files changed since $base"
git diff --stat "$base"...HEAD
echo
echo "## TODOs added on this branch"
git diff "$base"...HEAD | grep '^+.*TODO' \
  || echo "(none)"
echo
echo "## Tests at handoff: $tests"
sh -c "$tests" 2>&1 | tail -n 30 | sed 's/^/    /'
echo
echo "Rules are in AGENTS.md. Run the tests first."

A few choices in there are deliberate. git log uses two dots, so it lists only the commits on your branch. git diff uses three dots, so it compares against the point where the branch split from main and ignores whatever landed on main since. The TODO grep reads only lines this branch added, so the old TODOs in the codebase stay out of it. The test output is indented four spaces, which makes it a code block in Markdown without nesting fences. Set TEST_CMD="pytest -q" (or whatever your project runs) when it isn't npm test.

The script runs the tests itself, on your machine, before any agent touches the branch again. That output is the baseline the fourth command checks against.

Then keep HANDOFF.md out of your commits for good:

echo HANDOFF.md >> "$(git rev-parse --git-path info/exclude)"

info/exclude is the place for ignore patterns that are specific to one person's workflow and shouldn't be shared. In a linked worktree you can't guess where git keeps it, which is why the git-worktree docs tell you to resolve paths like this one with git rev-parse --git-path. It lives in the shared git directory, so one line covers every worktree of the repo.

The four commands

Let Claude Code finish its wrap-up. If the last thing it printed was a plan, /copy puts its latest reply on your clipboard, and that is your "next step" line. Then leave the session with /exit, so nothing is still writing files while you commit.

1. Checkpoint the work. Look at git status --short first. git add -A stages everything git doesn't ignore, so make sure .env is covered by .gitignore before you rely on it.

git add -A && git commit --no-verify -m "wip: handoff"

--no-verify skips the pre-commit and commit-msg hooks. Half-done code often fails a lint hook, and this commit is a checkpoint you'll squash before the pull request. It also skips any secret-scanning hook, so read git status --short and the staged diff before you commit. Your real commit still goes through the hooks.

2. Write the handoff.

handoff.sh "Add the refund route and its test" > HANDOFF.md

Read the file once. Thirty seconds here is cheaper than a confused Codex turn.

3. Start Codex on it. Interactive codex takes an optional first prompt, and -s and -a set the sandbox and the approval policy (CLI reference):

codex -s workspace-write -a on-request \
  "Read HANDOFF.md. Run the test command it names,
compare with 'Tests at handoff', report, then stop.
Do not edit files until I say go."

4. Check that nothing moved.

git status --short

Check the pickup before Codex edits anything

Command 3 makes Codex prove it is looking at the same branch you are, and command 4 confirms it got there without changing anything.

Compare Codex's report with the "Tests at handoff" block. Same failures, same counts: that's your signal Codex is in the right folder, on the right commit, with the same dependencies and environment. Tell it to go ahead with the next step.

Different results mean something in the environment is off, and you want to know before any edit. Usually it's one of these:

• Codex's sandbox. The workspace-write mode keeps network access off by default, so a test that reaches a database or an API can fail under Codex and pass in your shell. Start Codex with -c 'sandbox_workspace_write.network_access=true' if your tests need the network.
• Codex started in another folder. Run it from the worktree root, or pass -C with the path.
• Something only Claude's shell had, like an exported variable or a running database container.
• A test that depends on time or order. Run it twice yourself before you blame the handoff.

git status --short should print nothing, because HANDOFF.md is excluded and Codex was told not to edit. If it lists files, read the diff before you continue. Test runs that write untracked artifacts show up here too, and that's a .gitignore fix you'll want anyway.

When your Claude window resets, the handoff runs the other way. Checkpoint again with command 1, so whatever Codex changed is in a commit handoff.sh can read. Then run handoff.sh and claude -c in the same folder. It loads the most recent conversation in that directory, so Claude has its old context back. Tell it Codex worked on the branch since its last turn and point it at HANDOFF.md.

The same handoff in Hermes IDE

I build Hermes IDE, so weigh this section with that in mind.

Hermes starts each task on its own hermes/<name> branch in its own worktree, and you pick the agent, model, effort and account per task in the ⌘N launcher (Ctrl+Shift+N on Windows and Linux). The README lists the case this post is about: when one agent hits its usage limit, you can continue the task in another. It also supports several accounts per agent.

The ⌘N New task sheet with its agent picker open: Claude Code (installed) selected, Codex installed, and the other supported agents marked Not installed.

Because every task already lives on its own branch and worktree, and every agent turn is saved so you can diff or restore it, the git bookkeeping in this post is mostly done before the limit hits. Each agent runs its own interface in a real terminal, so Claude's conversation stays with Claude Code. What Codex gets is the branch and whatever you wrote down, so the AGENTS.md and HANDOFF.md habits above are worth keeping inside Hermes too. Hermes never types into an agent's terminal on its own, so Codex gets its first prompt from you.

Codex and Claude Code side by side, each in its own hermes/ worktree, with the sidebar showing each session's status, context use, cost and branch.

The sidebar also shows each session's spend, as the agent reports it or as an estimate marked as one. The current release is 2.3.4, published October 15 (releases). It is free to download, source-available under BSL 1.1, runs on macOS, Windows and Linux, and isn't affiliated with Nous Research, Anthropic, OpenAI or any agent vendor. Everything above works in plain terminals too.

When to wait instead

A handoff isn't free. Codex makes different calls than Claude, and a branch with two agents' styles in it takes longer to review. If the reset is less than an hour away, or the next step is a delicate one that depends on reasoning Claude never wrote down, waiting is often the better choice. On a work repo, check that your team allows the code to go to both vendors before you hand it over.

It also isn't the only exit. The paid options in the help article from the top of this post still apply. For why a team might want a second vendor ready in the first place, I made that argument here.

Move your rules into AGENTS.md and save handoff.sh today, while Claude still has quota.

If this was useful

HANDOFF.md is a prompt, just one assembled from git instead of typed from memory, and the rules in AGENTS.md are context engineering by another name. The Prompt Engineering Pocket Guide covers how to write both so a model that has never seen your repo gets it right on the first turn. It's one of 8 short books in Pocket Guides for Developers, covering agents, RAG, prompts, observability, events, databases and system design. If you run Claude Code and Codex on the same repo, Hermes IDE is free, and a star on GitHub helps other developers find it.