{
"markdown": "\n\n# Compact Guardian\n\n**Prevent task loss during context compaction in Claude Code**\n\n[](https://docs.anthropic.com/en/docs/claude-code)\n[](https://github.com/ibarapascal/compact-guardian)\n[](https://github.com/ibarapascal/compact-guardian/releases)\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/)\n[](https://github.com/ibarapascal/compact-guardian/pulls)\n\n
\n\n---\n\n## Overview\n\nClaude Code plugin that protects your in-progress tasks from being lost during context compaction.\n\n**The problem:**\n- Long sessions hit context limits, triggering automatic compaction\n- The compact summary may falsely claim tasks are \"completed\" when they're not\n- After compaction, the AI trusts the summary and skips unfinished work\n\n**What it does:**\n- Saves your recent instructions and AI's progress before compaction\n- Automatically restores that context after compaction via stdout injection\n- The AI can then cross-check what was actually done vs. what the summary claims\n\n**How it works:**\n\n```\nPreCompact hook -> compact_save.py -> saves snapshot to file\n |\n Context compaction happens\n |\nSessionStart(compact) hook -> compact-restore.sh -> restores snapshot via stdout\n |\n AI sees both compact summary AND original context\n -> can verify what's actually done\n```\n\n---\n\n## Installation\n\n**From GitHub**:\n```bash\nclaude plugin install https://github.com/ibarapascal/compact-guardian\n```\n\nThat's it. The plugin runs automatically whenever compaction occurs.\n\n---\n\n## What Gets Saved\n\n| Content | Detail | Purpose |\n|---------|--------|---------|\n| User messages | Last 5 (filtered) | Your recent instructions |\n| AI response | Last text (up to 1000 chars) | AI's latest progress |\n| Checklists | `- [ ]` / `- [x]` items | Task completion state |\n| Tool calls | Last 20 summaries | What the AI already did |\n\n**Example snapshot** (injected after compaction):\n\n```markdown\n# Pre-Compaction Context Snapshot\n\n> **IMPORTANT**: Cross-check the compact summary against data below.\n> If the summary claims a task is done but no matching actions appear here, treat it as NOT done.\n> Resume work from where this snapshot shows.\n\n> 2026-02-07 14:30:00 | Session: abc12345 | CWD: /Users/you/project\n\n## Recent User Instructions\n\n**[1]**\nFix the authentication bug in login.tsx and add tests\n\n**[2] (latest)**\nAlso update the API docs\n\n## AI Progress\n\n- [x] Fix login bug\n- [ ] Add unit tests\n- [ ] Update API docs\n\n**Last response:**\nI've completed the first task (fixing the login bug). Next I'll work on\nthe unit tests...\n\n## Recent Actions\n\n- Read: src/components/login.tsx\n- Edit: src/components/login.tsx\n- Bash: npm test\n```\n\n---\n\n## How It Works\n\n### 1. PreCompact Hook (`compact_save.py`)\n\nTriggered before every compaction:\n\n- Reads the session transcript (JSONL), optimized for large files (only reads last 2MB)\n- Extracts the last 5 genuine user messages (filters out system messages, tool results, etc.)\n- Extracts AI text response, checklist items, and tool call summaries\n- Writes a session-specific snapshot to `~/.claude/compact-snapshot-.md`\n- Cleans up stale snapshots (older than 10 minutes)\n\n### 2. SessionStart Hook (`compact-restore.sh`)\n\nTriggered after compaction completes:\n\n- Finds the session-specific snapshot\n- Checks it's less than 10 minutes old\n- Outputs content to stdout (automatically injected into AI context)\n- Deletes snapshot after successful restore\n\n### Technical Details\n\n**Transcript parsing** — Claude Code stores conversation history as JSONL (one JSON object per line). The save script parses each line, dispatches by message `type` (`user` / `assistant`), and extracts the relevant data. For large transcripts (>2MB), only the tail portion is read to stay within the 15-second hook timeout.\n\n**User message filtering** — In the JSONL format, system-injected content (``, CLAUDE.md, skill listings, etc.) appears as separate text blocks within a user message's content array. The plugin filters at the **individual text block level** — stripping system blocks while preserving the user's genuine text. This prevents legitimate instructions from being lost due to attached system metadata.\n\n**Tool call summarization** — Uses a unified parameter lookup (`file_path`, `command`, `pattern`, etc.) across all tool types, producing one-line summaries like `Read: src/app.tsx` or `Bash: npm test`. No per-tool-type logic needed.\n\n**Snapshot lifecycle** — Write before compaction → survive compaction (stored on disk, outside context window) → read after compaction via stdout injection → delete immediately. 10-minute TTL enforced on both sides. All errors exit silently (`exit 0`) — the plugin never blocks compaction or session start.\n\n---\n\n## Safety\n\n- **Session isolation**: Each session saves to its own snapshot file\n- **10-minute expiration**: Stale snapshots are ignored and cleaned up\n- **Auto-cleanup**: Snapshots are deleted after restore\n- **Minimal context cost**: Capped at 12K chars (~3K tokens)\n- **Non-blocking**: All errors are handled gracefully — if anything fails, the hook exits silently\n- **Read-only**: The save script only reads the transcript, never modifies it\n\n---\n\n## Requirements\n\n- **python3** (pre-installed on macOS and most Linux)\n- **bash**\n\n---\n\n## Platform Support\n\n| Platform | Status |\n|----------|--------|\n| macOS | Supported |\n| Linux | Supported |\n| Windows | Not supported |\n\n---\n\n## Testing\n\n**Manual test:**\n\n```bash\n# Start a Claude Code session\nclaude\n\n# Have a conversation, then run:\n/compact\n\n# After compaction, you should see your recent instructions\n# appear in the AI's context (visible in verbose mode: Ctrl+R)\n```\n\n**Script test:**\n\n```bash\n# Test save with a real transcript\necho '{\"session_id\":\"test\",\"transcript_path\":\"/path/to/session.jsonl\",\"cwd\":\"/tmp\"}' \\\n | python3 scripts/compact_save.py\ncat ~/.claude/compact-snapshot-test.md\n\n# Test restore\necho '{\"session_id\":\"test\"}' | bash scripts/compact-restore.sh\n```\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Make your changes\n3. Test with a real Claude Code session\n4. Submit a pull request\n\nAll contributions must be in English.\n\n---\n\n## License\n\nMIT\n\n---\n\n\n\n**Made for the Claude Code community**\n\n[](https://github.com/ibarapascal/compact-guardian)\n\n[Report Bug](https://github.com/ibarapascal/compact-guardian/issues) · [Request Feature](https://github.com/ibarapascal/compact-guardian/issues)\n\n
\n",
"bytes": 7065,
"sha": "20c20ce037314b952016cf93d2950bacddacd1d6c1945be033ea1f5143e60ca6",
"repo_slug": "ibarapascal/compact-guardian",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_ibarapascal_compact_guardian_compact_gua_07bdc977/readme"
}