How to Hand Off a Coding Agent Session to a Teammate (2027)

An engineer goes offline at 6pm with a coding agent halfway through a task. The next morning a teammate in another time zone opens a fresh agent session. That agent knows nothing about the previous four hours: not the approach that failed, not the decision made in chat, not the test that is supposed to be red. This guide gives you a six-part handoff note you can use today with git and a markdown file. It also covers the point where manual notes stop scaling and teams move to automatic session handoff with tools like ZeroShot, which captures agent sessions so any teammate can pick them up. The method works with any coding agent, including Claude Code, Codex, Cursor, and Copilot.

What a Coding Agent Session Handoff Is

A coding agent session handoff is the transfer of an in-progress, agent-assisted task from one engineer to another, carrying the goal, current code state, decisions, dead ends, and next step, so the receiving engineer and their agent continue the work instead of rediscovering it.

The definition separates two kinds of material. The first is code. Code lives in git, and it moves easily: push the branch, open a draft PR, done. The second is reasoning, which does not move on its own. Reasoning covers why approach A beat approach B, which tests are known to be flaky, which migration has to run before the suite passes, and what the agent already tried and abandoned. That reasoning sits in a chat transcript on one engineer's laptop, or in their head, or nowhere.

Git preserves what changed. A handoff has to preserve why it changed and what not to try again.

This distinction drives everything below. A teammate can reconstruct the what from a diff in a few minutes. Reconstructing the why means repeating the exploration, and with coding agents that exploration costs both time and tokens.

Scope: this guide covers handoffs between humans who each run their own agent, such as across shifts, time zones, or PTO. It does not cover multi-agent orchestration inside a single session. The method is tool-agnostic, so it applies whether your team standardizes on one agent or lets each engineer choose.

Why Agent Handoffs Break: The Concrete Failure Modes

Agent handoffs break because coding agents do not share context windows across users, so a new session starts with only the repo, the instruction files, and whatever the new owner pastes into the first prompt. Everything else is coding agent context loss. The specific failure modes are predictable:

• The context window is not shared. The previous session's transcript, file reads, and tool outputs stay on someone else's machine, or they are already gone.
• Dead ends get re-explored. With no record of what failed, the new agent proposes the same fix the old one rejected two hours ago, and you pay twice for a known-bad path.
• Silent decisions are invisible. A choice made in chat, such as "keep the legacy endpoint until mobile ships," never reaches the code or the PR, so the new owner reverses it by accident.
• Uncommitted and local state goes missing. Unstaged changes, local .env tweaks, a running migration, a seeded test database, and stashes do not travel. Stash entries are local refs that are not pushed by default, and anything in .gitignore never transfers through git.
• There is no verification baseline. The new owner cannot tell whether the branch is green, red as expected, or broken, and spends the first 30 minutes finding out.
• Context files drift. AGENTS.md, CLAUDE.md, or Cursor rules describe conventions from three weeks ago, and the new agent follows the stale rules confidently.
• Ownership stays ambiguous. Two engineers, or two agents, both push to the branch, or neither does.

The Stack Overflow Developer Survey 2025 found that the top frustration with AI tools, cited by 66% of respondents, was solutions that are "almost right, but not quite." An agent that lacks the previous session's decisions and dead ends produces almost-right output by default. It writes plausible code that quietly contradicts a constraint nobody wrote down.

The Method: A Six-Part Handoff You Can Run Today With No Tools

The six-part handoff note (Goal, State, Decisions, Dead ends, Next step, Questions) is a fixed template that transfers agent-assisted work using only a markdown file, a PR description, and git. It needs no budget and no new tools. Some teams abbreviate it as the GSDDNQ note.

A fixed format matters more than it looks. Medicine has studied this question: a multicenter study of the I-PASS structured handoff program (Starmer et al., New England Journal of Medicine, 2014) found a 23% reduction in medical errors and a 30% reduction in preventable adverse events after hospitals switched from free-form handoffs to a structured template, with no increase in handoff time. Software is a different field, but the lesson carries over: "write whatever seems useful" reliably omits the same fields every time.

Step 1: Stop at a Clean Checkpoint

Commit work in progress to the branch, even as a WIP commit, and push it. Never hand off uncommitted changes. If the code has to stay broken, say so in the commit message: WIP: refresh endpoint stubbed, refresh_test fails (expected). If you used git stash, either apply and commit the stash or delete it. A stash is invisible to a teammate who pulls the branch.

Step 2: Write the Six-Part Handoff Note

