| name | watchtower |
| description | Use when the user wants an agent session supervised while they are not watching it. Triggers on "launch this and watch it", "keep an eye on that session", "drive this to done while I'm out", "what are my sessions waiting on", or any task long enough that the user will not sit through it. Launches a supervised session, reports what is live and what each one is blocked on, and puts a driver on one session that answers routine prompts and escalates every real decision to the user. |
Watchtower: supervising a session the user is not watching
A long session needs a human a handful of times, for seconds each, and the user cannot
predict when. So they either sit and watch a progress bar or come back to a session that
stopped twenty minutes in on a permission prompt. Watchtower is what sits in that chair:
it launches a session that is addressable, puts a driver on it, and gets the user back
only for the things that are actually theirs to decide.
Read the charter before driving anything
PATTERN.md is the charter: the roles, the reasoning, and every authority
boundary. Read it before you launch, seed, or drive a session. It is not restated
here, and it is deliberately not summarized here either. Two copies of an authority
boundary drift, and a drifted boundary is the failure this tier exists to prevent.
The one line worth carrying before you get there: the routine belongs to this tier,
every choice belongs to the user, and when you cannot tell which one you are looking at,
it is a choice.
When not to use this
- The user is sitting right there watching the session. Then they are the driver, and
a second supervisor is pure overhead.
- The task is short. If it finishes before the user could get up, the setup costs more
than it saves.
- The session already exists. Watchtower only drives sessions it launched, because a
session it did not launch has a goal and stop conditions it was never told. Report on
those; do not adopt them.
Preflight
Run `bin/gucci-doctor` before the first launch in a session. It checks the tier's
dependencies and says plainly what is missing. If it fails, report exactly what it said
and stop. Do not launch, do not work around it, and do not diagnose it three commands
deep into a broken session.
Dependencies: tmux and python3 >= 3.9. Tested on macOS. Linux probably works and
is unverified; Windows is not supported.
Entry points
| Path | What it is |
|---|
PATTERN.md | The charter. Roles, boundaries, limits. Read first |
bin/gucci-doctor | Preflight. Run before the first launch |
bin/agent-solo | Launch a session that is addressable from birth. The only supported way in |
bin/wt-send | Send one line into a session and verify it landed |
bin/wt-status | What is live, and what each session is waiting on |
.claude/agents/wt-driver.md | The driver. Babysits one session to a verified result |
lib/sessions.py | The single place the session registry is parsed |
The loop
- Preflight once, per the gate above.
- Launch with
bin/agent-solo. Keep the target handle it reports; the driver needs it.
- Seed the session with
bin/wt-send: goal, constraints, and what "verified done"
concretely means.
- Spawn a
wt-driver immediately, with the target, goal, constraints, and
verification criteria. Those four things are its whole brief. Never hand it state about
any other session.
- Handle its returns. A driver ends its shift on an escalation, on a verified result,
or at its shift cap. On an escalation, put the question to the user unanswered and arm
a fresh driver with their decision as context. On an interim report, arm a fresh driver
with that report. Relay its sends to the user as if they were your own.
Then stop touching the session. Polling it yourself is the job you just delegated.
