Tide Watch

Tide Watch 🌊

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

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.

Full disclosure: See SECURITY-ADVISORY-CVE-2026-001.md

Security Best Practices

For Directives-Only Mode (Safest):

1. ✅ Copy AGENTS.md.template and HEARTBEAT.md.template to workspace
2. ✅ No code installation required
3. ✅ No npm dependencies
4. ✅ Lowest security surface

For CLI Tools Mode (If Needed):

1. ⚠️ Verify version 1.0.1 or later (tide-watch --version)
2. ⚠️ Inspect code before installing:
   • Review lib/capacity.js and lib/resumption.js
   • Check package.json for install hooks (should have none)
   • Run npm test to verify behavior (113 tests)
3. ⚠️ Only use UUID session IDs with --session flag
4. ⚠️ Avoid untrusted input to CLI commands
5. ⚠️ Review backups location (~/.openclaw/agents/main/sessions/archive/)

Operation Types:

Read-Only Operations (✅ Safe, no modifications):

• tide-watch status - Check current session count
• tide-watch check --session <id> - View specific session capacity
• tide-watch check --current - Auto-detect and check current session (v1.3.4+)
• tide-watch dashboard - Visual capacity overview
• tide-watch dashboard --watch - Live updating dashboard
• tide-watch dashboard --raw-size - Show full precision token counts (v1.3.2+)
• tide-watch report - List sessions above threshold
• tide-watch resume-prompt show --session <id> - View resumption prompt

Modifying Operations (⚠️ Moves/creates files):

• tide-watch archive --older-than <time> - Moves sessions to archive/ (time-based)
• tide-watch archive --session <id> - Archive specific session (v1.3.3+)
• tide-watch archive --session <id1> --session <id2> - Archive multiple sessions (v1.3.3+)
• tide-watch resume-prompt edit --session <id> - Opens editor (CVE patched in v1.0.1)
• tide-watch resume-prompt delete --session <id> - Deletes resumption prompt file

New Flags (v1.3.2+):

• --raw-size - Show full precision token counts (e.g., 18,713/128,000 instead of 18.7k/128k)
• --current - Auto-detect current session via OPENCLAW_SESSION_ID environment variable (v1.3.4+)
• --session (enhanced) - Supports partial IDs, multiple sessions for archive, labels/channels (v1.3.3+)

File System Access:

