/checkpoint
Save your session before the context window wipes it.
The failure this kills
You spend an hour getting Claude up to speed on what you’re building. It finally understands the plan, the constraints, the file layout — and then the context window fills up. The session force-runs an auto-compaction to make room, and that pass is brutal and kind of random about what it keeps. The next thing you know, the agent has forgotten what you were in the middle of, it re-asks a question you answered twenty minutes ago, and it suggests code that contradicts a decision you’d already made.
It’s one of the most-reported frustrations with Claude Code, and the reason is simple: compaction summarizes the old context but tends to drop the latest thing — the half-finished step you were actually on. That’s the part you most needed it to remember.
What it does
Right before the reset, you run checkpoint, and it writes everything down first — as a real note, not a lossy summary:
- In-flight work. The half-finished thing, and exactly where it stopped, including anything left in a broken or intermediate state.
- Done. What’s already landed, with the paths and IDs needed to verify it.
- Next. The concrete next action, specific enough to just pick up and do.
- The fiddly bits you paid for once. The IDs, ports, file names, and the “why this approach failed” — so nobody has to rediscover them.
Then it routes the durable lessons to the right place (your project notes, your memory, the credentials registry) and hands you a clean state file, so the next session — resumed or brand new — opens up like you never left.
When to reach for it
- Any time the context warning starts to show — run it before you go into a manual
/compact, so you compact on purpose instead of getting surprised. - When you’re wrapping up for the day, so tomorrow’s session starts where today’s ended.
- Before anything risky or irreversible, so there’s a known-good state to come back to.
A good habit: run checkpoint every time you finish a phase of work — somewhere around 400–500k tokens — and then compact. A shorter context also saves you tokens and keeps your agent running faster.
Install
Use the one-prompt install above — paste it into Claude and it builds the skill for you. Or grab the file directly:
mkdir -p .claude/skills/checkpoint
curl -o .claude/skills/checkpoint/SKILL.md https://agentropic.ai/skills/checkpoint/SKILL.mdWorks with Claude Code and any agent that supports the SKILL.md convention.
The bigger idea
The point isn’t the note. It’s that a long-running agent is only useful if its memory survives the moment its working context runs out. Left alone, an AI session degrades exactly when it’s finally productive. Teaching your agent to checkpoint its own state — deliberately, before the reset — is the kind of small, sharp discipline we install during a 1 Week Sprint: by Friday your AI isn’t losing the plot every time the context fills, it’s handing itself a clean handoff and carrying on.
The skill file
This is the entire skill — copy it, or download SKILL.md.
---
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.
Watch the walkthrough.
Every skill ships with a video on our YouTube channel — one discipline per episode, field-tested.