# Send Tide Watch to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "tide-watch",
    "name": "Tide Watch",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/chrisagiddings/tide-watch",
    "canonicalUrl": "https://clawhub.ai/chrisagiddings/tide-watch",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/tide-watch",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tide-watch",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "CHANGELOG.md",
      "CLAWHUB-SCANNER-RESPONSE.md",
      "INSTALLATION.md",
      "PARSING.md",
      "README.md",
      "RESEARCH-ANYBINS-PATTERN.md"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/tide-watch"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/tide-watch",
    "downloadUrl": "https://openagent3.xyz/downloads/tide-watch",
    "agentUrl": "https://openagent3.xyz/skills/tide-watch/agent",
    "manifestUrl": "https://openagent3.xyz/skills/tide-watch/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/tide-watch/agent.md"
  }
}
```
## Documentation

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

FeatureDirectives-OnlyCLI ToolsNode.js required?❌ No✅ Yes (14+)InstallationCopy templatesnpm linkCode execution❌ None✅ JavaScriptFile accessVia built-in toolsDirect filesystemSecurity riskLowestModerateUse casePassive monitoringActive 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.

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

### Security Best Practices

For Directives-Only Mode (Safest):

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

For CLI Tools Mode (If Needed):

⚠️ Verify version 1.0.1 or later (tide-watch --version)
⚠️ 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)


⚠️ Only use UUID session IDs with --session flag
⚠️ Avoid untrusted input to CLI commands
⚠️ 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

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

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:

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:

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:

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

I'll:

List available backups with timestamps and sizes
Load the selected backup
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)

### Automatic Monitoring (Heartbeat)

When you add Tide Watch to your HEARTBEAT.md, I automatically:

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



Check capacity on schedule (default: every hour)

Run session_status to get token usage
Calculate percentage: (tokens_used / tokens_max) * 100



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



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



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)



Suggest actions

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



Cleanup old backups

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



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.

### 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
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: chrisagiddings
- Version: 1.3.6
## Source health
- Status: healthy
- Source download looks usable.
- Yavira can redirect you to the upstream package for this source.
- Health scope: source
- Reason: direct_download_ok
- Checked at: 2026-04-30T16:55:25.780Z
- Expires at: 2026-05-07T16:55:25.780Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/tide-watch)
- [Send to Agent page](https://openagent3.xyz/skills/tide-watch/agent)
- [JSON manifest](https://openagent3.xyz/skills/tide-watch/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/tide-watch/agent.md)
- [Download page](https://openagent3.xyz/downloads/tide-watch)