---
name: checkpoint
description: Persist everything worth keeping from this session before context is lost — route durable lessons to the right CLAUDE.md, save preferences to memory, log credentials to the registry, and write in-flight work to STATE.md so a compacted or resumed session has no amnesia. Use when the user types /checkpoint, says "save state / before we compact / wrap up / don't lose this", when a session has run long or is nearing compaction, and before any risky or irreversible step.
user-invocable: true
trigger: /checkpoint
---

# checkpoint

Compaction and `/clear` throw away everything not written to disk. This routine writes
it down first. Run it **before** compacting — then compact.

Two different things are being saved, and they go to different places:

- **Lessons** — durable facts worth knowing next time (route them, see below)
- **In-flight work** — what you were in the middle of (goes to `STATE.md`)

Do not skip the second. Routing tables capture *"the reaper kills Chrome at 05:00"*;
they do not capture *"I was three files into a refactor and the fourth still has the
old signature."* That is what actually causes amnesia.

## Step 1 — write in-flight state (always)

Write `STATE.md` **as the last thing you learned, not a diary**. Overwrite it each
checkpoint; it is current state, not history.

- Working inside a project → `<project>/.claude/STATE.md`
- No single project (cwd is `~/Claude`, or the session spanned many) → `~/.claude/STATE.md`

```markdown
# STATE — <what this session is doing>
_updated 2026-08-08 15:30 · session <short-id>_

## Now
One or two lines: what is actually happening right now.

## Done
- Landed things, with the paths/IDs needed to verify them

## In flight
- The half-finished thing, and **exactly** where it stopped
- Anything left in a broken or intermediate state ⚠️

## Next
1. The immediate next action, concrete enough to just do

## Blocked / waiting on
- Waiting on a person, a 24h timer, an external system — say what and since when

## Don't re-derive
- Facts that cost real effort this session: IDs, paths, ports, why an approach failed
```

Be specific. `zone id 341ab540…`, `port 7070`, `Profile 1 = agentropic.ai` — a future
session should not have to re-discover any of it.

## Step 2 — route the lessons

For each durable thing learned, ask **"where would I look for this next time?"**

| Destination | What belongs there | Test |
|---|---|---|
| `~/.claude/CLAUDE.md` | Standing rules, machine/infra registry, cross-project gotchas | *Would this matter in a different project?* |
| `<project>/CLAUDE.md` | Build/deploy commands, architecture, project-specific traps | *Only true inside this folder?* |
| `~/.claude/projects/<slug>/memory/` + `MEMORY.md` | Preferences, feedback on how to work, pointers to resources | *About the user or how they want things done?* |
| **Credentials Registry Sheet** | Every new token, key, OAuth cred, webhook secret | *Is it a secret?* — this is **mandatory**, see global CLAUDE.md |
| `<project>/.claude/STATE.md` | In-flight work only | *Will this be stale in a week?* |

**Never hand-edit `~/.claude/KNOWLEDGE-INDEX.md`** — the 05:00 launchd job regenerates
it from every CLAUDE.md and will silently overwrite you. To change what it says, change
the source `CLAUDE.md`.

### Write freely vs. propose

- **Write without asking:** `STATE.md`, memory files, project `CLAUDE.md`
- **Propose, don't write:** `~/.claude/CLAUDE.md` — it is load-bearing across every
  project and machine. Show the exact diff you want to add and let the user say yes.
- **Credentials:** log to the registry immediately — that rule already stands.

### Don't write noise

Skip anything the code, git history, or an existing `CLAUDE.md` already says. Skip what
only mattered inside this conversation. If a fact is wrong, delete it rather than adding
a correction beside it. One fact per memory file, with a `MEMORY.md` pointer line.

## Step 3 — report, then hand over

Print a short table of what was written where, and what needs approval. Then say plainly
that it is safe to compact — **you cannot start compaction yourself**, the user runs
`/compact` (or auto-compact fires).

## The safety net

`~/.claude/hooks/precompact-checkpoint.sh` runs on **every** compaction, manual and
automatic. It cannot write files or take a turn, but it does inject instructions telling
the compaction to preserve pending work, blockers and hard-won identifiers verbatim — so
an unplanned auto-compact still degrades gracefully. It also warns when no `STATE.md` has
been written recently. It is a backstop, not a substitute for running this skill.