swarmvault watch

Watch the inbox directory and trigger import and compile cycles when files change.

Usage

swarmvault watch [--lint] [--repo] [--once] [--code-only] [--debounce <ms>]
swarmvault watch status

Options

  • --lint - Run lint after each compile cycle
  • --repo - Also refresh tracked repo roots that were previously ingested through directory ingest
  • --once - Run one refresh cycle immediately instead of starting a long-running watcher
  • --code-only - Force the AST-only refresh path and defer non-code semantic re-analysis to a later compile
  • --debounce <ms> - Debounce file changes before running a cycle. Default: 900

What It Does

Each watch cycle:

  1. Imports new or changed inbox files
  2. Optionally refreshes tracked repo roots when --repo is enabled
  3. Runs swarmvault compile
  4. Optionally runs swarmvault lint
  5. Writes a canonical session artifact to state/sessions/
  6. Appends a compatibility run record to state/jobs.ndjson

When --repo sees only code-file changes under tracked repo roots, SwarmVault takes the faster code-only path and refreshes code pages plus graph structure without re-running non-code semantic analysis for unchanged sources.

Use --code-only when you want to force that same narrower refresh path even on an explicit one-shot watch run.

When --repo sees non-code changes under tracked repo roots, SwarmVault records those files under state/watch/, marks affected pages stale, and surfaces the pending semantic refresh set through watch status and the local graph workspace instead of silently re-ingesting them.

Notes

  • Watch mode is a foreground local worker in the current release
  • --repo extends the watch target set to tracked repo roots, but still ignores SwarmVault's generated workspace directories
  • --once is the same single-run refresh path used by swarmvault hook install
  • watch status reports watched repo roots, the latest watch run, and pending semantic refresh entries
  • Rapid bursts of file changes are coalesced into a single cycle
  • state/jobs.ndjson remains available for machine-readable run history, but state/sessions/ is the canonical audit trail