context-manager — Claude Code Plugin

Proactive context window management via MCP tools + hooks. Gives Claude explicit tools to save/load structured checkpoints that survive compaction, track duplicate tool usage, and mark subtask completion for safe context reduction.

Background

This plugin is grounded in three papers:

• Dynamic Context Pruning (arXiv 2305.15805) — origin of the "DCP" name; demonstrates learnable token pruning achieving up to 80% context reduction without quality loss
• CAT / Context-as-Tool (arXiv 2512.22087) — primary architectural influence; proposes a structured 3-segment workspace where the model actively manages its own context via tool calls
• Complexity Trap (arXiv 2508.21433) — validates that simple observation masking (removing stale tool outputs) matches LLM-based summarization quality, justifying the hook-based approach here

Why it helps in practice: State (task progress, decisions, file context) is written to disk before compaction and restored afterward, so nothing is lost. Duplicate tool reads are detected and warned, reducing wasted tokens on re-reading the same files. Subtask boundaries give the model safe, predictable points to compact without dropping critical context.

Requirements

• Node.js >= 20
• jq (required for hook scripts)
• bash (required for hook scripts)
• Claude Code with plugin support

Install

git clone https://github.com/DxTa/claude-dynamic-context-pruning.git ~/.claude-plugins/context-manager
cd ~/.claude-plugins/context-manager && ./setup.sh
claude --plugin-dir ~/.claude-plugins/context-manager

The --plugin-dir flag loads all three layers: MCP server, hooks, and skill. All three are required for correct operation — hooks handle auto-save/restore around compaction, and the skill teaches the model when and how to use the tools.

What's Included

Layer	Purpose	Files
MCP Server	6 tools for the model to manage its context	server/
Hooks	Auto-save before compaction, auto-restore after, track duplicates	hooks/
Skill	Behavioral instructions teaching the model when/how to use the tools	skills/
Config	Plugin manifest, MCP registration, hook definitions	Root files

MCP Tools

• save_checkpoint — Save structured state (task, files, decisions, errors)
• load_checkpoint — Recover state after compaction or between sessions
• mark_complete — Signal subtask completion for safe context compaction
• get_context_stats — View session stats and duplicate-read warnings
• list_checkpoints — Enumerate all saved checkpoints
• track_tool_usage — Record tool usage events (usually called by hooks)

Hooks

• PreCompact — Auto-extracts state from transcript before compaction
• SessionStart(compact) — Injects recovery text after compaction
• PostToolUse(Read|Bash) — Tracks duplicate reads, warns at 3+

How It Works

1. Model reads the skill → learns context management protocol
2. Model calls save_checkpoint at subtask boundaries
3. Model calls mark_complete when work is done
4. On compaction: PreCompact hook auto-saves → compaction runs → SessionStart hook injects recovery
5. Model calls load_checkpoint after compaction to restore full context
6. get_context_stats shows dedup warnings → model stops re-reading

State persists in .claude/context-state/ within the project directory.

Platform Support

Platform	Verdict
Linux / Ubuntu	✅ Full support
macOS	✅ Full support — install jq via brew install jq
Windows (WSL2)	✅ Full support
Windows (native)	❌ Not supported — no bash
Windows (Git Bash)	❌ Not supported — jq unavailable by default

Hooks require bash and jq. Platforms without both are not supported.

Development

cd server
pkgx npm install
pkgx npm run bundle   # Single-file esbuild bundle (recommended, no runtime node_modules)
pkgx npm run build    # TypeScript tsc compilation

License

MIT