Why does an agent handoff need a document at all?

Context windows end, sessions get closed, and the assistant that started the work is not the one that finishes it. What survives is whatever was written down. A handoff document is a compact, honest account of the state of a task: what was done, what was verified, what is still broken, and what to do next. It is not a transcript, and it deliberately does not carry repository access, credentials, or the previous conversation — only text.

What should an agent handoff document contain?

Nine sections, in this order. Copy the template into your project or ask your assistant to fill it in.

# Agent handoff: <task name>

## Objective
One paragraph: what "done" means, and what must not change.

## Repository and branch
- Repo:
- Branch:
- Base:

## Relevant commit
<hash> — <subject>. Everything below describes the tree at this commit.

## Completed changes
- ...

## Files affected
```
path/one.ts   (new | modified)
```

## Commands run and results
```
npm test  → 14 passed
```

## Unresolved problems
1. ...

## Decisions and constraints
- ...

## Next steps
1. ...

Two of these do most of the work. Commands run and results saves the next agent from re-running a ten-minute test suite to learn what you already know. Relevant commit lets it check git log -1 and see immediately whether the summary still matches the branch.

What does a filled-in handoff look like?

A fictional but realistic one: an agent moved session storage to Redis behind a feature flag, ran the tests, and stopped before the CI and staging work. Everything the next agent needs is in the document, including the pre-existing lint warning it should not waste time on.

lib/session/redis-store.ts      (new)
lib/session/index.ts            (modified)
lib/session/memory-store.ts     (unchanged, still default)
docker-compose.yml              (modified)
.env.example                    (modified)
tests/session/redis-store.test.ts (new)

npm test -- session         → 14 passed, 0 failed
npm run type-check          → clean
npm run lint                → 1 warning (unused import in memory-store.ts, pre-existing)
docker compose up redis     → healthy on :6379
SESSION_STORE=redis npm run dev → login/logout works; cart persists across a server restart

How do I publish the handoff and pass the link on?

From Claude Code or Cursor with the Docs MD MCP server connected, at the end of the session:

Write an agent-handoff.md for the work in this session using the nine-section
template, then share it with a 7-day expiry and give me both links.

You get a rendered URL and a raw URL. Paste the raw URL into the next session's first message, or into the issue the teammate will pick up. Without MCP, the same thing from a shell:

curl -s -X POST https://docs-md.com/api/share \
  -H "Content-Type: application/json" \
  --data-binary @<(jq -Rs '{content: ., filename: "agent-handoff.md", expiry: "7d"}' agent-handoff.md) \
  | jq -r '.rawUrl'

How does the next agent or person read it?

• A person opens the rendered link: headings, the file list as a code block, the results table, and a table of contents in the sidebar.
• An assistant with an HTTP tool fetches https://docs-md.com/raw/<id> and gets the markdown as text/markdown. A first message such as "Read https://docs-md.com/raw/… and continue from its next steps" is enough.

Before acting on the summary, the next agent should compare the commit in the document with the branch head. If they differ, someone worked after the handoff was written, and the document is a starting point rather than the truth.

What are the limits?

• 120,000 characters per share; a handoff should be far shorter than that.
• The link is public to anyone who has it. Never include tokens, keys, or customer data.
• Expiry removes the page at its URL; it does not recall copies already fetched.
• The next agent needs its own repository access. The handoff carries a summary, not permissions.

See also: share an implementation plan for review and the REST API.

FAQ