# handoff

**A clean bridge between Claude Code sessions.**

Long Claude Code sessions rot: context fills up, the model starts forgetting decisions, re-trying approaches that already failed, and describing files that no longer look like that. Starting a fresh session fixes the rot — but throws away everything the old session learned.

`handoff` writes a **verified** `HANDOFF.md` at your project root so the next session picks up exactly where this one left off, without repeating your dead ends.


*A messy 3-hour session → `/handoff` → one clean file the next session resumes from.*

---

## Install

```bash git clone https://github.com/ostikwhy-blip/claude-code-handoff-skill.git cp -r claude-code-handoff-skill ~/.claude/skills/handoff ```

Start a new Claude Code session — done. No dependencies, no external APIs, no configuration.

<details> <summary>Install for a single project instead</summary>

```bash cp -r claude-code-handoff-skill your-project/.claude/skills/handoff ```

</details>

## Use

**End of a session** (or when it starts feeling off):

``` /handoff ```

Claude verifies the actual state of your repo, then writes `HANDOFF.md`.

**Start of the next session:**

``` resume from the handoff ```

Claude reads the file, re-checks it against the current repo, surfaces open questions, confirms the plan with you — then continues the work, already knowing what failed last time.

That's the whole workflow. Two commands.

## Why not just ask Claude to "summarize the session"?

Because that summary is written **from a degraded model's memory, at exactly the moment that memory is least reliable.** You get confident fiction: tests that "pass" but were never re-run, file descriptions that are twenty edits stale, hallucinated progress.

`handoff` is built around one rule: **nothing goes in the file from memory alone.**

Before writing a single line, Claude:

1. Runs `git status`, `git log`, `git diff` to reconstruct what *actually* changed — not w