Proactive session capacity monitoring and management for OpenClaw. Prevents context window lockups by warning at configurable thresholds (75%, 85%, 90%, 95%), automatically backing up sessions before resets, and managing session resumption prompts. Use when working on long-running projects, managing multiple conversation channels (Discord, Telegram, webchat), or preventing lost work from full context windows. Includes CLI tools for capacity checks, cross-session dashboards, archive management, a
Proactive session capacity monitoring for OpenClaw.
⚠️ Security & Architecture Notice
Tide Watch is a HYBRID SKILL with two operational modes:
Mode 1: Directives-Only (Recommended for Most Users)
Description: AGENTS.md and HEARTBEAT.md directives only
Code Execution:NONE - Uses OpenClaw's built-in tools only (no CLI installation)
File Access: Reads OpenClaw session files via agent's built-in tools
Installation: Copy template directives to workspace config files
Security: Lowest risk - no code installation or execution required
What it does:
- ✅ Monitors session capacity via session_status tool
✅ Warns at thresholds (75%, 85%, 90%, 95%)
✅ Auto-loads resumption prompts on session reset
✅ All operations through OpenClaw's native tools
Mode 2: CLI Tools (Optional)
Description: Node.js command-line tools for manual management
Code Execution:YES - Executable JavaScript code
File Access: Direct read/write to ~/.openclaw/agents/main/sessions/Installation:git clone + npm link (requires Node.js)
Security: Moderate risk - requires code inspection before install
What it does:
- CLI commands: tide-watch status, tide-watch dashboard, etc.
Manual capacity checks
Session archive management
Resumption prompt editing (⚠️ see CVE-2026-001 below)
Mode Comparison
Feature
Directives-Only
CLI Tools
Node.js required?
❌ No
✅ Yes (14+)
Installation
Copy templates | npm link |
| Code execution | ❌ None | ✅ JavaScript |
| File access | Via built-in tools | Direct filesystem |
| Security risk | Lowest | Moderate |
| Use case | Passive monitoring | Active management |
Choose Directives-Only if: You only need capacity warnings and resumption prompts. Choose CLI Tools if: You need manual session management, archiving, or dashboard views.
🚨 CRITICAL SECURITY NOTICE: CVE-2026-001
Vulnerability: Shell injection in editResumePrompt function Affected Version: v1.0.0 ONLY Current Version: v1.0.1 (PATCHED) Severity: HIGH (CVSS 7.8) Status: ✅ FIXED
Summary: v1.0.0 contained a shell injection vulnerability in the CLI's resume-prompt edit command. An attacker who could control the --session parameter could execute arbitrary commands. This has been fixed in v1.0.1 by replacing execSync with spawnSync.
If you installed v1.0.0:Update immediately to v1.0.1.
- --current - Auto-detect current session (v1.3.4+)
- Requires: OPENCLAW_SESSION_ID environment variable
- Example: tide-watch check --current
- Use case: Heartbeat monitoring (check THIS session)
- Fallback: Graceful error with helpful message if env var not set
Filtering:
- --all - Show all sessions regardless of capacity
- Binary:tide-watch (installed globally via npm link)
Installation:git clone + INLINECODE90
Why zero runtime dependencies?
- Uses only Node.js built-in modules (fs, path, child_process)
No external API clients
No network libraries
Minimal attack surface
Recommendation
Most users should use Directives-Only Mode. This provides automatic capacity monitoring without installing any code. Only install CLI tools if you specifically need manual capacity management features.
What It Does
Monitors your OpenClaw session context windows and warns you before they overflow:
- 🟡 75% — Heads up, consider wrapping up soon
🟠 85% — Recommend finishing current task and resetting
🔴 90% — Session will lock soon, ready to reset
🚨 95% — Critical! Save to memory NOW
Installation
Step 1: Add Monitoring Directive to AGENTS.md
Copy the directive template from AGENTS.md.template and add it to your workspace AGENTS.md file:
CODEBLOCK1
Or manually add the monitoring section from the template.
This tells me (your agent) what to look for and when to warn you.
Step 2: Add Heartbeat Task to HEARTBEAT.md
Copy the heartbeat template from HEARTBEAT.md.template and add it to your workspace HEARTBEAT.md file:
CODEBLOCK2
Or manually add the Tide Watch heartbeat section from the template.
This tells me to check capacity automatically on a schedule.
Step 3: Configure Settings (Optional)
Default settings work for most users, but you can customize in your AGENTS.md:
Set which thresholds trigger backups (default: [90, 95])
Configure retention (default: 7 days)
Enable compression to save disk space (default: off)
Channel-specific overrides (advanced):
- Different settings per channel (Discord vs. webchat vs. DM)
Usage
Once installed, I will:
1. Check capacity hourly during active conversations
Warn at thresholds (75%, 85%, 90%, 95%)
Suggest actions:
- Save important context to memory
- Switch to lower-usage channels
- Provide session reset commands
- Generate session resumption prompts
Manual Check
Ask me to check session status anytime:
CODEBLOCK3
Reset Session with Context Preservation
When warned about high capacity:
CODEBLOCK4
I'll:
1. Save current work to memory
Backup the session file (if not already backed up)
Provide a session resumption prompt
Reset the session
Load Session from Backup
If you need to load a previous session state from backup:
CODEBLOCK5
I'll:
1. List available backups with timestamps and sizes
Load the selected backup
Guide you through reconnecting to load the session
Backup locations:
- Path: INLINECODE99
Format: INLINECODE100
Retention: Configurable (default: 7 days)
How It Works
Automatic Monitoring (Heartbeat)
When you add Tide Watch to your HEARTBEAT.md, I automatically:
1. Parse your configuration (from AGENTS.md)
- Check frequency: How often to monitor
- Warning thresholds: When to warn you
- Backup settings: When to backup, retention, compression
- See PARSING.md for detailed parsing logic
2. Check capacity on schedule (default: every hour)
- Run session_status to get token usage
- Calculate percentage: INLINECODE103
3. Compare against your thresholds
- Use your configured thresholds (not hardcoded defaults)
- Determine which threshold(s) have been crossed
- Assign severity dynamically based on position (first=🟡, last=🚨)
3. Warn you (once per threshold)
- Issue warning message for new threshold crossings
- Track which thresholds already warned this session
- Don't repeat warnings if capacity stays at same level
4. Auto-backup (if enabled and triggered)
- Check if capacity crossed any backup trigger thresholds
- Create backup: ~/.openclaw/agents/main/sessions/backups/<session-id>-<threshold>-<timestamp>.jsonl
- Verify backup integrity
- Log backup completion
- Track which thresholds backed up (don't duplicate)
5. Suggest actions
- Save context to memory
- Switch to lower-usage channel
- Provide session reset commands
- Generate session resumption prompts
6. Cleanup old backups
- Remove backups older than retention period (default: 7 days)
7. Return to silent mode
- If capacity is below all thresholds, return HEARTBEAT_OK
- No output, no interruption
Manual Checks
You can also ask me to check anytime:
CODEBLOCK6
Key Features
- Model-agnostic: Works with any provider (Anthropic, OpenAI, DeepSeek, etc.)
Non-intrusive: Silent checks, only speaks up at thresholds
Configurable: Adjust thresholds, frequency, and actions to your workflow
Stateful: Tracks which thresholds warned, resets tracking when session resets
Why You Need This
Problem: Context windows fill up silently. Once at 100%, sessions lock and stop responding. You lose work mid-task.
Solution: Proactive monitoring catches capacity issues early, giving you time to save work, switch channels, or reset cleanly.
Real incident: Discord #navi-code-yatta hit 97% capacity and locked mid-task (2026-02-23). Had to manually reset, losing conversation context.
