Skip to content

Coco Watch

Jump to bottom
Griffen Fargo edited this page Aug 2, 2026 · 1 revision

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

# Default: continuous code review on every settled change set
coco watch

# Keep a commit-message draft current as you stage
coco watch --draft

# Run both review and draft on every settle
coco watch --review --draft

# Only watch staged changes (not the full working tree)
coco watch --staged

# Run one pass and exit (useful in scripts/CI)
coco watch --once

How It Works

  1. coco watch starts a filesystem watcher on the repository root (or just the index when --staged is set).
  2. When files change, a debounce timer starts (default 500ms). Rapid successive edits coalesce into a single "settled" event.
  3. 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).
  4. When the diff has actually changed, the configured operation(s) run against the current change set.
  5. 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:

{"type":"ready","repoRoot":"/path/to/repo","operations":["review"],"scope":"worktree"}
{"type":"running","operation":"review"}
{"type":"result","operation":"review","data":{...},"warnings":[]}
{"type":"skipped","reason":"unchanged","digest":"sha256:abc..."}
{"type":"idle"}
{"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

# Background reviewer while developing (default)
coco watch

# Live commit message preview for staged work
coco watch --draft --staged --conventional

# One-shot review of current changes (CI-friendly)
coco watch --once --json

# Long settle for slow-saving editors
coco watch --debounce 2000

# Lower cost ceiling: at most one call per minute
coco watch --interval 60000

See Also

Clone this wiki locally