Claude handoff

Handoff

Generate a complete, structured handoff document from the current chat session, optimized for consumption by Codex, Cursor, or other IDE-based AI coding agents.

The output is two files with identical content in different formats:

• handoff-{project}-{YYYY-MM-DD}.md -- markdown with headings, code fences, tables
• handoff-{project}-{YYYY-MM-DD}.txt -- flat text with ASCII section dividers

Save both to /mnt/user-data/outputs/ and present them with present_files.

Core principle

This is lossless distillation, not transcription. Every meaningful detail from the chat survives, but reorganized so the next model can act immediately. The biggest single value-add is explicitly labeling discarded approaches with the reason they were rejected, so the next model does not re-suggest them.

Do not paraphrase technical details. File paths, function names, error messages, version numbers, command strings, and config values must appear verbatim. Prose around them can be tightened.

When to run

One-shot. Do not ask the user clarifying questions. Infer the project name from the chat (repo name, app name, or main subject). If genuinely ambiguous, use session as the project slug.

What to extract from the chat

Walk the entire conversation from start to current turn. Pull out:

1. Project identity -- name, repo URL, local path, deployment target, stack, key dependencies
2. The goal of the session -- what the user was trying to accomplish
3. Decisions made -- each one with the reasoning, and any alternatives that were considered and rejected
4. All code blocks -- both final and discarded, clearly labeled (see Code Handling below)
5. Errors hit and their fixes -- error message verbatim, root cause, solution
6. Environment quirks and gotchas -- anything non-obvious about the setup, library versions, OS-specific behavior, config requirements
7. File paths touched -- every file mentioned, created, or edited, with one-line purpose
8. Commands run or planned -- shell commands, git operations, deploy steps
9. User preferences expressed -- naming conventions, style rules, things to avoid
10. Open questions -- anything unresolved at the moment of handoff
11. Next steps -- ordered, imperative, actionable

Do not omit detail because it seems minor. A throwaway comment like "we found out port 465 needs secure: true" is exactly the kind of thing the next model needs.

Code handling

Include every code block from the chat. Label each one with one of these statuses:

• [FINAL] -- the version that was accepted and is currently in use
• [SUPERSEDED] -- earlier version that was replaced; include the reason it was replaced
• [REJECTED] -- a version that was tried and explicitly thrown out; include the reason
• [DRAFT] -- proposed but never finalized

For [SUPERSEDED] and [REJECTED] blocks, the rejection reason is mandatory. This is the whole point. Without it, the next model will re-suggest the same wrong thing.

Never abbreviate or truncate [FINAL] code blocks. Emit the full file contents verbatim. No [... rest of file ...], no [... see repo for full content ...], no [... truncated ...]. The receiving model has zero file system access to your environment, so a pointer to a path it cannot reach is useless. If the file is 800 lines, output 800 lines. The same applies to [SUPERSEDED] blocks: the whole reason for including a superseded version is so the next model can see exactly what was changed and why. The only blocks that may be abbreviated are [REJECTED] blocks where the rejection happened at the concept level and no actual code was ever written -- in that case write (no code; behavioral choice) or similar and explain in prose.

Each code block must include the file path it belongs to (or "no file -- one-off snippet") and the language tag.

Output structure

Use this exact section order in both files. Omit a section only if it would be empty.

# Session Handoff: {Project Name}

> Generated {ISO timestamp} for handoff to Codex / Cursor.
> Source: chat session with Claude.

## TL;DR

{3-5 bullets. What was being built, where we landed, what is next.}

## Project Context

- **Name:** ...
- **Repo:** ...
- **Local path:** ...
- **Stack:** ...
- **Deployment:** ...
- **Key deps:** ...
- **Branch / working state:** ...

## Session Goal

{One paragraph. What the user came in wanting to accomplish.}

## Timeline

{Chronological, tight. Each item: what happened + why + outcome. One or two lines each. This is the narrative spine.}

1. ...
2. ...

## Decisions

| Decision | Rationale | Alternatives Rejected |
|---|---|---|
| ... | ... | ... |

## Constraints, Gotchas, and Hard Rules

{The non-obvious stuff. Environment quirks, library version pins, "do not do X" rules from the user, platform-specific behavior. Each as a bullet.}

- ...

## Files Touched

| Path | Purpose | Status |
|---|---|---|
| ... | ... | created / modified / deleted |

## Code Artifacts

### [FINAL] {file path}
```{lang}
{code}

[SUPERSEDED] {file path}

Replaced because: {reason}

{code}

[REJECTED] {description}

Rejected because: {reason}

{code}

{... repeat for every code block in the chat ...}

Errors and Fixes

Error	Root Cause	Fix
...	...	...

Commands

{Shell commands, git operations, deploy steps. Verbatim. Group by purpose.}

# Local dev
...

# Deploy
...

User Preferences and Style Rules

{Anything the user expressed about how they want code, naming, tone, formatting.}

• ...

Open Threads

{Unresolved questions, known bugs, deferred work.}

• ...

Next Steps

{Ordered, imperative. The next model should be able to start executing from item 1.}

1. ...
2. ...

Raw Notes

{Anything that did not fit cleanly above but might matter. Dump zone. Do not omit detail to keep this section short.}

## TXT format adaptation

The `.txt` version follows the same structure but with these substitutions:

- `# Heading` becomes `=== HEADING ===` (uppercase, padded with `=`)
- `## Subheading` becomes `--- Subheading ---`
- Markdown tables become aligned plaintext tables with `|` separators and `-` divider rows
- Code fences become indented blocks (4 spaces) with a `--- CODE: {file path} [{status}] ---` header line and a `--- END ---` footer line
- Bullets use `*` instead of `-`
- Bold/italic markdown is stripped

## Filename convention

handoff-{project-slug}-{YYYY-MM-DD}.md handoff-{project-slug}-{YYYY-MM-DD}.txt

Project slug is lowercase, hyphenated, no spaces. If the chat has multiple handoffs in one day, append `-1`, `-2`, etc.

## Final step

After writing both files to `/mnt/user-data/outputs/`, call `present_files` with the `.md` first (it renders nicer in the chat preview) followed by the `.txt`. Add a one-line summary above the file presentation: how many code blocks were captured, how many decisions logged, and what the recommended first prompt to Codex/Cursor is.

Example summary:

> Captured 14 code blocks (9 FINAL, 3 SUPERSEDED, 2 REJECTED), 6 decisions, 4 errors with fixes. Recommended first prompt for Codex: "Read this handoff doc, then continue from Next Step 1."

## Hard rules

- Never omit detail because it seems redundant. The next model has zero context.
- Never paraphrase identifiers, paths, or error strings. Verbatim only.
- Never skip the rejection reason on `[SUPERSEDED]` or `[REJECTED]` code blocks.
- Never abbreviate, truncate, or summarize `[FINAL]` code blocks. Emit the full file contents verbatim, no matter how long. Phrases like `[... rest of file ...]`, `[... see repo ...]`, or `[... full content ...]` are forbidden inside FINAL blocks. The receiving model needs the actual bytes, not a pointer. The same rule applies to `[SUPERSEDED]` blocks where the full prior version is the entire point of including it.
- Never use em dashes anywhere in the output. Use double hyphens or commas instead.
- Never invent details that were not in the chat. If a section has no content, write `_(none recorded in this session)_` rather than fabricating.
- Do not ask the user any questions. One-shot only.