| name | vigil |
| description | Keep vigil over a session's context: measure how full the context window is (ctx NN%) and hand over in-process via /clear at points you choose, resuming from a re-injected handover. Use when the user wants to reset/compact context without losing the thread, asks "how full is my context", "hand over", "reset and resume", or runs a long/unattended session that must manage its own context. Requires tmux for automatic handover; works manually without it.
|
Vigil
Two jobs, one lifecycle: measure context accumulation, and hand over
(reset + resume) before the window overflows. Vigil is self-contained — it needs
no other plugin. State lives in a git-ignored .vigil/ in the working directory.
Drive it through the CLI (locate cli.py relative to this skill; when installed
as a plugin the scripts live under the plugin root):
python .../scripts/cli.py --root . <command>
Begin the watch
Run begin to activate vigil for this directory. It reports auto (under
tmux — the Stop hook can send /clear unattended) or manual (no tmux — you
checkpoint and ask the user to type /clear). Until you begin, the hooks
no-op: zero interference in an ordinary chat.
Measure
context prints ctx NN% — the live context usage against your configured
threshold (from config, shown only when over; never a hardcoded number). Read
it at natural stop points.
Hand over — you decide, never a blind threshold
Hand over when: (a) ctx NN% is over threshold AND you are at a clean stop
point; (b) you finish a coherent unit of work; or (c) the user asks. Run:
handover [--notes "the critical prose a fresh you must know"] \
[--content-file F | -] [--no-snapshot]
The handover document is assembled from a generic session snapshot (cwd, git
branch + status, recently-modified files), plus any --content-file blob (a
caller can pipe richer context via -), plus your --notes. --no-snapshot
drops the generic capture when the caller supplies the whole payload. In auto
mode the Stop hook sends /clear at turn end; in manual mode you tell the user
to type /clear. Either way SessionStart re-injects the handover — once (it is
archived to .vigil/archive/ on inject) — and you resume lean.
Defer and pause
Never clear a discussion out from under a live human. While a live exchange is
in progress, hold off; run pause when someone joins an unattended run, and
resume to re-arm. Always wait for in-flight work to finish before handing over.
Config
config get|set context.threshold|context.mode|context.window. mode is
local (plain) or remote (a launcher may add --remote-control for mobile
visibility). Defaults: threshold 35, window 200000.
Manual trigger
The /handover command runs the handover flow on demand.