• Reads: ~/.openclaw/agents/main/sessions/*.jsonl (session data)
• Writes: ~/.openclaw/agents/main/sessions/resume-prompts/*.md (resumption prompts)
• Moves: ~/.openclaw/agents/main/sessions/archive/ (archived sessions)

Network Activity: NONE - All operations are local filesystem only.

CLI Reference

Complete flag and option documentation:

Display Options:

• --raw-size - Show full precision token counts with commas (v1.3.2+)

  • Default: Human-readable (e.g., 18.7k/128k, 20.6k/1M)
  • With flag: Full precision (e.g., 18,713/128,000, 20,631/1,000,000)
  • Use case: When exact token counts needed
  • Example: tide-watch dashboard --raw-size

• --json - Output as JSON instead of formatted table

  • Example: tide-watch check --session abc123 --json
  • Useful for scripting and parsing

• --pretty - Pretty-print JSON output (requires --json)

  • Example: tide-watch report --json --pretty

Session Selection:

• --session <key> - Target specific session (enhanced in v1.3.3+)

  • Full UUID: --session 17290631-42fe-40c0-bd23-c5da511c6f7b
  • Partial UUID: --session 17290631-4 (v1.3.3+)
  • Label: --session "#navi-code-yatta" (v1.3.3+)
  • Channel: --session discord (v1.3.3+)
  • Channel + label: --session "discord/#navi-code" (v1.3.3+)
  • Multiple (archive only): --session abc123 --session def456 (v1.3.3+)

• --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
• --threshold <num> - Filter sessions above percentage (default: 75)
• --active <hours> - Only show sessions active within N hours
• --agent <id> - Filter to specific agent (multi-agent setups)
• --exclude-agent <id> - Exclude specific agent (can use multiple times)

Archive Options:

• --older-than <time> - Archive sessions older than time

  • Examples: 4d, 2w, 1mo, 3months
  • Mutually exclusive with --session

• --dry-run - Preview archive without making changes

  • Example: tide-watch archive --older-than 7d --dry-run

• --exclude-channel <name> - Exclude channel from archiving

  • Example: tide-watch archive --older-than 30d --exclude-channel discord

• --min-capacity <num> - Only archive sessions below capacity threshold

  • Example: tide-watch archive --older-than 7d --min-capacity 50

Live Monitoring:

• --watch - Live updating dashboard (refreshes every 10s)
  • Example: tide-watch dashboard --watch
  • Press Ctrl+C to exit

Multi-Agent:

• --all-agents - Multi-agent discovery mode (default, auto-discovers agents)
• --single-agent-only - Single-agent mode (main agent only)

Configuration Override:

• --refresh-interval <seconds> - Dashboard refresh interval (1-300)
• --gateway-interval <seconds> - Gateway status check interval (5-600)
• --gateway-timeout <seconds> - Gateway command timeout (1-30)
• --session-dir <path> - Custom session directory

Usage Examples:

# Human-readable vs full precision
tide-watch dashboard                    # 18.7k/128k (easy to scan)
tide-watch dashboard --raw-size         # 18,713/128,000 (exact)

# Auto-detect current session (v1.3.4+)
export OPENCLAW_SESSION_ID="17290631-4"
tide-watch check --current              # Check THIS session
tide-watch check --current --json       # JSON for heartbeat scripts

# Session-specific archiving (v1.3.3+)
tide-watch archive --session abc123 --dry-run    # Preview
tide-watch archive --session abc123              # Archive one
tide-watch archive --session a --session b       # Archive multiple

# Partial ID matching (v1.3.3+)
tide-watch check --session 17290631-4   # Matches 17290631-42fe-40c0-...

# Multi-agent filtering
tide-watch dashboard --agent kintaro    # Kintaro sessions only
tide-watch report --exclude-agent main  # All except main

Runtime Requirements

Mode 1 (Directives-Only):

• Node.js: Not required
• npm: Not required
• Dependencies: None
• Binary: None
• Installation: Copy templates to workspace config files

Mode 2 (CLI Tools - Optional):

• Node.js: v14.0.0 or later required
• npm: Any recent version
• Dependencies:
  • Development: jest@^30.2.0 (for testing only)
  • Runtime: None (zero production dependencies)
• Binary: tide-watch (installed globally via npm link)
• Installation: git clone + npm link

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:

# From your workspace root (~/clawd or similar)
cat skills/tide-watch/AGENTS.md.template >> AGENTS.md

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:

# From your workspace root (~/clawd or similar)
cat skills/tide-watch/HEARTBEAT.md.template >> HEARTBEAT.md

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:

Warning thresholds (when to warn):

• Adjust percentages (default: 75/85/90/95)
• Range: 50-99%, ascending order, 2-6 thresholds

Check frequency (how often to monitor):

• Adjust interval (default: Every 1 hour)
• Options: 15min, 30min, 1hr, 2hr, or 'manual'
• Range: 5 minutes to 6 hours

Auto-backup:

• Enable/disable automatic backups (default: enabled)
• 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
2. Warn at thresholds (75%, 85%, 90%, 95%)
3. 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:

What's my current session capacity?
Check context usage
Run session_status

Reset Session with Context Preservation

When warned about high capacity:

Help me reset this session and preserve context

I'll:

1. Save current work to memory
2. Backup the session file (if not already backed up)
3. Provide a session resumption prompt
4. Reset the session

Load Session from Backup

If you need to load a previous session state from backup:

Show me available backups for this session
Load session from 90% backup

I'll:

1. List available backups with timestamps and sizes
2. Load the selected backup
3. Guide you through reconnecting to load the session

Backup locations:

• Path: ~/.openclaw/agents/main/sessions/backups/
• Format: <session-id>-<threshold>-<timestamp>.jsonl[.gz]
• 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: (tokens_used / tokens_max) * 100

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=🚨)

4. 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

5. 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)

6. Suggest actions

   • Save context to memory
   • Switch to lower-usage channel
   • Provide session reset commands
   • Generate session resumption prompts

7. Cleanup old backups

   • Remove backups older than retention period (default: 7 days)

8. 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:

What's my current session capacity?
Check context usage
Run session_status

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.

Configuration Examples

Conservative (early warnings)

Warning thresholds: 60%, 70%, 80%, 90%
Check frequency: Every 30 minutes

Aggressive (maximize usage)

Warning thresholds: 85%, 92%, 96%, 98%
Check frequency: Every 2 hours

Channel-specific

Discord channels: 75%, 85%, 90%, 95% (default)
Webchat: 85%, 95% (lighter warnings)
DM: 90%, 95% (minimal warnings)

Future Features

• CLI tool for capacity reports
• Automatic session backups at thresholds
• Historical capacity tracking
• Cross-session capacity reports
• Integration with heartbeat monitoring
• Email/notification warnings
• Smart session rotation suggestions

Requirements

• OpenClaw with session_status tool support
• Workspace with AGENTS.md file
• Active monitoring directive in agent instructions

Support

• Repo: https://github.com/chrisagiddings/openclaw-tide-watch
• Issues: https://github.com/chrisagiddings/openclaw-tide-watch/issues
• ClawHub: https://clawhub.ai/chrisagiddings/tide-watch

License

MIT