August 20, 2026 · Harness Engineering · Coding Agents · Template · EN

Coding-Agent Handoff Template: Transfer Work Between Claude Code, Codex, and Other Agents

A repository-native handoff protocol for transferring coding work between Claude Code, Codex, Cursor, and other agents without losing scope, decisions, evidence, or recovery state.

Coding-Agent Handoff Template: Transfer Work Between Claude Code, Codex, and Other Agents

A coding-agent handoff is a repository-visible record of the outcome, current state, changed contracts, evidence, unresolved risk, and next action at a stable checkpoint. It lets a fresh Claude Code, Codex, Cursor, or other agent continue without reconstructing the previous chat.

A weak handoff says, “The feature is mostly done; finish the tests.” A strong handoff identifies which behavior works, which files and contracts changed, the exact commit to inspect, which commands passed, what was not run, and the first decision the next agent must make.

This page provides a reusable handoff template and a verification protocol. It complements the broader operating model in How to Manage Multiple Coding Agents in One Repository: that guide coordinates several workers; this one defines the artifact that crosses the boundary between them.

The handoff must survive the missing chat

Coding-agent sessions end for ordinary reasons:

the context window is full;
a task moves from planning to implementation;
one agent writes code and another reviews it;
a worker stops at an approval boundary;
a long-running job resumes on another machine;
a failure needs a clean recovery session;
a specialist tool takes over one narrow part of the change.

If the next agent needs the old transcript, the task state is not durable. Transcripts contain false starts, repeated explanations, unverified assumptions, and interface-specific details. They are useful evidence during an incident, but they are a poor operating contract.

The handoff should instead point to verifiable repository state:

Question	Durable answer
What are we trying to achieve?	task packet and outcome statement
Where is the current work?	commit, branch, patch, or worktree
What changed?	paths and contract deltas
Why was it changed this way?	accepted decision or explicit assumption
What is proven?	commands, results, and relevant runtime evidence
What is not proven?	omitted checks and residual risks
What happens next?	one concrete next action and its gate

The handoff is an index into those sources, not a replacement for them.

Task packet, checkpoint, and handoff are different artifacts

Teams often overload one plan file with every stage of the task. Separating the artifacts makes ownership clearer.

Artifact	Created	Owns	Should not own
Task packet	before execution	outcome, scope, acceptance, validation plan	fabricated completion state
Stable checkpoint	during execution	exact code and file state	narrative explanation
Handoff	at a worker or session boundary	actual state, evidence, risk, next action	permanent architecture rules
Decision record	when a lasting choice is accepted	why a durable constraint exists	temporary task progress
Repository instructions	when workflow rules change	recurring operating behavior	who owns one task today

A task packet says what should happen. A checkpoint preserves what exists. A handoff says what actually happened and how to continue.

The coding-agent handoff template

Store the file somewhere the next worker will discover, such as docs/tasks/active/<task>/handoff.md or .agents/handoffs/<task>.md. Use one canonical location and mention it in root repository instructions.

# Handoff — <task name>

## Outcome
State the user-visible or system-visible behavior this task is meant to produce.
Say whether that outcome is complete, partial, blocked, or disproven.

## Stable checkpoint
- Branch: `<branch>`
- Commit: `<full commit SHA>`
- Worktree or patch: `<path or artifact>`
- Base revision: `<revision used to start>`
- Working tree: `<clean, or list intentional uncommitted paths>`

## Scope
- Task packet: `<path>`
- Write scope used: `<paths or subsystem>`
- Read-only dependencies: `<paths>`
- Explicitly untouched: `<paths or operations>`

## Changed contracts
Describe behavior, interfaces, schemas, commands, generated outputs,
or ownership boundaries that changed. Link to authoritative files.

## Decisions and assumptions
- Accepted decision: `<decision and source>`
- Temporary assumption: `<assumption that still needs proof>`
- Rejected approach: `<only if it prevents repeated dead work>`

