---
name: context-guardian
description: Proactive context monitoring and automatic compaction before overflow. Maintains lossless retrieval pointers and ensures continuous operation in long sessions.
---

# Context Guardian

This skill proactively monitors context window usage and automatically compacts context before overflow occurs.

## When to Use

Use this skill when:
- You are in a long-running session (>50 messages)
- Context is approaching token limits
- You need to preserve important information during compaction
- You want automatic context management without manual intervention

## How It Works

Context Guardian operates in three modes:

### 1. Monitoring Mode (Passive)

Track context usage without intervention:

```
context_monitor() → {
  current_tokens: number,
  max_tokens: number,
  usage_percent: number,
  messages_count: number,
  estimated_remaining: number
}
```

### 2. Pre-emptive Mode (Active at 70%)

When context reaches 70% threshold, automatically compact:

- Preserve recent tool outputs
- Summarize older conversation segments
- Create lossless pointers to original content
- Maintain ability to retrieve full context if needed

### 3. Emergency Mode (Active at 90%)

When context reaches 90%, aggressively compress:

- Keep only essential context (current goal, key decisions)
- Store compressed summaries
- Create recovery checkpoints
- Request user confirmation before critical operations

## Usage

Invoke this skill to activate context management:

```
skill: context-guardian
```

### Monitoring Functions

```javascript
// Check current context status
context_status() → {
  tokens: number,
  percent_used: number,
  mode: "normal" | "monitoring" | "pre-emptive" | "emergency"
}

// Get compaction recommendations
compaction_recommend() → {
  priority: "none" | "low" | "medium" | "high" | "critical",
  suggested_actions: string[],
  estimated_savings: number
}
```

### Compaction Functions

```javascript
// Compact context with lossless pointers
compact_context({
  preserve_recent: 10,
  summarize_older: true,
  create_pointers: true
}) → {
  before_tokens: number,
  after_tokens: number,
  pointers_created: number,
  recovery_available: boolean
}

// Retrieve original content from pointer
retrieve_from_pointer(<pointer_id>) → original_content
```

### Checkpoint Functions

```javascript
// Create recovery checkpoint
create_checkpoint({
  label: "pre-refactor",
  include_context: true,
  include_files: ["src/main.ts"]
}) → checkpoint_id

// Restore from checkpoint
restore_checkpoint(<checkpoint_id>) → restored_state
```

## Compaction Strategy

When compacting, preserve in this priority order:

1. **Current task** - What you're actively working on
2. **Recent decisions** - Key choices and reasoning
3. **Tool outputs** - Results from file operations
4. **Errors/resolutions** - Problems solved
5. **User preferences** - Explicit requirements

Summarize or discard:
- Redundant tool calls
- Similar error attempts
- Outdated context
- Low-value messages

## Lossless Retrieval

Context Guardian maintains pointers to original content:

- **Message pointers** - Can retrieve any summarized message
- **File snapshots** - Can restore file state at checkpoint
- **Tool call history** - Can replay tool operations
- **Decision log** - Can retrieve reasoning at any point

## Best Practices

- Call `context_status()` regularly in long sessions
- Create checkpoints before major operations
- Review compaction suggestions at 70% threshold
- Use pointers to retrieve historical information when needed
- Avoid letting context reach emergency mode proactively