snapper-shot

A skill for Claude Code that writes down what a session knows, right before that knowledge disappears.

The problem

You spend two hours on a hard problem, settle on an approach, and rule out three others for good reasons. Then the context window fills up, you type /clear, and every bit of that reasoning is gone.

The next session opens with nothing. It does not know the goal, and it does not know which approaches you already threw out, so it cheerfully suggests one of them again. You end up explaining your own project back to it, which is the part of the work you least wanted to repeat.

Git remembers your code. Nothing remembers your reasoning.

What this does

Two commands.

Save captures the state of the session into a numbered file inside the project, so you get snapshots/snapshot1.md, then snapshot2.md, and so on.

Brief reads the newest one back, checks it against the code as it stands now, and tells the next session where it is standing.

/snapper-shot          save the state before you clear
brief me           read the last snapshot and catch up

The part that matters

Before it writes anything, the skill reads the session back to you in a single message covering six things:

• Goal: the one thing you are working toward
• Hard constraints: what cannot change
• Decided: each choice, and the reason behind it
• Rejected: each option you killed, and why you killed it
• Where we are: the current position and the next concrete step
• Open questions: whatever still needs your answer

Then it stops and waits for you to correct it.

That pause is the whole point. A model summarising two hours of conversation will get something wrong, whether it logs a decision you never actually agreed to or quietly softens a blocker into a minor detail. Without the pause, that mistake gets written to disk, and every session afterwards inherits it. Ten sessions later you are debugging a misunderstanding from Tuesday.

The Rejected section earns its keep faster than the rest, because it is the section that stops a fresh model from proposing the same dead idea you already spent an hour ruling out.

Install

With npx

npx snapper-shot

That installs the skill into ~/.claude/skills/snapper-shot, where every project on your machine can reach it.

Useful flags:

npx snapper-shot --project     # install for this project only
npx snapper-shot --hooks       # add the optional hooks
npx snapper-shot --dry-run     # show changes, write nothing
npx snapper-shot --uninstall   # remove it cleanly

Run it with --dry-run first if you would rather see exactly what gets touched before anything changes.

You can also run it straight from this repository without going through the registry:

npx github:benhering123/snapper-shot

Install by hand

Copying two things into a skills folder is the entire installation.

git clone https://github.com/benhering123/snapper-shot.git
mkdir -p ~/.claude/skills/snapper-shot
cp -r snapper-shot/SKILL.md snapper-shot/references ~/.claude/skills/snapper-shot/

To install for one project only, use .claude/skills/snapper-shot inside that project instead of the folder in your home directory.

Start a Claude Code session afterwards and check that snapshot appears in the list of available skills. When it does not appear, the cause is almost always broken YAML in the frontmatter at the top of SKILL.md.

Using it

Save before you clear:

> /snapper-shot

Read the message it gives you and fix anything it got wrong. Once you confirm, it writes snapshots/snapshot3.md and points out anything that probably belongs in your longer-lived project documentation instead.

Pick the work back up later:

> brief me

It finds the newest snapshot, reads it, and compares what it says against your current branch and commit. If the code moved on since that snapshot was written, it tells you before it briefs you, because a snapshot that quietly describes last week is worse than having no snapshot at all.

What lands in the file

# Snapshot 3 — my-project — 2026-08-28 20:41
Supersedes: snapshot2.md · Branch: main @ a3f91c2

## Orientation        what this project is, in three sentences
## Goal               the current objective
## Hard constraints   what cannot change
## Decided            each choice and its reason
## Rejected           each dead option and why it died
## State              done / in progress / next action
## Files touched
## Open questions
## How to run and verify
## Gotchas
## Git state          branch, HEAD, dirty files
## Read first

Old snapshots stay exactly where they are. Brief mode only ever opens the newest one, so the folder gradually becomes a history you can read back whenever you need to know how some decision actually got made.

Snapshots are not project docs

Both are worth keeping, and they hold different things.

| Snapshot | Project doc (README, HANDOFF, architecture notes) | |---|---| | Where the work sits right now | What the project is | | Half-finished work and the next step | Shipped features, URLs, infrastructure | | The reasoning from this session | Decisions that outlive the session | | Replaced by the next snapshot | Kept until it goes stale |

After a save, the skill checks whether anything crossed that line, such as a deploy, a newly wired service, or a lesson that would bite you again later. It asks before it writes to your project documentation, and it never edits those files behind your back.

Optional hooks

Two shell hooks ship in hooks/, and neither one is required.

SessionStart is the one worth adding. It spots a snapshot in the project you just opened and tells the model to catch up before it does anything else, which makes the briefing automatic after a /clear.

PreCompact comes with a warning, and I would rather state it plainly than let you discover it the hard way.

A PreCompact hook cannot write a snapshot for you. It runs as a shell command, and the model is not in the loop when it fires, so nothing in that script can read your conversation. All it can do is leave a pointer to your last snapshot and a reminder to run /snapper-shot yourself.

The reminder is still useful, because a compacted session otherwise forgets that any saved state exists. Just do not install it expecting an automatic save.

Install both with the flag:

npx snapper-shot --hooks

The installer backs up settings.json before touching it, merges into whatever hooks you already have rather than replacing them, and refuses to write at all if that file contains broken JSON. hooks/README.md covers the manual version.

Requirements

Claude Code, plus Node 16 or newer if you use the installer. The skill itself needs nothing beyond Bash and a text editor. There are no API keys, no network calls and no telemetry anywhere in it. Your snapshots are plain Markdown files that never leave the project they describe.

Contributing

Issues and pull requests are welcome. The skill is a Markdown file and a template, so changing how it behaves usually means editing prose rather than writing code.

License

MIT. See LICENSE.