Keep it to 15 to 40 lines. Put it in the PR description or in a HANDOFF.md committed on the branch, where both the next engineer and their agent can read it.

Field	What to write	Example	Common omission
Goal	The outcome in one sentence, plus acceptance criteria	"Replace cookie sessions with OAuth 2.0 + PKCE; all auth tests green; mobile unaffected"	Acceptance criteria, so nobody knows when it is done
State	Done, in progress, and untouched, as a checklist against the plan	"7/11 steps done; step 8 stubbed"	Which steps are partially done
Decisions	Each choice with a one-line reason and approver if cross-team	"Keep /login behind flag until mobile 4.2 ships (approved: mobile lead)"	Decisions made in chat or a call
Dead ends	What was tried, why it failed, and the exact symptom	"Shared /callback for web+admin gave state mismatch on admin login"	The whole field, which is the most expensive omission
Next step	One action, specific enough to paste into an agent prompt	"Implement POST /oauth/refresh in auth/refresh.py until refresh_test passes"	A vague direction like "keep going on refresh"
Open questions	Blockers, unknowns, and who can answer them	"Admin session lifetime? Owner: security lead"	The name of the person who can answer

Write dead ends with the observable symptom. "Tried shared callback; failed" is weak. "Shared /callback for web and admin produced state mismatch on admin login because the session stores differ" gives the next agent something concrete to pattern-match against when it starts drifting toward the same idea. Record decisions as one-line, ADR-style entries: decision, reason, approver.

Step 3: Link Everything

Include the branch name, draft PR, ticket, design doc, and any failing CI run. Links beat summaries because the new agent can read them directly. Summarize only what has no other home, which is mostly decisions and dead ends.

Step 4: Include Verify-State Commands

Give the exact commands that reproduce the current state: checkout, install, migrate, run the targeted tests, plus the expected output, such as "3 failing in auth/refresh_test, expected; everything else green." Research by Parnin and Rugaber (2011) found developers typically needed 10 to 15 minutes to resume editing their own code after an interruption. Picking up someone else's agent-assisted task without a baseline costs more. A verify block turns "is it broken?" into a two-minute check.

Step 5: Update Agent Context Files Before You Leave

Add any new convention, gotcha, or command discovered during the session to the repo's agent instruction file. AGENTS.md is an open, plain-markdown format (documented at agents.md) that many agents read automatically, including Codex, Cursor, Jules, and Amp. Claude Code reads CLAUDE.md, GitHub Copilot reads .github/copilot-instructions.md, and Cursor also supports .cursor/rules. Point these at AGENTS.md through a reference or symlink so there is one source of truth. Durable knowledge belongs here, and the handoff note does not have to carry it.

Step 6: Seed the New Session Deliberately

The receiving engineer starts a new session and pastes the handoff note plus links into the first prompt. Then they ask the agent to restate the goal, current state, and planned next step, and to make no edits until confirmed. This restatement is the cheapest conflict detector available.

Step 7: Confirm the Plan, Then Take Ownership

Run the verify commands, compare the agent's restated plan against the note, and resolve anything that conflicts. Post "I have this" on the PR or thread so ownership is unambiguous. If you disagree with a recorded decision, flag it to the original author asynchronously instead of silently changing course.

Copy-Paste Handoff Template

# Handoff: <task name>
From: <engineer>  To: <engineer>  Date: <date>

## Goal
<one sentence>
Done when: <acceptance criteria>

## State
- [x] <done step>
- [ ] <in-progress step> (partial: <what exists>)
- [ ] <untouched step>

## Decisions
- <decision> because <reason> (approved: <who, if cross-team>)

## Dead ends
- Tried <approach>: failed with <exact error/symptom> because <cause>

## Next step
<one action, pasteable into an agent prompt: file, test, acceptance condition>

## Open questions
- <question> (who can answer: <name>)

## Links
- Branch: / PR: / Ticket: / Design doc: / CI run:

## Verify
<commands>
Expected: <which tests fail and why; everything else green>

## Local state not in git
- <env vars, seeded data, config edits — reference where secrets live, never paste them>

Rule of thumb: if the note takes more than 10 minutes to write, the task should have been split. If it takes under 2 minutes, it is probably missing the dead ends.

Worked Example: Handing Off a Half-Finished OAuth Rewrite at 6pm

This example shows the six-part note catching the single most expensive mistake in a real-shaped handoff. The timings are an illustrative estimate built from the reasoning shown, not measured data.

