Watch mode

In release — preview. This surface is fully built and in the release process; it is not yet generally available. Treat the commands and behavior here as preview until GA.

Not every agent has lifecycle hooks. Watch mode is the dependency-free fallback that gives any tool the same loop: a debounced file watcher that runs one scan --changed per burst of edits and publishes the result as a privacy-safe event stream.

Run it

shipmoor-harness watch --emit json                    # event per scan, on stdout
shipmoor-harness watch --emit file                    # events to a file instead
shipmoor-harness watch --emit json --debounce-ms 500  # tune the burst window
shipmoor-harness watch --once                         # one burst, then exit (good for scripts)

The watcher polls scoped file mtimes — it respects .gitignore and your .shipmoor.yaml ignore rules, and never descends into .shipmoor/. A burst of rapid edits is debounced (default window: harness.watch.debounce_ms, 750 ms) into one scan, so an agent writing ten files doesn’t trigger ten scans. SIGINT/SIGTERM shut it down cleanly.

The event stream

Each scan emits one JSON line:

{"event":"scan","paths":["pay.py"],"findings_summary":{"counts_by_severity":{"critical":0,"high":1,"medium":0,"low":0,"info":0},"rule_ids":["python.phantom_import"],"total":1},"exit_code":0}

That’s the whole event, by design: paths, rule IDs, and counts only — never source, never finding prose. The event stream is safe to pipe into logs or dashboards without re-creating the privacy review your repo’s source would need.

The full findings (for the tool that should see them) land in .shipmoor/last-watch.json — mode, paths, findings, exit code, and the formatted feedback — which consumers like the Cursor adapter read locally.

Who uses it

• Cursor — the Cursor adapter is a soft adapter: it writes a rules file telling Cursor to prefer the watcher’s last-watch.json findings.
• Any editor or agent without hooks — run watch in a terminal beside your session; mode routing still applies, so block mode exits 1 on a threshold breach.
• Scripts — --once waits for one burst, scans, and exits, which makes it composable in test and CI scaffolding.

Exit codes

Next

• Agent support — how Cursor consumes the watcher.
• Install & modes — the mode the watcher routes with.
• Privacy & telemetry — the broader local-first guarantees.