Customize Claude Code's compaction experience by automatically exporting full conversations before compaction and injecting context pointers afterward.
When Claude Code compacts your conversation (at ~95% context), the built-in summary often loses critical details:
- File paths and code changes
- Error messages and debugging steps
- Architectural decisions and their rationale
- Tool call inputs and outputs
claude-compact installs hooks that:
- Before compaction: Export the full conversation to a readable markdown file
- After compaction: Tell Claude where to find the exported file
Claude can then read the full conversation history when needed, preserving all context.
pip install claude-compact# Install the hooks
claude-compact install
# Check status
claude-compact status
# That's it! Now when Claude Code compacts, your conversations are preserved.claude-compact install # Install hooks into Claude Code
claude-compact uninstall # Remove hooks, config, and exports
claude-compact status # Check installation statusclaude-compact config show # Show all settings
claude-compact config set KEY VALUE # Set a configuration value
claude-compact config reset # Reset to defaultsAvailable settings:
| Setting | Default | Description |
|---|---|---|
export_dir |
~/.claude/hooks/exports |
Where to save exports |
export_format |
markdown |
Format: markdown, json, html |
detailed |
true |
Include tool calls in export |
trigger |
both |
Hook trigger: auto, manual, or both |
cleanup_enabled |
true |
Auto-cleanup old exports |
cleanup_mode |
age |
Cleanup by age or count |
cleanup_max_age_days |
30 |
Delete exports older than N days |
cleanup_max_count |
50 |
Keep only N most recent exports |
prompt_template |
(see below) | Message injected after compaction |
claude-compact exports list # List all exports
claude-compact exports list -n 10 # List last 10 exports
claude-compact exports clean # Clean based on config
claude-compact exports clean -d 7 # Delete exports older than 7 days
claude-compact exports clean -k 20 # Keep only 20 most recent
claude-compact exports open 1 # Open most recent export in editorCustomize the message Claude sees after compaction:
claude-compact prompt show # Show current template
claude-compact prompt set # Edit template (opens editor)
claude-compact prompt reset # Reset to defaultDefault template:
IMPORTANT: This conversation was compacted. The FULL conversation before compaction is saved at:
{export_path}
If you need details from earlier in the conversation (file paths, error messages, code changes, tool calls, decisions made, etc.), use the Read tool to read that file.
Available variables:
{export_path}- Full path to the exported file{session_id}- Session ID{timestamp}- Export timestamp
- Hooks:
~/.claude/hooks/claude-compact-*.py - Config:
~/.claude/hooks/claude-compact-config.json - Exports:
~/.claude/hooks/exports/(configurable) - Claude settings:
~/.claude/settings.json
- Check installation:
claude-compact status - Verify settings.json has the hooks:
cat ~/.claude/settings.json | grep claude-compact - Try reinstalling:
claude-compact uninstall && claude-compact install
- Ensure
claude-conversation-extractoris installed:pip install claude-conversation-extractor - Check if you can run it manually:
claude-extract --list
The injected context is invisible to you but visible to Claude. Ask Claude: "Do you see any context about an exported conversation?"
# Remove hooks, config, and exports
claude-compact uninstall
# Remove the package
pip uninstall claude-compactThe uninstall command removes:
- Hook scripts (
~/.claude/hooks/claude-compact-*.py) - Config file (
~/.claude/hooks/claude-compact-config.json) - Exports folder (
~/.claude/hooks/exports/)
MIT
Contributions welcome! Please open an issue or PR.