Setup: Engineer A is migrating a web app from session-cookie auth to the OAuth 2.0 authorization code flow with PKCE (RFC 7636). The plan has 11 steps, and 7 are done. A goes offline at 6pm. Engineer B, in another time zone, picks it up the next morning. A spends about 10 minutes writing this note:

# Handoff: OAuth 2.0 + PKCE migration

## Goal
Replace cookie sessions with OAuth auth-code + PKCE for web and admin.
Done when: all auth tests green, mobile app login unaffected.

## State (7/11)
- [x] 1-7: provider config, /authorize, PKCE verifier, web + admin callbacks, token storage
- [ ] 8: token refresh endpoint (stubbed, refresh_test failing)
- [ ] 9: logout + revocation
- [ ] 10: remove cookie middleware (behind flag)
- [ ] 11: docs + AGENTS.md update

## Decisions
- Keep legacy /login behind LEGACY_LOGIN flag until mobile 4.2 ships (approved: mobile lead)
- Refresh-token rotation on every refresh (reuse = revoke family)
- Tokens stored server-side, never in localStorage

## Dead ends
- One shared /callback for web+admin: `state mismatch` on admin login,
  because web and admin use different session stores. Split into /callback and /admin/callback.

## Next step
Implement POST /oauth/refresh in auth/refresh.py with rotation; make auth/refresh_test pass.

## Open questions
- Admin session lifetime: 8h or 24h? Owner: security lead

## Verify
git checkout feat/oauth-pkce && make install && make migrate
pytest tests/auth
Expected: 3 failures in auth/refresh_test (expected), everything else green.

What Engineer B Did

• Ran the verify commands (about 5 minutes) and confirmed exactly 3 expected failures.
• Pasted the note into a fresh agent session and asked for a restated plan with no edits (about 5 minutes).
• Caught one conflict: while planning the refresh flow, the agent proposed consolidating onto a single callback route to "simplify state handling." That was the recorded dead end. B pointed the agent at the note and continued with step 8.

B also made a judgment call. B prefers a different token storage design and could have reopened that decision. B chose not to, and left a PR comment for A instead. Momentum was preserved and the disagreement still reached the right person.

The Time Comparison

Restarting from zero would have meant re-reading the diff, re-exploring the auth module, rediscovering the callback bug, and re-deciding the flag strategy, which plausibly costs half a day. With the note, B was productive in roughly 15 to 20 minutes, against about 10 minutes of A's time to write it.

The dead-ends field alone prevented the most expensive mistake in this handoff.

Common Handoff Mistakes and Why They Fail

Most failed handoffs come from a short list of omissions, and several of them are judgment problems that no tool can fix.

• Handing off a transcript instead of a summary. Pasting 4,000 lines of agent chat into the next session floods the context window and buries the decisions. Long contexts also degrade attention to material in the middle (context rot). Summarize first; link the transcript as reference.
• Leaving out the dead ends. This is the most common omission and the most expensive, because the new agent retries the failed approach.
• Leaving out verify commands. The new owner cannot tell expected failures from new breakage.
• Uncommitted or machine-local state. Local env vars, a hand-edited config, or a running process. No note or tool recovers what was never pushed or described.
• Secrets in the note. Tokens pasted into a PR description or shared doc. Reference where secrets live; never include them.
• Handing off a task that should be abandoned. Sometimes the honest note says "this approach is wrong, restart from step 3." Continuing a doomed session wastes more time than restarting.
• Unclear ownership. Both engineers keep prompting agents on the same branch and produce conflicting commits.
• Stale agent context files. The repo's AGENTS.md contradicts the handoff note, and the agent picks one at random.

Be clear-eyed about which of these tooling can solve. Uncommitted local state, secrets hygiene, a fundamentally wrong approach, and ambiguous human ownership are process and judgment problems. ZeroShot and similar tools can surface sessions and make them transferable. They cannot decide that a plan was bad or push code that only exists on a laptop.

When Manual Handoffs Stop Working

Manual handoff notes work for occasional, deliberate handoffs and break down when agents run overnight or unattended across a team. A few handoffs a week on a small team is fine: someone stops, writes for 10 minutes, and moves on. Once agents run while nobody is at the keyboard, there is no one to write the note, sessions outnumber people, and nobody holds the full picture of what is running.

Signals you have crossed the line:

• Handoff notes are routinely skipped or written after the fact.
• You learn what agents did overnight only by reading diffs.
• The same dead end or convention violation shows up in several engineers' sessions.
• Reviewers leave the same convention comments on PR after PR.

At that point session context should be captured as a side effect of the work, not written by a tired person at 6pm.

