compaction-advisor

---
name: compaction-advisor
description: Provides context-aware compaction guidance with intelligent checkpointing. Monitors context during long tasks and suggests checkpoints before compaction interrupts your work.
license: MIT
compatibility: Claude Code CLI with hooks enabled
---

# Compaction Advisor

You receive automatic context status via XML tags when context is concerning.

## Message Types

### 1. Context Status (on user prompts)

When you see these tags at the start of a conversation turn:

```
<context-status>CRITICAL: Only 12k tokens free. Run /compact before any task.</context-status>
<context-status>WARNING: 25k tokens free. Only small tasks safe.</context-status>
<context-status>CAUTION: 40k tokens free. Medium tasks OK, compact before large.</context-status>
```

When context is healthy (50k+ free), you won't see any tag.

### 2. Checkpoint Suggestions (during long tasks)

During multi-step work, you may see:

```
<context-checkpoint>
CHECKPOINT RECOMMENDED: Context critically low (18k free) after 12 operations.
Good time to pause and /compact. Summarize progress so far and key context to preserve.
</context-checkpoint>
```

This means you've been working for a while and context is running low.

### 3. PreCompact Warning (emergency)

Just before auto-compaction triggers:

```
<precompact-warning>
AUTO-COMPACTION IMMINENT
Context window is full. Compaction will happen after this message.
</precompact-warning>
```

## How to Respond

### When you see `<context-status>` CRITICAL

Immediately advise:
```
Context is critically low (12k free). Before we proceed, run:
/compact Focus on [relevant context to preserve]
```

### When you see `<context-status>` WARNING

For small tasks: proceed with caution
For medium+ tasks: recommend compaction first

```
Context is at 25k free. For a refactor like this (~50k needed),
run /compact first to avoid mid-task interruption.
```

### When you see `<context-checkpoint>`

This is mid-task. Pause and offer a checkpoint:

```
Good checkpoint - I've completed:
• [List what you've done so far]
• [Key decisions made]
• [Files modified]

Context is at 18k. To continue safely, run:
/compact Focus on [key context for remaining work]

After compacting, I'll continue with [next steps].
```

### When you see `<precompact-warning>`

This is urgent. Quickly summarize:

```
Compaction is about to happen. Quick summary of our progress:
• [What we were working on]
• [What's been completed]
• [What remains to do]

After compaction, remind me to [specific next step].
```

### When you see nothing

Context is healthy. Proceed normally without mentioning it.

## Task Size Reference

| Task | ~Tokens Needed |
|------|----------------|
| Typo fix | 5k |
| Bug fix | 15k |
| New feature | 30k |
| Refactor | 50k |
| Architecture | 80k+ |

## Compact Commands

```
/compact                              # General
/compact Focus on [specific context]  # Preserve specific context
```

Examples:
- `/compact Focus on the auth changes and test failures`
- `/compact Keep the refactoring progress and file structure decisions`

## Key Points

- You automatically receive context state - no need to ask user
- During long tasks, checkpoint suggestions appear after 8+ operations
- Match urgency to the tag level (CRITICAL > WARNING > CAUTION)
- For checkpoints, summarize progress and suggest what to preserve
- For precompact, quickly capture essential context
- For healthy context, work normally without mentioning it