# cc-steer watch
Tail live transcripts and run the steering cascade, delivering per `~/.cc-steer/live.toml`.
``` bash
cc-steer watch [OPTIONS]
```
Every open session is followed as it writes; each time one goes quiet after completing a turn, the cascade -- stage-1 gate, drafting model, optional exemplar-conditioned refiner -- decides whether the user would have steered right there. Stage 1 defaults to the promoted lexical gate from the model registry, thresholded at its trained 2 fires/100 turns budget (`--gate-threshold` overrides); without a promoted version it falls back to the turn-floor heuristic. Stage 2 defaults to the promoted local watcher (the mlx extra) when one exists, abstaining at its trained budget threshold on P(NO_STEER); stage 3 is then disabled -- the E2-validated two-stage configuration -- unless `--refiner spawn` re-enables it. Every proposal lands in the shadow ledger (`cc-steer shadow report` measures them); in `mirror` or a live mode it is also queued to the delivery mailbox (`cc-steer inbox`) for the `UserPromptSubmit` hook to surface. `--shadow` forces shadow delivery regardless of the config. Exemplar retrieval needs the `embed` extra and a built index (`cc-steer index`); without one the watcher still runs, stage 3 unconditioned. Runs until interrupted.
Full --help output
Usage: cc-steer watch [OPTIONS]
Tail live transcripts and run the steering cascade, delivering per ``~/.cc-
steer/live.toml``.
Every open session is followed as it writes; each time one goes quiet after
completing a turn, the cascade -- stage-1 gate, drafting model, optional
exemplar-conditioned refiner -- decides whether the user would have steered
right there. Stage 1 defaults to the promoted lexical gate from the model
registry, thresholded at its trained 2 fires/100 turns budget (``--gate-
threshold`` overrides); without a promoted version it falls back to the
turn-floor heuristic. Stage 2 defaults to the promoted local watcher (the
mlx extra) when one exists, abstaining at its trained budget threshold on
P(NO_STEER); stage 3 is then disabled -- the E2-validated two-stage
configuration -- unless ``--refiner spawn`` re-enables it. Every proposal
lands in the shadow ledger (``cc-steer shadow report`` measures them); in
``mirror`` or a live mode it is also queued to the delivery mailbox (``cc-
steer inbox``) for the ``UserPromptSubmit`` hook to surface. ``--shadow``
forces shadow delivery regardless of the config. Exemplar retrieval needs
the ``embed`` extra and a built index (``cc-steer index``); without one the
watcher still runs, stage 3 unconditioned. Runs until interrupted.
Options:
--shadow Force shadow delivery, ignoring the mode in
~/.cc-steer/live.toml.
--root DIRECTORY Transcript roots to tail. Defaults to
~/.claude/projects.
--gate [heuristic|lexical] Stage-1 gate: the lab-trained lexical model
(from the registry) or the turn-floor
heuristic. [default: (lexical when a gate
model is promoted, else heuristic)]
--gate-threshold FLOAT Stage-1 gate score below which a turn is
suppressed. [default: (the trained
threshold (lexical) or 0.5 (heuristic))]
--drafter [auto|spawn|mlx|http]
Stage-2 drafter: the local trained watcher
(mlx), a hosted vLLM-compatible endpoint
(http), or the claude CLI (spawn); auto
picks mlx when a watcher model is promoted
and the mlx extra is installed, and never
selects http (opt in explicitly). [default:
auto]
--drafter-endpoint TEXT vLLM-compatible base URL for the http
drafter (e.g. https://.modal.run);
scoring posts prompt_logprobs to
/v1/completions (a vLLM extension pure
OpenAI lacks) and generation uses
/v1/chat/completions. Required for --drafter
http.
--drafter-model TEXT Model name the http endpoint serves (the
OpenAI `model` field). Required for
--drafter http.
--drafter-timeout FLOAT Per-request timeout in seconds for the http
drafter; a hanging endpoint fails open to
NO_STEER. The API key is read from
$CC_STEER_DRAFTER_API_KEY. Ignored for other
drafters. [default: 30.0]
--stage2-threshold FLOAT Local drafter abstain threshold on
P(NO_STEER); ignored for the spawn drafter.
[default: (the promoted watcher's budget
threshold)]
--stage2-idle-ttl FLOAT Idle seconds before the local mlx drafter
unloads its weights; a large value keeps it
resident. Ignored for the spawn drafter.
[default: 900.0]
--refiner [auto|spawn|none] Stage 3: the claude CLI refiner or none (a
fired draft ships as-is); auto disables it
for the mlx drafter (two-stage, per E2) and
keeps it for spawn. [default: auto]
--debounce FLOAT Seconds a session must stay quiet before its
last completed turn is evaluated. [default:
2.0]
--poll FLOAT Seconds between transcript tail polls.
[default: 5.0]
--db FILE Database path. Defaults to ~/.cc-
steer/feedback.db.
--shadow-db FILE Shadow ledger path. Defaults to ~/.cc-
steer/shadow.db.
--help Show this message and exit.
# Options
`--shadow`
Force shadow delivery, ignoring the mode in ~/.cc-steer/live.toml.
`--root: DIRECTORY`
Transcript roots to tail. Defaults to ~/.claude/projects.
`--gate: CHOICE`
Stage-1 gate: the lab-trained lexical model (from the registry) or the turn-floor heuristic.
`--gate-threshold: FLOAT`
Stage-1 gate score below which a turn is suppressed.
`--drafter: CHOICE = auto`
Stage-2 drafter: the local trained watcher (mlx), a hosted vLLM-compatible endpoint (http), or the claude CLI (spawn); auto picks mlx when a watcher model is promoted and the mlx extra is installed, and never selects http (opt in explicitly).
`--drafter-endpoint: TEXT`
vLLM-compatible base URL for the http drafter (e.g. https://.modal.run); scoring posts prompt_logprobs to /v1/completions (a vLLM extension pure OpenAI lacks) and generation uses /v1/chat/completions. Required for `--drafter` http.
`--drafter-model: TEXT`
Model name the http endpoint serves (the OpenAI `model` field). Required for `--drafter` http.
`--drafter-timeout: FLOAT = 30.0`
Per-request timeout in seconds for the http drafter; a hanging endpoint fails open to NO_STEER. The API key is read from \$CC_STEER_DRAFTER_API_KEY. Ignored for other drafters.
`--stage2-threshold: FLOAT`
Local drafter abstain threshold on P(NO_STEER); ignored for the spawn drafter.
`--stage2-idle-ttl: FLOAT = 900.0`
Idle seconds before the local mlx drafter unloads its weights; a large value keeps it resident. Ignored for the spawn drafter.
`--refiner: CHOICE = auto`
Stage 3: the claude CLI refiner or none (a fired draft ships as-is); auto disables it for the mlx drafter (two-stage, per E2) and keeps it for spawn.
`--debounce: FLOAT = 2.0`
Seconds a session must stay quiet before its last completed turn is evaluated.
`--poll: FLOAT = 5.0`
Seconds between transcript tail polls.
`--db: FILE`
Database path. Defaults to ~/.cc-steer/feedback.db.
`--shadow-db: FILE`
Shadow ledger path. Defaults to ~/.cc-steer/shadow.db.