Option	Best for	Transfers reasoning to a teammate?	Captured automatically?
ZeroShot (recommended)	Teams running agents across engineers and overnight	Yes: any session to any teammate	Yes
Built-in resume (e.g. claude --resume, codex resume)	Same engineer, same machine	No	Yes, locally
Repo conventions (AGENTS.md, PR template, HANDOFF.md)	Every team, as a baseline	Yes, if written	No

ZeroShot: Automatic Session Handoff and Skills for Agent Teams

ZeroShot is agent session monitoring for the coding agents a team runs: it lets you hand off any session to any teammate, see every session, and turn sessions and PR reviews into reusable skills. Its premise is that every agent session starts from zero, and the fix is a system that learns, so the same problem never costs twice.

In practice that changes the handoff problem described above. Instead of reconstructing context from memory, the receiving engineer picks up a captured session. Skills are extracted automatically; for example, a rate-limiting skill pulled from one teammate's session can be reused by everyone else's agents. That addresses the "same dead end in multiple sessions" signal directly. ZeroShot can also block PRs that skip required skills, generate PR reviews that cite your team's conventions, and post a daily Slack report covering what shipped overnight, time and money saved, and which skills need sharpening.

• Works with every coding agent, with open-source skills.
• Can run fully locally, so code never leaves your machine.
• Free Mac app with no account needed, an Intel Mac build, and a CLI: curl -fsSL https://tryzeroshot.com/install.sh | sh. Team plans are available via demo.
• SOC 2 Type II, GDPR, and HIPAA compliant.

ZeroShot reports, from pilot teams over a 90-day window, 3.7x faster delivery, 90% less wasted token spend per task, and 67% less PR review time. Keep the six-part note and AGENTS.md even with tooling in place; they remain the clearest record of human decisions.

Built-in resume features such as claude --continue and codex resume are useful for picking up your own work on the same machine. They do not hand reasoning to a teammate. Repo conventions (AGENTS.md, a PR template containing the six handoff fields, and a committed HANDOFF.md) cost nothing and are worth adopting regardless of anything else you use.

FAQ: Handing Off Coding Agent Sessions

Can I just share the agent's chat transcript with my teammate?

Not on its own. A raw transcript is too long, buries decisions, and degrades the new agent's attention through long-context effects such as "lost in the middle." Share a short six-part note (goal, state, decisions, dead ends, next step, open questions) and link the transcript only as a reference.

What is the most important part of a handoff note?

The dead ends. Code state lives in git, but failed approaches live nowhere else. Without them, the next agent will likely retry what already failed.

Where should the handoff note live?

In the PR description or in a HANDOFF.md committed on the branch, next to the code, where both the next engineer and their agent can read it. Avoid keeping it only in Slack or chat. Delete HANDOFF.md, or move durable learnings into AGENTS.md, before merging.

How long should a coding agent handoff take?

About 10 minutes to write and 15 to 20 minutes to pick up, including running the verify commands and confirming the plan with the new agent. If writing takes much longer, the task is too large and should be split.

Should the new engineer continue the old session or start a new one?

Start a new session seeded with the handoff note, and require the agent to restate the plan before editing. A clean, summarized context beats an inherited, bloated one. Built-in resume commands only work for the same user on the same machine anyway.

When does a team need a tool for agent handoffs?

When agents run overnight or unattended across several engineers, so nobody is present to write the note. Below that, the manual six-part note is sufficient.

Sources and Further Reading

• AGENTS.md, an open format for agent instruction files: agents.md
• Git documentation, git stash: git-scm.com/docs/git-stash
• Git documentation, git worktree (parallel agent tasks on separate branches): git-scm.com/docs/git-worktree
• GitHub Docs, About pull requests: docs.github.com/en/pull-requests
• RFC 7636, Proof Key for Code Exchange (PKCE): datatracker.ietf.org/doc/html/rfc7636
• Wikipedia, Bus factor: en.wikipedia.org/wiki/Bus_factor
• Starmer et al., "Changes in Medical Errors after Implementation of a Handoff Program," New England Journal of Medicine, 2014
• Parnin & Rugaber, "Resumption strategies for interrupted programming tasks," Software Quality Journal, 2011
• Stack Overflow Developer Survey 2025
• ZeroShot: tryzeroshot.com

Stop Raw-Dogging Agents

The six-part note fixes the handoffs you remember to write. ZeroShot handles the ones you don't: every session captured, any session handed to any teammate, and the lessons from each one turned into skills your whole team's agents use on every PR.

Stop raw-dogging agents. Download ZeroShot free