context-snapshot

⚡ Fast context storage for Claude Code - Save conversation context with instant retrieval

Why This Tool?

When working with Claude Code, you often need to preserve important conversation context:

• Long discussions you want to reference later
• Critical decisions made during development
• Context that shouldn't be lost between sessions
• Important reminders for Claude to always see

This tool saves context to a persistent file that Claude can read instantly, with automatic clipboard copying for immediate use.

Installation

# Global install (recommended)
npm install -g context-snapshot

# Or use directly with npx
npx context-snapshot "Your context here"

Usage

Basic Usage

# Save context from command line
context-snapshot "This is important context to remember"

# Short alias
ctx "Quick context save"

# From stdin (pipe)
echo "Context from another command" | context-snapshot

# Multi-line context
context-snapshot "Line 1
Line 2
Line 3"

With Claude Code

The saved context is stored in .context/snapshot.md in your project root. Claude can read it anytime:

// In Claude Code, you can reference it:
Read('.context/snapshot.md')

Auto-Whitelisting (Claude Code)

To enable automatic execution without approval prompts:

# If installed globally
npx context-snapshot --whitelist

# Or manually add to Claude Code settings (/settings):
# Auto-approval patterns for Bash:
#   context-snapshot:*
#   npx context-snapshot:*
#   ctx:*

Features

✅ Instant saves - Context saved in <100ms ✅ Persistent storage - Survives between Claude Code sessions ✅ Clipboard integration - Auto-copies to clipboard (macOS/Linux) ✅ Markdown formatted - Easy to read, includes timestamps ✅ Stdin support - Works with pipes and command output ✅ Cross-platform - Works on macOS, Linux, Windows ✅ Zero dependencies - Uses only Node.js built-ins

Output Format

# 📸 Context Snapshot
# Saved: 2025-10-16 17:35:53
# This context is persistent and can be referenced anytime

---

Your context content here

---

# End of snapshot

Use Cases

1. Save Important Decisions

context-snapshot "DECISION: Using PostgreSQL for main DB, Redis for caching.
Reason: Better JSONB support for battle cards."

2. Preserve Long Conversations

context-snapshot "$(pbpaste)"  # Save clipboard content

3. Create Reminders for Claude

context-snapshot "REMINDER: Always run tests before committing.
Never create files in root directory."

4. Log Critical Context

git log -1 --pretty=format:"%h %s" | context-snapshot
# Saves latest commit info for reference

Claude Code Integration

After saving context, Claude can reference it anytime:

You: "What was our decision about the database?"

Claude: [Reads .context/snapshot.md]
"According to the context snapshot from earlier, we decided to use
PostgreSQL for the main database with Redis for caching, due to
better JSONB support for battle cards."

File Location

All snapshots are saved to:

<project-root>/.context/snapshot.md

Add .context/ to your .gitignore if you don't want to commit these files:

echo ".context/" >> .gitignore

Performance

• Write speed: <100ms for most content
• Read speed: Instant (Claude's Read tool)
• Storage: Minimal (typically <10KB per snapshot)
• Memory: Near-zero overhead

Comparison to Alternatives

| Method | Speed | Persistent | Claude Access | Multi-Session | |--------|-------|------------|---------------|---------------| | context-snapshot | ⚡ Fast | ✅ Yes | ✅ Instant | ✅ Yes | | Clipboard only | ⚡ Fast | ❌ No | ⚠️ Manual | ❌ No | | Conversation history | 🐌 Slow | ✅ Yes | ⚠️ Slow | ✅ Yes | | Manual file creation | 🐌 Slow | ✅ Yes | ✅ Yes | ✅ Yes |

Advanced Usage

Append to Snapshot (instead of replacing)

# Read current snapshot, append new content
cat .context/snapshot.md <(echo -e "\n\n---\n\nNew context here") | context-snapshot

Multiple Snapshots

# Save with timestamp-based filename
context-snapshot "Important context" && \
  cp .context/snapshot.md ".context/snapshot-$(date +%Y%m%d-%H%M%S).md"

Integration with Git Hooks

# .git/hooks/post-commit
#!/bin/bash
git log -1 --pretty=format:"%h %s%n%b" | context-snapshot

Troubleshooting

Issue: Clipboard not working Solution: Install pbcopy (macOS) or xclip (Linux). Not required - just optional.

Issue: Permission denied Solution: Run chmod +x $(npm root -g)/@thetadriven/context-snapshot/bin/context-snapshot.js

Issue: File not found in Claude Solution: Ensure you're in the project root directory where .context/ was created

License

MIT

Author

Elias Moosman (@thetadriven)

Contributing

Issues and PRs welcome at https://github.com/thetadriven/thetadrivencoach

⚡ Built for speed. Designed for Claude Code. 🚀