How do I hand off a Claude Code session to a teammate?

You can't pass a running Claude Code session to someone else: the conversation is saved on the computer that ran it, under that person's account. What you hand over instead is the work and the reasoning behind it: a pushed branch, a short handoff note that says what is done and what is next, and, when the history matters, the conversation exported as text. Your teammate starts a fresh session on that branch with the note as the first prompt, and is working in minutes.

Why can't my teammate just resume my session?#

claude --resume and claude --continue pick up conversations that Claude Code saved on the same computer, for the same folder. Your teammate's computer has none of your sessions, and their Claude Code runs on their own account. Copying session files between computers is not a supported way to share work, and it carries everything you pasted into the conversation along with it.

So a handoff between developers is a handoff of state, not of a session.

What does a good handoff contain?#

Part	Where it lives	Why
The code	A pushed branch, committed even if unfinished	Uncommitted changes stay on your disk
What is done and what is next	A handoff note in the pull request or the branch	The next session reads it first
Decisions and dead ends	The same note, as short bullets	Saves your teammate from retrying what failed
The conversation, if needed	`/export` to a text file	For the odd case where the details matter
Shared rules	`CLAUDE.md` or `AGENTS.md` in the repo	Both sessions follow the same rules

How do I write the handoff note?#

Ask the session that did the work to write it before you stop, while it still has the context:

Write a handoff note for a teammate who will continue this work in a new
Claude Code session. Include: the branch and last commit, what is finished,
what is left in order, decisions we made and why, approaches that failed,
how to run the tests, and anything that is half-done. Keep it under 40 lines.

Check it, commit it or paste it into the pull request description, and push:

bash

git add -A
git commit -m "wip: csv export, handoff in PR"
git push -u origin csv-export

A note in the pull request travels with the branch and is easy to find later. A HANDOFF.md on the branch works too; delete it before the merge.

How does my teammate pick it up?#

They check out the branch and start a new session with the note:

bash

git fetch origin
git switch csv-export
claude "Read the handoff note in PR #42 and continue from the first open item."

If the note sits on the branch, point the prompt at HANDOFF.md instead. Asking the new session to restate the plan before it changes anything catches a misread note early.

When should I export the conversation?#

Most handoffs don't need it: a good note is shorter and clearer than the transcript. Export when the reasoning is the hard part, such as a debugging session that ruled out several causes. Inside the session, /export handoff-chat.txt writes the conversation as plain text. Read it before you share it, and remove any secrets, keys or customer data that came up during the session.

How do I avoid two people working on the same thing?#

Say who owns the task at each moment. The person handing off stops pushing to the branch once the note is up; the person picking up says so where the team can see it. Stopping two agents from editing the same files covers the rest, and connecting Codex and Claude Code uses the same note format when the next agent is a different tool.

Where does Joxo fit?#

Joxo gives a team one task board that every teammate's agent can see. An agent that stops mid-task leaves its handoff note on the task, and the next teammate's agent claims the task and reads the note before it starts, whichever agent each person uses. Getting started has the setup.

Frequently asked questions#

Not for a session running on your computer. Share the pushed branch and a handoff note instead; your teammate starts their own session from them.

Does my teammate need my Claude account?#

No, and they shouldn't use it. Each developer runs Claude Code on their own account; the repo, the branch and the note are what they share.

Should the handoff note be committed?#

Either commit it on the branch and delete it before merging, or keep it in the pull request description. The pull request keeps the main branch clean.

What if the work isn't in a state that compiles?#

Commit it anyway on its own branch, and say so in the first line of the note. A broken branch with a clear note is easier to continue than changes that never left your computer.