How to Hand Off a Coding Agent Session to a Teammate

Published August 29, 2026 · by the AQ team

Handing off a coding agent session means transferring three separate things: the conversation context the agent has built up, the state of the code it has produced, and control of the live process. As of August 2026 no major agent CLI transfers all three to another person in one step. Claude Code and Codex store sessions locally, per machine and per account, and cloud platforms keep a teammate's access read-only unless an admin loosens it. So the reliable handoff is a deliberate one: land the code state on a pushed branch, capture the context in a written handoff note, and transfer live control only when the session runs somewhere both people can reach, such as a tmux session on a shared VM.

The three layers of a handoff

Treat the session as three layers, because each one transfers differently:

• Conversation context. What the agent was asked, what it tried, what it rejected, and why. This lives in the session transcript and, critically, in the head of the person who was steering. It transfers as writing.
• Code state. The branch, the diff, the untracked files, the failing test. This transfers as git: if it is not committed and pushed, it does not hand off.
• Live control. The running process itself: who can type into it, interrupt it, approve its next action. This transfers only when the session runs on infrastructure the next person can reach.

Most botched handoffs fail because the sender transferred one layer and assumed the others came along: a pushed branch without the context note forces the receiver to reverse-engineer intent from the diff.

What the tools give you today

Claude Code: resume is per machine and per account

Claude Code saves every session continuously as a local transcript (under the .claude directory on that machine), and resuming is first-class: claude --continue reopens the most recent session in the current directory, claude --resume opens a session picker, and named sessions resume directly by name. As of August 2026 all of that is scoped to one machine and one account. Cross-machine CLI resume is an open feature request on the Claude Code repository, not a shipped feature, and Anthropic's cloud sessions and teleport command move sessions between your own devices, not between people (see moving Claude Code between your laptop and the cloud for that workflow).

What Claude Code does give a handoff is /export, which renders the current conversation to a readable text file or the clipboard. An exported transcript plus a pushed branch is a complete handoff package; resuming and searching Claude Code sessions covers the transcript mechanics.

Codex: same shape, same boundary

Codex CLI stores sessions as local files and resumes them with codex resume --last (or a picker via codex resume). In Codex cloud, as of August 2026, each user in a ChatGPT workspace has their own task history: teammates do not see each other's tasks by default, and sharing a scheduled task copies the instructions without chat history or previous results. The practical handoff artifact from a Codex cloud task is the pull request it opens.

Cursor cloud agents: read-only by default, follow-ups by admin switch

Cursor's cloud agents are the most handoff-aware of the vendor platforms. As of August 2026 you can send an agent's URL to a teammate on the same Cursor team, and if they have their own access to the repository, they can view the run read-only, conversation and changes included. A team admin can additionally enable team follow-ups, which lets teammates send messages to an agent someone else started. Cursor's own documentation flags the tradeoff plainly: the agent runs with its creator's secrets and credentials, so a follow-up from a teammate executes with the original creator's access.

The gap all three share

None of these transfers a live terminal session between people, and the usage data explains why: a July 2026 LeadDev analysis of 25,264 agent-generated pull requests across 2,361 popular GitHub repositories found that in 79 percent of agentic PRs the same developer both reviewed and modified the agent's contribution, and only about one in eight workflows involved multiple humans. The tooling assumes a solo operator; teams that hand sessions off are ahead of the default, which means doing some of the work themselves.

The manual handoff playbook

This works with any agent, any harness, any pair of time zones.

1. Land the code state

Commit everything, including work in progress, and push the branch. A WIP commit with an honest message beats a clean tree the next person cannot see.

git add -A
git commit -m "WIP: token refresh works, retry loop still failing test_backoff"
git push -u origin fix-auth-refresh

2. Write the handoff note

Five sections, kept short:

• Goal: the task in one sentence, with the issue link.
• Done: what works now, and how to verify it (the exact test command).
• Not done: what remains, most specific item first.
• Dead ends: what the agent tried that did not work, and why it was abandoned. This is the section people skip, and without it the next person re-runs yesterday's failures.
• Next action: the single command or prompt the receiver should start with.

You do not have to write it by hand: ask the agent, at the end of the session, to write the handoff note for the next person; it has the whole session in context. Read it and correct what it got wrong, and attach the exported transcript for anyone who wants the full history.

3. Put the note where the receiver will look

The PR description is usually right, because it travels with the branch and reviewers see it anyway. A HANDOFF.md committed on the branch works for pre-PR work. What does not work is a note living in the sender's chat scrollback.

4. Receive into a fresh session

The receiver should not try to import the sender's raw transcript into a new agent session; replayed context ages badly and buries the current state under history. Start a fresh session pointed at the branch and the note: read the handoff note, read the diff against main, run the verification command, then take the next action. The same discipline applies when the handoff crosses tools rather than people; carrying context between Claude Code and Codex covers that variant.

5. For live control, share the machine, not the transcript

When you genuinely need to hand over a running session (a long agent run mid-flight, a debugging state that took an hour to reach), the pattern that works is running the agent where both people have access: a shared VM with tmux. Two SSH clients attached to the same tmux session see the same terminal, so the receiver watches the run live and the sender detaches when the handoff is done. Follow-the-sun teams have used this pattern since long before coding agents, paired with a short overlap window where sender and receiver are online together: the note answers the questions you predicted, the overlap answers the ones you did not.

Handoff etiquette

• Hand off at a stable point. Tests green, or the failing state documented. Never mid-refactor with the build broken and no note saying so.
• One person steers at a time. Typing into a session someone else is driving is the cardinal sin; announce a takeover and get an acknowledgment first.
• Dead ends are deliverables. The abandoned approaches are the part of the context that exists nowhere but the session. Write them down before you close the laptop.
• Name the next action. A handoff that ends with "it is in decent shape" transfers a task; one that ends with "run the backoff test, the retry loop is off by one" transfers momentum.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. In this guide's terms, AQ makes the hard layer (live control) a product feature instead of an SSH ritual. Agents run as real CLIs in persistent tmux sessions on your team's VM, so the session survives the sender closing their laptop, and it streams live to the browser: the receiver opens the same workspace and is watching the same session, with the full scrollback, from any device. Nothing to export and nothing to reattach.

Control transfers with consent rather than shared SSH keys: the receiver asks to type, and the session's owner approves the control request in one click while keeping their own input. Each workspace runs in its own isolated git worktree on a dedicated branch, so the handoff branch is already pushed where teammates can see it, and the PR the agent opens is tracked on the workspace. Visibility is owner-managed (team-visible, or private and shared with specific people), and for teams that run intake through Linear, ownership follows the assignee: reassign the issue and the workspace moves to the new owner. The playbook above still applies (write the note, name the next action); AQ removes the part where you rebuild the session on the other side. See sharing a dev environment with your team and team workflows for coding agents for the wider patterns.