Session Health Monitor

Context window health monitoring for OpenClaw agents — threshold warnings via Telegram, pre-compaction snapshots, and memory rotation.

Security Scan

The skill largely does what it says (local context monitoring and snapshots), but it modifies user app config (~/.claude/settings.local.json) and claims Telegram warnings without providing or requesting a Telegram integration/credential — these behaviors warrant caution.

Purpose & Capability

The scripts and instructions align with the stated goal of monitoring context usage, taking pre-compaction snapshots, rotating memory files, and exposing a statusline. However the SKILL.md mentions 'warnings via Telegram' but the bundled scripts do not implement Telegram network calls or request a Telegram token — the skill expects the agent's existing Telegram messaging tool to be used, which is reasonable but not explicitly documented as a dependency.

Instruction Scope

Runtime instructions ask the agent to append context-footers to outgoing Telegram messages and to modify agent heartbeat loops. The provided setup script (setup-statusline.sh) modifies ~/.claude/settings.local.json to add a statusLine entry and copies a statusline script into ~/.claude — this changes another application's configuration outside the skill's own files, which is scope creep and could surprise users if done without explicit consent.

Install Mechanism

No remote install or downloads are performed (instruction-only with local scripts). The only external dependency is jq for the installer/statusline patches. No network fetches or archives are used, so installation risk is low, but users should still inspect/prompt before running setup-statusline.sh since it writes into home directories.

Credentials

The skill uses sensible, optional environment variables (MEMORY_DIR, KEEP_DAYS, HEALTH_GREEN_MAX, etc.) and local filesystem paths (~/.openclaw, ~/.claude, /tmp). It does not request tokens or secrets in the registry metadata. The use of user home directories for memory and state is proportionate to the purpose.

Persistence & Privilege

Although always:false and no autonomous 'always-on' flag is set, the installer writes a persistent statusline script into ~/.claude and patches settings.local.json, creating persistent behavior across restarts of the Claude Code app. Modifying another tool's settings is a notable privilege and should be done only with explicit user consent and backup.

What to consider before installing

This skill appears to implement local context monitoring and snapshotting, but before installing you should: (1) review the included scripts yourself, (2) back up ~/.claude/settings.local.json if you plan to run setup-statusline.sh (it will overwrite/add a statusLine entry), (3) be aware the skill does not itself send Telegram messages or require a Telegram token — it only instructs the agent to append footers to messages sent via whatever Telegram integration you already have, and (4) run the installer in a sandbox or with explicit consent to avoid surprising persistent changes. If you do not use Claude Code or do not want the skill to modify ~/.claude, avoid running setup-statusline.sh and use the scripts manually instead.

Monitor your OpenClaw agent context window health, get warnings via Telegram when usage is high, save critical facts before compaction, and keep memory directories clean.

Overview

Four capabilities for OpenClaw agent sessions:

1. Context Threshold Warnings — Agents append usage footer to Telegram messages and warn at configurable thresholds
2. Compaction Detection — Track usage drops to infer when context was compacted
3. Pre-Compaction Snapshots — Save key facts and decisions to daily memory files before they're lost
4. Memory Rotation — Archive old daily memory files to prevent clutter

Quick Setup (OpenClaw)

1. Add shared skill reference

Add to your shared/INDEX.md:

| Context window health, compaction detection, pre-compaction snapshots | `skill-session-health.md` |

2. Create shared skill doc

Create shared/skill-session-health.md:

# Session Health Monitor

## Context Health Thresholds
| Level  | Condition                          | Action                        |
|--------|------------------------------------|-------------------------------|
| GREEN  | <50% used AND 0 compactions        | Normal operation              |
| YELLOW | >=50% used OR >=1 compaction       | Save key facts via snapshot   |
| RED    | >=75% used OR >=2 compactions      | Save facts NOW, session ending|

## Behavioral Rules
1. When context reaches YELLOW+, extract 3-5 key facts (decisions, files changed, blockers)
2. Run: `bash scripts/snapshot.sh "fact1" "fact2"`
3. Append footer to Telegram messages at YELLOW+: `X% Context Window | Nx compacted`
4. Do this BEFORE session ends or context gets compacted
5. After any detected compaction, immediately snapshot what you remember

3. Add heartbeat step

Add to your agent heartbeat/loop:

**Context health check**: Run `session_status` → always append context % to Telegram messages
as footer: `📊 X% Context Window`. If Context >50% OR Compactions >=1, add:
"⚠️ consider /restart after current task." If Context >75% OR Compactions >=2, flag as urgent.

Context Health Thresholds

Level	Condition	Action
GREEN	<50% used AND 0 compactions	Normal operation
YELLOW	>=50% used OR >=1 compaction	Consider saving key facts
RED	>=75% used OR >=2 compactions	Save facts NOW, session ending

Telegram Message Footer

Agents append a footer to every outgoing Telegram message:

📊 42% Context Window                          # GREEN — no extra warning
📊 63% Context Window | 1x compacted           # YELLOW — consider restart
⚠️ 📊 81% Context Window | 2x compacted        # RED — urgent, save facts

This keeps the user informed about session health without requiring manual checks.

Pre-Compaction Snapshot Protocol

When context reaches YELLOW or above, the agent SHOULD:

1. Extract 3-5 key facts from the current session (decisions made, files changed, blockers found)
2. Write them to memory/YYYY-MM-DD.md using scripts/snapshot.sh
3. Include any unfinished work or next steps
4. Do this BEFORE the session ends or context is compacted

Example snapshot content:

## Pre-Compaction Snapshot (14:32)
- Refactored auth module to use JWT instead of sessions (files: src/auth.ts, src/middleware.ts)
- Bug found in rate limiter: counter resets on deploy, not on TTL expiry
- Next: write tests for new auth flow, fix rate limiter reset logic
- Decision: using RS256 for JWT signing (user preference)

When to trigger:

• Context hits 50%+ for the first time in a session
• After any detected compaction
• Before ending a long session
• When the agent detects it has accumulated significant context

Scripts Reference

context-check.sh

Standalone health check, useful in heartbeat loops.

bash scripts/context-check.sh                    # Human-readable output
bash scripts/context-check.sh --json              # Machine-readable JSON
echo '{"context_window":{"used_percentage":72}}' | bash scripts/context-check.sh
# Exit codes: 0=GREEN, 1=YELLOW, 2=RED

snapshot.sh

Save facts to daily memory file.

bash scripts/snapshot.sh "Fact one" "Fact two" "Fact three"
echo -e "Fact one\nFact two" | bash scripts/snapshot.sh -

rotate.sh

Archive old daily memory files.

bash scripts/rotate.sh           # Archives files older than 3 days (default)
KEEP_DAYS=7 bash scripts/rotate.sh  # Keep 7 days instead

Configuration

All configuration is via environment variables with sensible defaults:

Variable	Default	Description
MEMORY_DIR	Auto-detect (see below)	Where to write daily memory files
KEEP_DAYS	3	Days to keep before archiving
HEALTH_GREEN_MAX	50	Max % for GREEN status
HEALTH_RED_MIN	75	Min % for RED status
COMPACTION_DROP	30	% drop that indicates compaction

Memory directory auto-detection order:

1. $MEMORY_DIR environment variable
2. ~/.openclaw/workspace/memory (if exists)
3. ~/.claude/memory (fallback)

Troubleshooting

jq not installed

# macOS
brew install jq
# Linux
sudo apt-get install jq

Reset compaction state

rm /tmp/session-health-*.json

Agent not appending footer

1. Check shared/INDEX.md references skill-session-health.md
2. Check heartbeat includes the context health step
3. Verify session_status tool is available to the agent