Coco Watch

coco watch monitors your working tree for changes and re-runs a configured generation task (review, commit draft, or both) on each debounced save. It acts as a background reviewer that flags issues as you code, or as a live commit-message preview while staging.

Basic Usage

bash

1# Default: continuous code review on every settled change set
2coco watch
3
4# Keep a commit-message draft current as you stage
5coco watch --draft
6
7# Run both review and draft on every settle
8coco watch --review --draft
9
10# Only watch staged changes (not the full working tree)
11coco watch --staged
12
13# Run one pass and exit (useful in scripts/CI)
14coco watch --once

How It Works

coco watch starts a filesystem watcher on the repository root (or just the index when --staged is set).
When files change, a debounce timer starts (default 500ms). Rapid successive edits coalesce into a single "settled" event.
On settle, the watcher computes a content digest of the current diff. If the digest matches the last successful run, the LLM call is skipped entirely (no cost incurred for touch-saves or formatting-only changes).
When the diff has actually changed, the configured operation(s) run against the current change set.
Results print to stdout. With --json, each state transition emits a newline-delimited JSON event for editor integration.

Options

Flag	Default	Description
`--review`	`true` (when neither flag given)	Re-run a code review each time the change set settles
`--draft`	`false`	Keep a commit-message draft current as you stage
`--staged`	`false`	Watch staged changes only (`git diff --cached`) instead of the full working tree
`--conventional`	`false`	Constrain `--draft` output to Conventional Commits
`--language <lang>`	config value	Write output in this language
`--interval <ms>`	`15000`	Minimum milliseconds between LLM calls (cost control)
`--debounce <ms>`	`500`	Milliseconds to wait after the last fs event before treating the change set as settled
`--once`	`false`	Run a single pass immediately and exit
`--json`	`false`	Emit line-delimited JSON events (one per state change)

Cost Control

The --interval flag (default 15 seconds) sets an absolute floor on how frequently LLM calls fire, regardless of how often you save. Combined with the content-digest guard (unchanged diffs never trigger a call), coco watch stays cost-effective even in rapid-iteration sessions.

For tighter control, set a budget via telemetry.budget.monthlyUsd in your config and coco doctor --cost will warn when you approach your cap.

JSON Event Stream

With --json, each state transition emits a JSON object on stdout:

jsonc

1{"type":"ready","repoRoot":"/path/to/repo","operations":["review"],"scope":"worktree"}
2{"type":"running","operation":"review"}
3{"type":"result","operation":"review","data":{...},"warnings":[]}
4{"type":"skipped","reason":"unchanged","digest":"sha256:abc..."}
5{"type":"idle"}
6{"type":"stopped"}

Event types: ready, idle, skipped, running, result, error, stopped.

Graceful Shutdown

Ctrl+C (SIGINT) or SIGTERM stops the watcher cleanly: in-flight LLM calls are cancelled via AbortController, the watcher closes, and a final stopped event emits.

Examples