## Evidence
- `<exact command>` — PASS: `<result that supports a claim>`
- `<exact command>` — PASS: `<result>`
- Runtime or visual evidence: `<artifact, URL, screenshot, or log reference>`

## Not run
- `<relevant check>` — `<why it was omitted>`

## Residual risks
- `<specific failure that could still exist>`
- `<contract or environment that remains unverified>`

## Next action
One concrete action the next worker should take first.
Include its expected output and the gate for proceeding.

## Recovery
If the next action fails, state the last known-good checkpoint,
what may be safely discarded, and which evidence to preserve.

The template is deliberately short enough to complete while details are fresh. Add domain-specific fields only when they change how the next worker acts.

Write claims that point to proof

A handoff should not report activity as if it were an outcome.

Weak claim	Better handoff claim
“Updated auth.”	“Refresh-token reuse now returns 401 in `src/auth/refresh.ts`; focused integration test passes at commit `…`.”
“Tests look good.”	“`npm test -- auth` passed 42 tests; the browser login flow was not run.”
“Refactored the API.”	“Renamed `User.id` to `User.userId` in the public schema; regenerated TypeScript client is clean; Python client remains stale.”
“Ready to merge.”	“Worker checks pass; combined migration rollback and end-to-end signup remain integration-gate requirements.”
“Could not finish.”	“Blocked on schema-owner approval for nullable `team_id`; no migration was created; checkpoint is clean.”

Each claim should answer three questions:

What behavior or contract is being claimed?
Which stable state contains it?
Which evidence supports it?

If one answer is missing, label the statement as an assumption or open risk.

The handoff pipeline

A file existing is not the success condition. The success condition is that a fresh worker can reconstruct and verify the state without hidden context.

Handoff from Claude Code to Codex: a worked example

Suppose Claude Code has changed an API contract and Codex will regenerate clients and update consumers.

# Handoff — avatar upload contract

## Outcome
Partial. The API now accepts JPEG and PNG avatars up to 2 MB.
Server behavior and the OpenAPI schema are complete. Generated clients and UI are not.

## Stable checkpoint
- Branch: `agent/avatar-api`
- Commit: `4d31...`
- Base revision: `main@8bf2...`
- Working tree: clean

## Scope
- Task packet: `docs/tasks/active/avatar-upload/task.md`
- Changed: `packages/api/avatar/**`, `openapi/avatar.yaml`
- Untouched: `generated/**`, `packages/web/**`, migrations

## Changed contracts
- `POST /v1/avatar` now uses multipart input.
- Maximum payload is 2 MB.
- Error `avatar_type_unsupported` is public.
- Canonical schema: `openapi/avatar.yaml`.

## Decisions and assumptions
- Accepted storage choice: `docs/decisions/0017-media-storage.md`.
- Assumption: the TypeScript generator preserves the new error enum.

## Evidence
- `scripts/validate-api avatar` — PASS: 18 focused tests.
- `scripts/lint-openapi` — PASS.
- Manual request with PNG fixture — PASS: HTTP 201.

## Not run
- Client generation — belongs to the next task.
- Browser upload flow — blocked until generated client is integrated.

## Residual risks
- Multipart names may map differently in the Python generator.
- No end-to-end proof exists yet.

## Next action
Run the documented generators from commit `4d31...`, inspect both client diffs,
and stop if either generated API differs from `openapi/avatar.yaml`.

## Recovery
If generation fails, keep commit `4d31...` as the API checkpoint.
Discard generated output only; preserve generator logs and the schema diff.

Codex should first verify the commit, task file, changed contract, and commands. Only then should it generate code. The transfer is between repository states, not between model memories.

Choose a stable checkpoint before writing the handoff

Do not hand off an incoherent working tree unless the interruption is unavoidable. Prefer these checkpoint types in order:

A focused commit with a clean tree — easiest to inspect, diff, revert, and reproduce.
A named patch plus base revision — useful when commits are not allowed.
A worktree with an explicit dirty-path list — acceptable for interrupted recovery.
A prose description without preserved state — not a handoff; it is a reconstruction request.

