The session about to hit its weekly limit is the single best-informed writer of the brief that lets a different vendor’s agent pick up the work. Spend the last of the allowance on that brief, not on one more edit.
Two Subscriptions, One Piece of Work
Most people doing this seriously now hold more than one agent subscription. A Claude Code plan with weekly limits, a Codex OAuth subscription sitting alongside it, maybe a Cursor seat from a previous month. These are separate meters. They reset on separate schedules. And the work in front of you does not care which one is paying.
The failure I kept hitting was treating the limit as the end of the work rather than the end of a shift. Claude Code would warn me that I was low on weekly usage, I would push a bit further, run out mid-task, and then either wait for the reset or start again somewhere else from a cold start. The restart is the expensive part. Not the tokens: the twenty minutes of re-explaining a codebase, a half-applied refactor, and three dead ends I had already ruled out.
The session that is about to run out knows more about the task than I do. It has the file paths, the failed approaches, the reason the obvious fix does not work, the exact command that reproduces the bug. That knowledge is sitting right there, one prompt away from being written down. So write it down while there is still allowance to write it.
Ask For the Handoff Out Loud
The whole technique is a prompt. There is no tool, no MCP server, no orchestration layer.
I'm running low on weekly usage. Write a handoff document to
docs/handoff-<task>.md for a fresh agent on a different provider
that has never seen this conversation.
Include: the goal and the definition of done; what is already
done and verified, with the commands that verified it; what is
in progress and exactly where it stopped; approaches I tried
that failed and why, so it doesn't retry them; the files that
matter and why each one matters; the next three concrete steps.
Assume it has the repo and nothing else. No summary of our chat.
Then commit that file, open Codex in the same repo, and point it at the document. It reads the brief, reads the files the brief names, and starts working. The meter that was empty is now irrelevant.
I have run this both directions. Codex to Claude Code when I want a harder review pass on something Codex drafted, Claude Code to Codex when the weekly window is nearly gone and the remaining work is mechanical. The handoff document is provider-agnostic by construction, because the receiving agent has no shared context to lean on. That constraint is what makes it good.
Why the Agent Writes a Better Handoff Than You Do
I used to write these myself. They were worse, for a reason worth naming: I remember the parts of a session I found interesting, and the agent remembers the parts that changed the code. Those overlap less than you would expect. Something like “the test helper mocks the clock, so anything time-dependent needs vi.setSystemTime or it flakes” is exactly the fact that unblocks the next agent and exactly the fact I would forget to mention, because I only learned it forty minutes ago through a failure I have already stopped thinking about.
There is a second reason. Writing the handoff is a compaction pass, and it happens to be the same discipline that keeps long single-vendor sessions alive. The trajectory that matters (objective, current truth, settled decisions, live failures, next move) is precisely what a cross-vendor brief has to carry, because nothing else survives the jump. If you already know why compaction is about trajectory rather than tokens, the handoff is the same operation performed deliberately and pointed at a stranger.
Where It Goes Wrong
Dumping the transcript is not a handoff. The tempting version of this is “summarise our conversation so far”, which produces a chronological narrative of an exploration, including every path that turned out to be irrelevant. The receiving agent reads all of it and inherits your dead ends as if they were context. Ask for a brief written for someone who has never seen the conversation, and ask for failed approaches to be listed as explicit exclusions rather than as history.
The handoff has to point at durable state. If the work only exists as unsaved edits and things the agent said, there is nothing for the document to reference. Commit first, even a scrappy wip: commit, so the brief can say “as of commit abc123” and mean it. This is why checkpoint commits are a prerequisite rather than a nice-to-have, and why a handoff pairs well with the goal file plus state file split on longer runs.
Verified and assumed are different categories. A handoff that says “auth flow now works” when what actually happened was “auth flow compiles” hands the next agent a false floor to build on. I ask explicitly for the commands that produced the evidence, so the receiving agent can re-run them cheaply and decide for itself.
The Adjacent Move: Schedule the Resume Instead
Handing off across vendors is one answer to a limit. A second is scheduling the resume on the same vendor for after the reset. They solve the same problem and I pick between them on one question: does the work need to move now?
If the task is on a deadline, or I want a second model’s read on it anyway, I hand off. If the reset is tonight and nothing is waiting on it, I schedule. The interesting thing is that both need the same artefact. A scheduled resume that starts from a fresh session and a Codex session that starts from a cold repo are the same situation, and the handoff document is what makes either one work. Write it once and you can choose your continuation strategy afterwards.
The Third Option: An Open Harness Removes the Seam
The handoff exists because of a seam. Claude Code is a closed harness pointed at one vendor, Codex is a closed harness pointed at another, and moving between them means moving between two programs that share nothing but the filesystem.
Open harnesses close that seam by design. pi.dev speaks to 15-plus providers, authenticates with OAuth as well as API keys, and lets you swap the model mid-session with /model, on top of tree-structured sessions you can branch from any earlier point. opencode reaches 75-plus providers through models.dev and logs in against a ChatGPT Plus or Pro account or a Copilot seat. In either one, hitting a weekly limit is a model swap and the context simply stays where it is. No document, no restart.
With pi the whole manoeuvre happens inside a running session:
# install once, then start on whichever meter still has room
curl -fsSL https://pi.dev/install.sh | sh
pi --model anthropic/claude-opus-5
# ... an hour of work later, the weekly allowance runs out.
# in the same session:
# /login OAuth against a subscription provider
# /model picker; choose an OpenAI model (Ctrl+S saves it as the default)
#
# the conversation, the file context, and the tool history stay where they were.
opencode is the same shape with different spellings:
curl -fsSL https://opencode.ai/install | bash
opencode -m anthropic/claude-sonnet-4-20250514
# /connect add credentials for another provider
# /models switch to it
# or pin the default in opencode.json: { "model": "opencode/gpt-5.1-codex" }
So why am I still writing handoff files? Because a harness tuned for one model family is not the same product as a harness tuned for none of them. Claude Code’s system prompt, tool descriptions, and defaults are co-designed with Claude, and Codex is co-designed with OpenAI’s models. Pi’s thesis is deliberately the opposite: four tools, a system prompt under a thousand tokens, and everything else opt-in through typed TypeScript extensions. That is a real trade of vendor tuning for control and portability, not a free upgrade.
I am currently thinking about moving to pi.dev for exactly that control. Even if I do, I expect to keep writing the brief. An open harness turns the handoff from a cross-tool problem into a within-session one, but it does not make durable state optional. A branched session, a cold return on Monday, and a colleague picking the task up all want the same file. Pi gives you the branch points and nothing else:
pi -c # continue the most recent session
pi -r # browse and pick an older one
# /tree jump back to any earlier turn and carry on from there
# /fork <id> branch a new session from a previous message
A branch that resumes from a vague memory of the work is as cold a start as a different vendor’s CLI. The tree tells you where you were. It does not tell you what was true.
The Actual Point
Weekly limits made agent capacity a resource I have to allocate rather than a tap I turn on. The instinct is to optimise consumption: cheaper models, tighter prompts, fewer tokens per task. That helps at the margin. The bigger win is making the work portable, so that hitting a limit costs you a file write instead of a restart.
Every subscription I hold is a separate pool of capacity. A handoff document is the pipe between them, and the agent will write it for me if I ask before the meter runs out.
