Context Guardian 🛡️

Your context guardian. Alerts before errors happen.

Proactive context monitoring that warns you at 60%, 70%, and 85% usage — before context pollution causes errors and hallucinations.

Why You Need This

The Problem:

• Long conversations lead to context pollution
• Quality degrades silently as context fills up
• You don't know when to restart until it's too late
• Errors and hallucinations increase after ~70% usage

The Solution:

• Continuous monitoring of context usage
• Smart 3-level alerts (⚠️ 60%, 🟠 70%, 🔴 85%)
• Actionable suggestions at each level
• Prevents duplicate alerts

Quick Start

For Agents: Heartbeat Integration

When you receive a heartbeat poll, include this check:

1. Call session_status tool to get current context usage
2. Parse the context percentage from the output
3. Compare against thresholds: 60% (warning), 70% (danger), 85% (critical)
4. If threshold exceeded and not a duplicate alert, display the appropriate alert message
5. Update state file to track alert history

Implementation:

During heartbeat:
1. Get context usage from session_status
2. Check if usage >= 60%, 70%, or 85%
3. Load state from memory/context-guardian-state.json
4. Determine if alert should be sent (prevent duplicates)
5. If yes, display alert and update state

For Users: Enable in HEARTBEAT.md

Add to your HEARTBEAT.md:

## Context Monitoring
- Check context usage
- Alert if thresholds exceeded (60%, 70%, 85%)

The agent will automatically handle the rest.

How It Works

Monitoring

The skill calls session_status to check your current context usage percentage.

Alert Levels

⚠️ Warning (60%)

⚠️ Context: 60%
Getting full. Consider wrapping up or starting fresh soon.

🟠 Danger (70%)

🟠 Context: 70%
Pollution risk rising. Recommend:
• Finish current task
• Start new session for next task
• Or compress with context-optimizer

🔴 Critical (85%)

🔴 Context: 85% - CRITICAL
High error risk. STRONGLY recommend:
• Save work
• Start new session NOW
• Quality degradation likely

Smart Duplicate Prevention

The skill tracks alert history and only alerts when:

1. First time reaching a threshold
2. Alert level upgrades (60% → 70% → 85%)
3. Usage drops below threshold then rises again

Configuration

Edit config/default.json or create config/user.json:

{
  "enabled": true,
  "checkInterval": "heartbeat",
  "thresholds": {
    "warning": 60,
    "danger": 70,
    "critical": 85
  },
  "alertMethod": "message",
  "alertStyle": "emoji",
  "preventDuplicates": true,
  "trackHistory": true,
  "suggestions": {
    "autoSuggest": true,
    "suggestCompression": true,
    "suggestRestart": true
  }
}

Options

checkInterval:

• "heartbeat" - Check during heartbeat polls (default)
• "cron" - Independent cron job (future)
• number - Check every N minutes (future)