context-guardian

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

```markdown
## 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...

# Context Guardian 🛡️

**Your context guardian. Alerts before errors happen.**

Proactive context monitoring with smart 3-level alerts (60%, 70%, 85%). Know when to restart before quality degrades.

## Features

- 🛡️ **Proactive protection** against context pollution
- 📊 **Real-time monitoring** with zero overhead
- 🚨 **Smart 3-level alerts** (60%, 70%, 85%)
- 🔧 **Highly configurable** thresholds and alert styles
- 🤝 **Integrates** with context-optimizer and context-recovery

## Quick Start

1. Install:
   ```bash
   clawhub install context-guardian
   ```

2. Add to `HEARTBEAT.md`:
   ```markdown
   ## Context Monitoring
   - Check context usage via context-guardian
   ```

3. Done! You'll get alerts when context usage reaches thresholds.

## Why You Need This

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.

Context Guardian monitors your context usage and alerts you **before** errors happen:

- ⚠️ **60%** - Warning: Consider wrapping up
- 🟠 **70%** - Danger: Finish current task, start fresh
- 🔴 **85%** - Critical: High error risk, restart NOW

## Documentation

See [SKILL.md](SKILL.md) for full documentation.

## License

MIT