Bookmark
Context snapshots for Claude Code.
You've been deep in a coding session. Claude knows your architecture, the decisions you've made, the bugs you've fixed, the open items left. Then the context window compacts — or you close your terminal and come back tomorrow.
Claude forgets everything.
Bookmark fixes this. It captures snapshots of your session context automatically and restores them when you return. No manual steps. No copy-pasting context. You pick up exactly where you left off.
The Problem
Claude Code sessions are ephemeral. Context is lost when:
- Compaction happens — the conversation gets too long and Claude summarizes it, losing detail
- You close your terminal — start a new session and Claude has no memory of the last one
- Your computer restarts — everything from that deep debugging session is gone
- You switch between projects — come back a day later and Claude doesn't know what "we" decided
This creates a painful pattern: every new session starts with you re-explaining what you were working on, what you decided, what's still left to do.
How Bookmark Works
Install it. Forget about it. It just works.
Bookmark runs as an external process — zero tokens consumed from your context window. Four hooks handle everything automatically:
| Hook | When | What |
|---|
| PreCompact | Before context compaction | Captures full context before it's compressed |
| SessionStart | New session begins | Restores prior context so Claude knows what you were doing |
| UserPromptSubmit | Every user message | Checks if a time-based snapshot is due |
| Stop | Session ends | Final snapshot preserving everything |
When you open a new terminal and run claude, Bookmark restores your prior context. Claude greets you knowing what you were working on, what decisions were made, and what's left to do.
What Gets Captured
Each snapshot extracts from the conversation transcript — no LLM calls needed:
- Decisions made — "chose Postgres over SQLite because...", "going with React Query for..."
- Current status — what was being worked on when the session ended
- Open items — TODOs, next steps, unfinished work
- Unknowns and blockers — things that were unclear or blocking progress
- Files changed — which files were created, edited, or read
- Errors encountered — what broke and whether it was resolved
- Tool usage — aggregate counts of Read, Edit, Bash, etc.
All extraction uses pattern matching on the transcript. Zero API calls, zero cost, zero latency.
File paths in snapshots are now project-relative
As of v0.3.3, file paths in .bookmark/snapshots/SNAP_*.json are stored
relative to project_path (e.g. src/foo.ts instead of
/Users/me/dev/git-folder/myapp/src/foo.ts). Older snapshots may carry
pre-move absolute paths that went stale when a project was relocated
(e.g. ~/Desktop/git-folder/... → ~/dev/git-folder/...); those are not
auto-rewritten — they're left intact so the historical record stays
honest. Going forward, a project move only invalidates project_path
itself, not the per-file entries inside each snapshot.
Install
Via Claude Code plugin marketplace (recommended):
/plugin marketplace add tyroneross/bookmark
/plugin install bookmark@bookmark
Via npm (in a project):
npm install @tyroneross/bookmark
Hooks are configured automatically. Start a Claude Code session and you're covered.
Via npm (globally):
npm install -g @tyroneross/bookmark
Then activate in any project by typing /bookmark:activate in a Claude Code session, or run bookmark setup in your project directory.
Commands
Use these inside Claude Code:
| Command | What it does |
|---|
/bookmark:snapshot | Take a manual snapshot right now |
/bookmark:restore | Restore from latest or a specific snapshot |
/bookmark:status | Show snapshot count, compaction cycles, last snapshot time |
/bookmark:list | List available snapshots with details |
/bookmark:activate | Set up Bookmark for the current project |
CLI
bookmark status # Show stats
bookmark list # List snapshots
bookmark show --latest # Show latest snapshot content
bookmark show SNAP_ID # Show specific snapshot
bookmark config # Show current configuration
bookmark config --interval 15 # Change snapshot interval to 15 minutes
bookmark setup # Interactive configuration
Adaptive Thresholds
Bookmark gets smarter the more your context compacts. It tracks compaction cycles and adjusts when snapshots trigger:
