claude-compact

Customize Claude Code's compaction experience by automatically exporting full conversations before compaction and injecting context pointers afterward.

The Problem

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

The Solution

claude-compact installs hooks that:

1. Before compaction: Export the full conversation to a readable markdown file
2. After compaction: Tell Claude where to find the exported file

Claude can then read the full conversation history when needed, preserving all context.

Installation

pip install claude-compact

Quick Start

# Install the hooks
claude-compact install

# Check status
claude-compact status

# That's it! Now when Claude Code compacts, your conversations are preserved.

Commands

Installation

claude-compact install    # Install hooks into Claude Code
claude-compact uninstall  # Remove hooks, config, and exports
claude-compact status     # Check installation status

Configuration

claude-compact config show          # Show all settings
claude-compact config set KEY VALUE # Set a configuration value
claude-compact config reset         # Reset to defaults

Available 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

Exports Management

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 editor

Prompt Customization

Customize 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 default

Default 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

How It Works

File Locations

• Hooks: ~/.claude/hooks/claude-compact-*.py
• Config: ~/.claude/hooks/claude-compact-config.json
• Exports: ~/.claude/hooks/exports/ (configurable)
• Claude settings: ~/.claude/settings.json

Troubleshooting

Hooks not running?

1. Check installation: claude-compact status
2. Verify settings.json has the hooks: cat ~/.claude/settings.json | grep claude-compact
3. Try reinstalling: claude-compact uninstall && claude-compact install

Export not created?

1. Ensure claude-conversation-extractor is installed: pip install claude-conversation-extractor
2. Check if you can run it manually: claude-extract --list

Claude doesn't see the context?

The injected context is invisible to you but visible to Claude. Ask Claude: "Do you see any context about an exported conversation?"

Uninstalling

# Remove hooks, config, and exports
claude-compact uninstall

# Remove the package
pip uninstall claude-compact

The uninstall command removes:

• Hook scripts (~/.claude/hooks/claude-compact-*.py)
• Config file (~/.claude/hooks/claude-compact-config.json)
• Exports folder (~/.claude/hooks/exports/)

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.