Context Guardian

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

Security Scan

The skill's behavior is broadly consistent with a context-monitoring helper, but there are inconsistencies and missing declarations (notably an undeclared dependency on jq and an unclear reliance on an OpenClaw CLI/session_status mechanism) that should be resolved before trusting it.

Purpose & Capability

The name/description (context monitoring with 3-level alerts) matches what the files implement: a heartbeat-invoked check that parses context usage and writes a small state file. However, the implementation depends on external tooling (openclaw CLI/session_status and jq) that are not declared in the manifest or SKILL.md dependencies, which is an incoherence: a monitoring skill can legitimately need a way to read session status and a JSON tool, but those requirements should be declared.

Instruction Scope

SKILL.md instructs agents to call session_status, parse a percentage, and update a state file in workspace memory; the script implements that workflow. The skill reads/writes only local config and a workspace memory JSON file and does not attempt network calls or access unrelated system secrets. It will silently exit if it cannot obtain usage (so it does not escalate when missing context).

Install Mechanism

No install spec (instruction-only + a shell script). Nothing is downloaded or extracted. This is low-risk from an install-execution perspective.

Credentials

The skill declares no required env vars or credentials, but the script reads OPENCLAW_WORKSPACE and HOME and expects tools (openclaw CLI and jq). The absence of declared dependencies (jq) and no clear guidance in SKILL.md about tool availability is disproportionate to what is claimed; it may simply be an oversight, but it is an important practical/integrity gap.

Persistence & Privilege

always is false and the skill only saves a small JSON state to the user's OpenClaw workspace memory directory. It does create the workspace memory directory if missing, which is normal for a stateful helper and does not modify other skills' configs.

Scan Findings in Context

[calls-openclaw-cli] expected: SKILL.md asks agents to use a session_status tool; the script calls `openclaw session status`. Calling an OpenClaw CLI or session_status is expected for a context-monitoring skill, but the dependency is not documented in manifest or SKILL.md.

[uses-jq] unexpected: The script extensively uses `jq` to parse JSON. That is reasonable for reading JSON config and state, but `jq` is not declared in required binaries or described in SKILL.md; the skill may fail silently if jq is unavailable.

[uses-grep--oP] unexpected: The script uses `grep -oP` (PCRE flag). Not all environments ship grep with -P support; this is an implementation fragility rather than malicious, but it increases the chance the script won't work as intended.

[writes-workspace-memory] expected: The skill writes a state file to {workspace}/memory/context-guardian-state.json to track alerts. This is expected for the stated purpose (prevent duplicate alerts).

What to consider before installing

This skill appears to do what it says (monitor context usage and show alerts) and does not attempt to exfiltrate data or use remote endpoints. However, before installing: 1) ensure the environment provides the tools the script expects — notably `jq` and either the OpenClaw CLI (openclaw session status) or an equivalent session_status tool — otherwise the script will silently do nothing; 2) be comfortable with a skill that will create and write a small JSON state file in your OpenClaw workspace (~/.openclaw/workspace/memory by default); 3) verify the script's grep usage works on your platform (grep -P may be unsupported); and 4) because the skill's source/owner and homepage are unknown, consider reviewing or running the script in a sandboxed environment first or asking the author to explicitly list dependencies and clarify whether session_status must be available as a CLI or provided by the agent. If those gaps are addressed (declare jq, document session_status/CLI expectations), the skill would be coherent and low-risk.

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)

thresholds:

• Customize alert levels (default: 60, 70, 85)

alertMethod:

• "message" - Send as message (default)
• "log" - Log only
• "notification" - System notification (future)

alertStyle:

• "emoji" - Emoji + concise text (default)
• "text" - Plain text
• "detailed" - Full explanation

---

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:

• Check that HEARTBEAT.md includes context monitoring
• Verify heartbeat is running
• Check state file for errors

Too many alerts:

• Increase thresholds in config
• Check preventDuplicates is enabled

Alerts not accurate:

• Verify session_status is working
• Check OpenClaw version compatibility

---

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:

• OpenClaw 2026.2.0+
• session_status tool
• Bash

Performance:

• Zero overhead (only checks during heartbeat)
• Minimal state storage (~1KB)

Privacy:

• All data stored locally
• No external calls
• No telemetry

---

Roadmap

v1.1.0:

• Historical trend tracking
• Usage prediction
• Independent cron mode

v1.2.0:

• Auto-trigger context-optimizer
• Visual trend graphs
• Multi-session monitoring

---

Contributing

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

---

License

MIT