The checkpoint should represent one coherent unit: a stabilized contract, a reproducible failure, a completed investigation, or an implementation with focused proof. Do not wait for the entire feature if a downstream worker only needs one stable dependency.

Separate decisions from assumptions

The next agent must know which statements it may rely on.

Use three labels:

Accepted decision — durable and backed by an owner or decision record.
Verified fact — observed in the recorded checkpoint with evidence.
Temporary assumption — useful for progress but still needs confirmation.

For example:

Accepted decision: generated clients remain checked in.
Verified fact: TypeScript generation is clean at commit 4d31...
Temporary assumption: Python maps multipart errors to the same enum.

Without labels, the next agent may treat a guess as architecture or reopen an accepted decision.

Record exact evidence and honest omissions

Evidence needs enough detail to reproduce the claim:

npm test                         — too broad; result can change with the environment
npm test -- auth                 — better; exact command
npm test -- auth — PASS, 42 tests — useful handoff evidence

Include the environment only when it materially affects the result: browser, operating system, architecture, feature flag, database mode, or external service version.

The Not run section is mandatory. It prevents silence from being interpreted as proof. A credible handoff often says both:

what passed;
what remains for the integration gate.

A handoff cannot replace the validation contract pattern. It transports the proof produced by that contract.

Verify the handoff in a clean session

Use a fresh agent that cannot see the previous transcript. Give it the repository and the handoff path, then require a structured reconstruction.

The fresh agent should be able to:

locate the task packet and stable checkpoint;
explain the intended outcome and actual current state;
identify changed and untouched contracts;
distinguish accepted decisions from assumptions;
rerun or inspect the evidence;
name omitted checks and residual risks;
state the next action and recovery path.

Score one point for each item. A handoff below 7/7 is not ready for unattended continuation.

If the fresh agent asks a necessary question, do not answer only in chat. Repair the task packet, handoff, source map, validation command, or decision record that should have supplied the answer, then restart the verification session.

This is the same clean-session principle used to audit a repository for agent-readiness: corrective prompts reveal missing repository controllers.

Common handoff failures

A narrative instead of a state transfer

A chronological account of everything attempted forces the next agent to infer current truth. Lead with outcome and checkpoint, not history.

No stable revision

“Use my branch” is ambiguous after another commit lands. Record the exact commit, base, and working-tree state.

Commands without results

A command list is a validation plan. A handoff needs the command, result, and claim it supports.

Results without commands

“Tests pass” cannot be reproduced. Record the invocation and relevant environment.

Hidden contract changes

A generated file, schema, CLI flag, or event payload changes without being named. The next agent discovers the dependency only after downstream work fails.

Permanent rules trapped in the handoff

If a discovered boundary applies to future tasks, move it into AGENTS.md, architecture docs, validation scripts, or a decision record. Handoffs should expire; operating knowledge should not.

The next action is “continue”

“Continue the implementation” provides no priority or gate. Name the first action, expected output, and stop condition.

No recovery path

When the next step fails, the new agent guesses what to discard. Preserve a last known-good checkpoint and identify disposable outputs in advance.

Repository conventions for handoffs

A lightweight layout can be enough:

AGENTS.md
.agents/
  handoffs/
    active/
    archive/
docs/
  tasks/
    active/
  decisions/
scripts/
  validate-handoff

Root instructions can define the lifecycle:

## Agent handoffs

- Write handoffs to `.agents/handoffs/active/<task>.md`.
- Use the repository handoff template; never rely on chat history alone.
- Record a stable checkpoint and exact evidence before transfer.
- A fresh worker must verify the handoff before changing code.
- Move lasting rules and decisions to their canonical owners.
- Archive the handoff when the task is integrated or abandoned.

A mechanical check can require headings, a checkpoint, at least one evidence entry, and an explicit Not run section. Semantic quality still needs review, but structural omissions are cheap to catch.

When not to hand off

A handoff adds overhead. Skip a separate artifact when the same worker can finish a tiny, low-risk change in one short session and the commit plus normal pull-request description already captures the state.

