Help/Recipes/Switching between agents

Hand off to another agent

Or to yourself next week.

For: Anyone stopping mid-task: switching from Claude Code to Codex, ending the day, or passing work to a teammate
When: The last five minutes of a session
Takes: About two minutes of agent time
You get: One handoff document with where things stand, the decisions made, what needs you, and a next step any agent can run

Agents forget everything when a session ends, and each tool keeps its own history. A handoff in onecell is the part that survives: the next agent, in any tool, reads it and carries on. Pair it with Recipe: resume where I left off.

The prompt

Not connected yet? Set up your AI Run in Claude Run in ChatGPT

Hand this work off through onecell, so another agent, or me next week,
can pick it up cold. Save it to <cell> (default: my Inbox).

1. Look first: search onecell for an earlier handoff or parked session on
   this work. If there is one, update it with get_document and
   update_document (pass expected_version) instead of starting a new one.

2. Write "Handoff: <topic>" with create_document (dry run first):
   - Where things stand: a short paragraph, then a checklist of what is
     done and what is left
   - Decisions made in this session as decision blocks, with the context
     and the reasoning. Mark one accepted only if I agreed to it;
     otherwise leave it proposed
   - Open questions for me, as a checklist
   - Where the work lives: repo, branch, files, documents and links
   - Gotchas: anything that cost time and would cost the next agent time
   - The next step, as a prompt block the next agent can run as it is

3. Remember only facts that outlast this task (entity: the project).
   Call recall first; if one conflicts, tell me instead of replacing it.

4. Reply with the link and a one-line prompt to resume from it.

What your agent does

Looks for an earlier handoff
search finds any handoff or parked session on the same work. If one exists, the agent updates it, so each piece of work has one record.
Writes the state of the work
A paragraph and a done-and-left checklist, the decisions made, open questions, where everything lives, gotchas, and the next step.
Records decisions as decision blocks
They show up in list_decisions, so a teammate or a Monday sweep finds what was decided, and what still waits on you.
Keeps memory for what lasts
Facts that outlive the task become remembered facts. Session detail stays in the handoff.
Gives you the way back in
A link and a one-line prompt to resume from it, in any agent.

What you get back

Open the full example →

A handoff for Tally, a made-up invoicing app, written at the end of a session mid-way through a fix. The gotchas are what save the next agent an hour.

Sample handoff: moving invoice reminders to the job queue

Where it stands

Reminders used to be sent by a cron script. After they went out twice on 14 August, we are moving them onto the job queue so each reminder is sent exactly once. The queue job is written and tested; the old cron script still runs in production.

Done: 3 of 5; steps in the plan
Branch: reminders-queue; 2 commits ahead of main
Tests: 41 passing; none skipped

Decided

Each reminder gets a unique key (invoice + reminder number), so a retry can never send it twice.
The cron script is switched off only after the queue has run in production for two days alongside it, in dry-run mode.

Open questions

Should a reminder that misses its 8am–8pm window wait until the next morning, or be skipped?
Do we need a backfill for reminders lost during the switch?

Gotchas

The worker reads time zones from the client, not the freelancer. The tests cover both; don't simplify that away.
Local Postgres needs pnpm migrate after pulling this branch: there is a new table.

Next step

Deploy the queue job in dry-run mode and compare its log with the cron script's for two days.

.md for agents

Variations

Handing work to a teammate

Save it to a cell you share, or the team's hive, and add: “Write it for <name>, who hasn't seen this work.” The decisions they need to make show as proposed, where list_decisions finds them.

Switching agent tools

Run it in the tool you are leaving, then start the next tool with the resume prompt it gives you. onecell is the shared part, so Claude Code, Cursor and Codex all read the same handoff.

Only keeping a record of the conversation

If you want the conversation itself rather than the state of the work, use Park a session from the Agents page: it saves the key turns to your Inbox. Hand off when someone will continue the work; park when you only want to find the conversation later.

Tips

Ask for it before the session gets long: an agent near its limit writes a thinner handoff.
Only mark a decision accepted if you actually agreed to it. Proposed is the honest default.
The gotchas are worth the most: they save the next agent the time this one lost.
Keep one handoff per piece of work and update it, rather than one per session.