Context Guardian 🛡️

---

name: context-guardian

version: 1.0.1

description: Proactive context monitoring with smart 3-level alerts. Know when to restart before quality degrades.

author: brucey0017

tags: [monitoring, context, alerts, proactive, quality]

---

# 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:**

**The Solution:**

---

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:**

**thresholds:**

**alertMethod:**

**alertStyle:**

---

Manual Check

You can manually check context status:

bash {baseDir}/scripts/check.sh

---

Integration with Other Skills

context-optimizer

When you reach 70%, the skill suggests using `context-optimizer` to compress your context instead of restarting.

context-recovery

After context recovery, the skill automatically resumes monitoring.

---

Implementation Guide for Agents

Step-by-Step Process

**1. Get Context Usage**

Call `session_status` tool and parse the output:

Example output: "Context: 54k/200k (27%)"
Extract: 27

**2. Determine Alert Level**

if (usage >= 85) level = "critical"
else if (usage >= 70) level = "danger"
else if (usage >= 60) level = "warning"
else level = null

**3. Load State**

Read `{workspace}/memory/context-guardian-state.json`:

{
  "lastCheck": 1709452800,
  "lastUsage": 54,
  "lastAlertLevel": "warning",
  "lastAlertTime": 1709452500,
  "history": [...]
}

**4. Check if Should Alert**

Prevent duplicate alerts:

shouldAlert = false

// First time reaching threshold
if (!lastAlertLevel && level) shouldAlert = true

// Level upgrade (warning → danger → critical)
if (levelNum[level] > levelNum[lastAlertLevel]) shouldAlert = true

// Usage dropped below threshold and rose again
if (lastUsage < threshold - 5 && usage >= threshold) shouldAlert = true

**5. Send Alert**

If `shouldAlert`, display the appropriate message:

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

**6. Update State**

Save new state to `memory/context-guardian-state.json`:

{
  "lastCheck": <current_timestamp>,
  "lastUsage": <current_usage>,
  "lastAlertLevel": <level_if_alerted>,
  "lastAlertTime": <timestamp_if_alerted>,
  "history": [..., {"timestamp": <now>, "usage": <usage>}]
}

Alert Messages

**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

---

State Management

State is stored in `{workspace}/memory/context-guardian-state.json`:

{
  "lastCheck": 1709452800,
  "lastUsage": 54,
  "lastAlertLevel": null,
  "lastAlertTime": null,
  "history": [
    {"timestamp": 1709452800, "usage": 54}
  ]
}

---

Troubleshooting

**No alerts appearing:**

**Too many alerts:**

**Alerts not accurate:**

---

Examples

Heartbeat Integration

Add to `HEARTBEAT.md`:

## Context Monitoring
- Check context usage
- Alert if thresholds exceeded

Custom Thresholds

Create `config/user.json`:

{
  "thresholds": {
    "warning": 50,
    "danger": 65,
    "critical": 80
  }
}

---

Technical Details

**Dependencies:**

**Performance:**

**Privacy:**

---

Roadmap

**v1.1.0:**

**v1.2.0:**

---

Contributing

Found a bug? Have a suggestion? Open an issue or PR on GitHub.

---

License

MIT