@tyroneross/bookmark 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "title": "Bookmark — Context Snapshots",
+  "tagline": "Never lose session context again",
+  "category": "developer-tools",
+  "icon": "bookmark",
+  "screenshots": [],
+  "features": [
+    "Automatic snapshots before compaction",
+    "Adaptive threshold system",
+    "Time-based interval snapshots",
+    "Zero context window tax",
+    "Session restoration on startup",
+    "Optional LLM-enhanced extraction"
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "bookmark",
+  "version": "0.1.0",
+  "description": "Context snapshots for Claude Code — session continuity across compactions and terminals",
+  "author": { "name": "Tyrone Ross" },
+  "homepage": "https://github.com/tyroneross/bookmark",
+  "repository": "https://github.com/tyroneross/bookmark",
+  "license": "MIT",
+  "keywords": ["context", "snapshots", "session-continuity", "compaction", "memory"],
+  "hooks": "../hooks/hooks.json",
+  "skills": "../skills/",
+  "agents": "../agents/"
+}

package/CLAUDE.md

@@ -0,0 +1,69 @@
+# Bookmark — Context Snapshots for Claude Code
+
+## What Bookmark Does
+
+Bookmark automatically captures, compresses, and restores session context so you never lose progress across compactions, terminal closures, or computer shutdowns.
+
+## How It Works
+
+**Automatic hooks** (zero context window tax):
+- **PreCompact** — Snapshots before compaction (async, external process)
+- **SessionStart** — Restores context from latest snapshot
+- **UserPromptSubmit** — Checks time/threshold intervals (fast no-op when nothing triggers)
+- **Stop** — Final snapshot before session ends
+
+**Adaptive thresholds** — Snapshots trigger earlier as compaction happens more:
+- 1st compaction: snapshot at 20% remaining
+- 2nd: 30% remaining
+- 3rd+: 40-50% remaining
+
+**Time-based intervals** — Default every 20 minutes (configurable).
+
+## Storage Location
+
+All data lives in `<project>/.claude/bookmarks/`:
+```
+.claude/bookmarks/
+├── LATEST.md       ← Read this first (hot context, <150 lines)
+├── index.json      ← Snapshot index
+├── state.json      ← Plugin state
+├── snapshots/      ← Full snapshot files (SNAP_*.json)
+└── archive/        ← Old snapshots
+```
+
+## Available Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/bookmark:snapshot` | Take a manual snapshot |
+| `/bookmark:restore` | Restore from latest or specific snapshot |
+| `/bookmark:status` | Show snapshot inventory and stats |
+| `/bookmark:list` | List all snapshots |
+
+## CLI Quick Reference
+
+```bash
+npx @tyroneross/bookmark status          # Stats
+npx @tyroneross/bookmark list            # List snapshots
+npx @tyroneross/bookmark show --latest   # Show latest snapshot
+npx @tyroneross/bookmark show <SNAP_ID>  # Show specific snapshot
+npx @tyroneross/bookmark config          # Show/set configuration
+npx @tyroneross/bookmark init            # Initialize in project
+```
+
+## What Gets Captured
+
+Each snapshot extracts from the transcript:
+- **Current status** — What was being worked on
+- **Decisions made** — Key choices with rationale
+- **Open items** — TODOs with priority
+- **Unknowns/blockers** — Uncertainties and blockers
+- **Files changed** — With operation types
+- **Errors encountered** — Resolved vs unresolved
+- **Tool usage summary** — Aggregate tool call counts
+
+## Smart Mode
+
+Pass `--smart` to use Claude Haiku for higher-quality extraction (~$0.001/snapshot). Requires `ANTHROPIC_API_KEY`.
+
+*bookmark — context snapshot*

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tyrone Ross
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# 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.
+
+## Install
+
+**In a project (recommended):**
+
+```bash
+npm install @tyroneross/bookmark
+```
+
+Hooks are configured automatically. Start a Claude Code session and you're covered.
+
+**Globally:**
+
+```bash
+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.
+
+**As a Claude Code plugin:**
+
+```bash
+claude plugin add github.com/tyroneross/bookmark
+```
+
+## 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
+
+```bash
+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:
+
+| Compaction count | Snapshot triggers at | Behavior |
+|-----------------|---------------------|----------|
+| 0 (never compacted) | 20% context remaining | Conservative — only near compaction |
+| 1 (once) | 30% remaining | Earlier snapshots |
+| 2 (twice) | 40% remaining | Even earlier |
+| 3+ (frequent) | 50% remaining | Aggressive — snapshot at halfway |
+
+Sessions that compact frequently get protected more aggressively. Sessions that never compact barely notice Bookmark is there.
+
+## Time-Based Snapshots
+
+Default: every **20 minutes** of active session time. Configurable:
+
+```bash
+bookmark config --interval 10   # Every 10 minutes
+bookmark config --interval 30   # Every 30 minutes
+```
+
+Or set via environment: `BOOKMARK_INTERVAL=15`
+
+## Smart Mode (Optional)
+
+For higher-quality extraction, pass `--smart` to use Claude Haiku (~$0.001 per snapshot):
+
+```bash
+bookmark config --smart-default   # Enable by default
+```
+
+Requires `ANTHROPIC_API_KEY`. Falls back to pattern matching if unavailable.
+
+## Storage
+
+All data lives in your project at `.claude/bookmarks/`:
+
+```
+.claude/bookmarks/
+├── LATEST.md       # Hot context — what gets restored on SessionStart
+├── index.json      # Snapshot index with stats
+├── state.json      # Plugin state (compaction count, thresholds, timing)
+├── config.json     # Your preferences
+├── snapshots/      # Full snapshot files
+└── archive/        # Old snapshots (>30 days)
+```
+
+Automatically added to `.gitignore` — snapshot data never gets committed.
+
+## Zero Context Tax
+
+This is the key design principle. Every other approach to "memory" for Claude Code injects tokens into your context window, reducing the space available for actual work.
+
+Bookmark runs as an external CLI process. The hooks invoke `npx @tyroneross/bookmark` — a separate Node process that reads the transcript file directly, extracts patterns, and writes snapshot files. The only context injection is ~500-800 tokens on SessionStart to restore prior session context.
+
+All the heavy lifting happens outside the context window.
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BOOKMARK_INTERVAL` | `20` | Snapshot interval in minutes |
+| `BOOKMARK_THRESHOLD` | `0.2,0.3,0.4,0.5,0.6` | Adaptive threshold levels |
+| `BOOKMARK_CONTEXT_LIMIT` | `200000` | Context window size in tokens |
+| `BOOKMARK_SMART` | `false` | Enable smart extraction by default |
+| `BOOKMARK_STORAGE_PATH` | `.claude/bookmarks` | Storage directory |
+| `BOOKMARK_VERBOSE` | `false` | Enable verbose logging |
+| `BOOKMARK_SKIP_SETUP` | `false` | Skip postinstall auto-setup |
+
+## Requirements
+
+- Node.js >= 20
+- Claude Code
+
+## License
+
+MIT

package/agents/snapshot-analyst.md

@@ -0,0 +1,41 @@
+---
+name: snapshot-analyst
+description: Agent for deep analysis of session context and snapshot comparison. Use for detailed context review, decision timelines, and coverage analysis.
+color: "#10B981"
+tools: ["Bash", "Read", "Glob", "Grep"]
+---
+
+# Snapshot Analyst Agent
+
+You analyze context snapshots to help users understand session history.
+
+## Capabilities
+
+1. **Deep Comparison**: Compare snapshots across sessions to track project evolution
+2. **Decision Timeline**: Build a timeline of all decisions made across snapshots
+3. **Coverage Analysis**: Identify topics or files that lack snapshot coverage
+4. **Context Quality**: Assess whether snapshots are capturing enough useful context
+
+## Data Location
+
+All bookmark data is in `.claude/bookmarks/`:
+- `LATEST.md` — Latest compressed summary
+- `index.json` — Snapshot index with stats
+- `state.json` — Plugin state (compaction count, thresholds)
+- `snapshots/SNAP_*.json` — Full snapshot files
+
+## Response Format
+
+1. **Summary**: One paragraph overview
+2. **Details**: Structured findings with file references
+3. **Recommendations**: Actionable next steps
+
+## Commands
+
+```bash
+npx @tyroneross/bookmark list --limit 20    # List all snapshots
+npx @tyroneross/bookmark show <SNAP_ID>     # Show specific snapshot
+npx @tyroneross/bookmark status             # Current state
+```
+
+*bookmark — context snapshot*

package/commands/activate.md

@@ -0,0 +1,20 @@
+---
+description: "Activate Bookmark context snapshots for this project"
+allowed-tools: Bash
+---
+
+Activate Bookmark (context snapshots) for the current project. This configures hooks, creates storage directories, and sets up automatic context capture.
+
+Run the setup command:
+
+```bash
+npx @tyroneross/bookmark setup --defaults
+```
+
+After activation, confirm to the user:
+- Bookmark is now active for this project
+- Snapshots will be captured automatically before compaction, on 20-minute intervals, and at session end
+- Context will be restored automatically when starting a new session
+- Available commands: `/bookmark:snapshot`, `/bookmark:status`, `/bookmark:list`, `/bookmark:restore`
+
+*bookmark — context snapshot*

package/commands/list.md

@@ -0,0 +1,15 @@
+---
+description: "List all context snapshots"
+allowed-tools: Bash
+argument-hint: "[--limit N]"
+---
+
+List context snapshots:
+
+```bash
+npx @tyroneross/bookmark list {{ARGUMENTS}}
+```
+
+Display a compact list showing snapshot ID, trigger type, context percentage, and timestamp.
+
+*bookmark — context snapshot*

package/commands/restore.md

@@ -0,0 +1,30 @@
+---
+description: "Restore context from a snapshot"
+allowed-tools: Bash, Read
+argument-hint: "[SNAP_ID]"
+---
+
+{{#if ARGUMENTS}}
+Load and display the full context from a specific snapshot:
+
+```bash
+npx @tyroneross/bookmark show {{ARGUMENTS}}
+```
+
+Read the snapshot and present the decisions, status, open items, and unknowns to the user. Use this context to continue the work.
+
+{{else}}
+Show the latest snapshot and list available alternatives:
+
+```bash
+npx @tyroneross/bookmark show --latest
+```
+
+```bash
+npx @tyroneross/bookmark list --limit 5
+```
+
+Present the restored context and ask the user which open item to continue with.
+{{/if}}
+
+*bookmark — context snapshot*

package/commands/snapshot.md

@@ -0,0 +1,26 @@
+---
+description: "Take a manual context snapshot"
+allowed-tools: Bash
+argument-hint: "[--smart]"
+---
+
+Take a manual context snapshot of the current session.
+
+{{#if ARGUMENTS}}
+```bash
+npx @tyroneross/bookmark snapshot --trigger manual {{ARGUMENTS}}
+```
+{{else}}
+```bash
+npx @tyroneross/bookmark snapshot --trigger manual
+```
+{{/if}}
+
+After the snapshot is taken, confirm to the user with:
+- The snapshot ID
+- Number of decisions captured
+- Number of files tracked
+- Number of open items
+- Context remaining percentage
+
+*bookmark — context snapshot*

package/commands/status.md

@@ -0,0 +1,19 @@
+---
+description: "Show bookmark snapshot inventory"
+allowed-tools: Bash
+---
+
+Show the current state of context snapshots:
+
+```bash
+npx @tyroneross/bookmark status
+```
+
+Display the results including:
+- Number of snapshots
+- Compaction cycle count
+- Last snapshot time
+- Current adaptive threshold
+- Time until next scheduled snapshot
+
+*bookmark — context snapshot*

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}