Use a handoff when any of these are true:

another agent or human will continue the task;
the session will cross a context or time boundary;
work is blocked at an approval or dependency gate;
the task changes a shared contract;
recovery would be expensive;
evidence must be reviewed independently;
concurrent tasks depend on this output.

The cost of a handoff should match the cost of reconstructing the work incorrectly.

Handoff readiness checklist

Before transferring a coding task:

The handoff is complete only when the receiver can verify it.

Make the repository carry continuity

Model context is temporary. Repository state can be inspected, diffed, tested, reviewed, and resumed.

A reliable coding-agent handoff freezes a coherent checkpoint, names changed contracts, separates fact from assumption, records executable evidence, exposes omissions, and gives the next worker one concrete action. When a transfer reveals a recurring gap, repair the durable repository layer instead of making the next handoff longer.

repository-harness provides a starting structure for bounded tasks, repository-visible state, validation contracts, and evidence-based handoffs across Claude Code, Codex, Cursor, and other coding agents.

FAQ

What should a coding-agent handoff include?

A coding-agent handoff should include the intended outcome, current state, bounded scope, changed contracts, durable decisions, exact validation evidence, omitted checks, residual risks, stable checkpoint, and the next recommended action. It should let a fresh agent continue without reconstructing the previous chat.

How do I hand work from Claude Code to Codex?

Save the work at a stable commit or patch, write a repository-visible handoff using a shared template, include exact commands and results, and start Codex from the same checkpoint. Ask Codex to verify the handoff against the repository before continuing rather than trusting a prose summary alone.

Should an agent handoff include the full chat transcript?

No. Chat transcripts are noisy, tool-specific, and difficult to verify. A good handoff extracts only the durable task state, decisions, changed contracts, evidence, assumptions, and next action. Link to repository files and commits as the authoritative sources.

Where should coding-agent handoff files live?

Keep active handoffs in a repository-visible task or handoff directory such as docs/tasks/active or .agents/handoffs. Archive or remove them when the task is integrated, while promoting lasting decisions and operating rules into their canonical documentation.

What is the difference between a task packet and a handoff?

A task packet defines the intended outcome, boundaries, acceptance criteria, and validation before work starts. A handoff records the actual state after work: what changed, what was proven, what remains uncertain, and where the next agent should continue.

How do I verify that an AI coding-agent handoff is complete?

Start a fresh agent from the recorded checkpoint and require it to locate the changed paths, explain the current state, rerun the stated checks, identify the next action, and name any unresolved risk without access to the old chat. Any corrective prompt reveals a missing or ambiguous handoff field.

Can a coding-agent handoff replace tests or code review?

No. A handoff transports claims and evidence; it does not create proof. Tests, builds, runtime checks, review, and integration validation remain the mechanisms that establish correctness. The handoff makes those results discoverable and reviewable by the next worker.

Coding-Agent Handoff Template: Transfer Work Between Claude Code, Codex, and Other Agents

The handoff must survive the missing chat

Task packet, checkpoint, and handoff are different artifacts

The coding-agent handoff template

Write claims that point to proof

The handoff pipeline

Handoff from Claude Code to Codex: a worked example

Choose a stable checkpoint before writing the handoff

Separate decisions from assumptions

Record exact evidence and honest omissions

Verify the handoff in a clean session

Common handoff failures

A narrative instead of a state transfer

No stable revision

Commands without results

Results without commands

Hidden contract changes

Permanent rules trapped in the handoff

The next action is “continue”

No recovery path

Repository conventions for handoffs

When not to hand off

Handoff readiness checklist

Make the repository carry continuity

Related pages

FAQ

What should a coding-agent handoff include?

How do I hand work from Claude Code to Codex?

Should an agent handoff include the full chat transcript?

Where should coding-agent handoff files live?

What is the difference between a task packet and a handoff?

How do I verify that an AI coding-agent handoff is complete?

Can a coding-agent handoff replace tests or code review?