Use when you need to check whether the current session is approaching context limits and decide whether to compact, hand off, or continue. Implements a casca...
---
name: willow-context-sentinel
version: "1.0.0"
description: Use when you need to check whether the current session is approaching context limits and decide whether to compact, hand off, or continue. Implements a cascading model protocol for Willow/OpenClaw stacks on Linux โ monitoring prompt_count as a context proxy and routing to strategic-compact or willow_task_submit as needed.
metadata: { "openclaw": { "emoji": "๐งญ", "os": ["linux"], "requires": { "bins": ["bash"] } } }
---
# Willow Context Sentinel
Monitor session context usage and apply a cascading relief protocol before context exhaustion silently degrades response quality.
| Output | Meaning |
| ----------------- | -------------------------------------------------------------------------- |
| **STATUS_OK** | prompt_count < 15 โ session is healthy, continue normally |
| **COMPACT_NOW** | prompt_count 15โ25 โ approaching limit, invoke strategic-compact |
| **HANDOFF_NOW** | prompt_count > 25 โ near ceiling, invoke handoff + willow_task_submit |
| **POSTGRES_DOWN** | session_anchor.json reports postgres as down โ fix infra before proceeding |
## When to use
- **Heartbeat**: run at the start of every session and every ~10 prompts
- **Before large tasks**: check before any operation that will generate many tool calls or long output
- **Proactively**: if responses feel slower, less coherent, or you notice unusual hedging, run this check immediately
- **After a branch merge or plan execution**: context spikes are common at transition points
## Step 1 โ Run the sentinel script
```bash
bash {baseDir}/scripts/check_context.sh
```
The script reads two Willow state files:
- `~/.willow/anchor_state.json` โ `prompt_count` field (context proxy)
- `~/.willow/session_anchor.json` โ `postgres` status field
## Step 2 โ Interpret the output
Run the script and act on the single-line output:
### STATUS_OK
No action needed. Session is healthy.
```
STATUS_OK
```
Continue with the current task. Optionally note the prompt_count in a heartbeat log entry.
### COMPACT_NOW
```
COMPACT_NOW
```
Context is filling. Invoke the `strategic-compact` skill immediately before proceeding:
```
/strategic-compact
```
After compact completes, re-run the sentinel. If it still reports `COMPACT_NOW` or escalates to `HANDOFF_NOW`, proceed to the handoff protocol below.
### HANDOFF_NOW
```
HANDOFF_NOW
```
Session is near the context ceiling. Invoke the `handoff` skill and submit the next task to Willow:
1. Run `/handoff` to produce a structured handoff document
2. Call `willow_task_submit` with the next bite as the task body
3. End the session cleanly โ do not attempt further large operations
### POSTGRES_DOWN
```
POSTGRES_DOWN
```
Willow's backing store is unreachable. KB reads and writes will fail silently. Do not proceed with memory-dependent tasks. Check the Willow server status:
```bash
willow status
# or
systemctl status willow-postgres
```
Resolve the infra issue before resuming work.
## Step 3 โ Integration with HEARTBEAT.md
Add a sentinel call to your heartbeat template so it runs automatically. Minimal example:
```markdown
## Heartbeat โ {timestamp}
**Sentinel:** `bash ~/.openclaw/skills/willow-context-sentinel/scripts/check_context.sh`
| Check | Result |
| -------- | --------- |
| Context | STATUS_OK |
| Postgres | up |
Next bite: {next_task}
```
If the sentinel output is anything other than `STATUS_OK`, record the output and the action taken before moving on.
## Cascading protocol reference
```
Claude Sonnet 4.6
โ
โโ prompt_count โฅ 15 โ COMPACT_NOW โ /strategic-compact
โ โ
โ โโ still โฅ 15 after compact
โ โ
โโ prompt_count > 25 โ HANDOFF_NOW โ /handoff + willow_task_submit
```
Relief valves are applied in order. Skip to `HANDOFF_NOW` if compact has already been run in this session and context remains high.
## Notes
- `prompt_count` is a proxy, not a direct token count. Actual context consumption varies by response length. Treat thresholds as conservative triggers, not hard limits.
- Both state files (`anchor_state.json`, `session_anchor.json`) are written by the Willow server. If either file is missing, the script outputs `STATUS_OK` and logs a warning to stderr โ it fails open, not closed.
- This skill does not modify any state files. It is read-only and safe to run at any time.
don't have the plugin yet? install it then click "run inline in claude" again.