Watch mode

codeguard watch analyzes a project once, then re-analyzes it whenever relevant source files change. It reuses the same analysis engine, scanner, and configuration as codeguard check.

codeguard watch .
codeguard watch ./src
codeguard watch . --debounce 500

Options

Option	Behavior
[path]	Project directory to watch; defaults to .. Must be an existing directory.
--debounce <ms>	Milliseconds to wait for changes to settle before re-analyzing. Whole number from 0 to 60000; default 300.

Press Ctrl+C (SIGINT) or send SIGTERM to stop. Watchers and timers are released and the process exits with code 0.

Example output

CodeGuard watch mode
Debounce: 300 ms. Press Ctrl+C to stop.
[09:05:01] Running initial analysis...
[09:05:02] Analysis #1 complete for sample-app in 812 ms
  Active analyzers: typescript, javascript
  Files scanned: 12
  Status: clean (0 error(s), 0 warning(s)). Watching for changes...
[09:05:20] Change detected: src/index.ts. Re-analyzing...
[09:05:21] Analysis #2 complete for sample-app in 640 ms
  Active analyzers: typescript, javascript
  Files scanned: 12
  Changed: src/index.ts
  ERROR [TS2322] src/index.ts:3:7: Type 'string' is not assignable to type 'number'.
  Status: errors found (1 error(s), 0 warning(s)). Watching for changes...
[09:05:40] Watch mode stopped.

The output is the example format only. Colors follow the standard NO_COLOR convention and are disabled when output is not a terminal. The terminal is never cleared.

Behavior

• A full-project analysis runs after each batch of changes; incremental compilation is not used.
• Changes to .ts, .tsx, .js, and .jsx files, to codeguard.config.json, tsconfig*.json, and jsconfig.json, and creation or removal of directories trigger analysis.
• Rapid changes are coalesced by the debounce window. Only one analysis runs at a time; changes made during a run trigger exactly one follow-up run.
• Finding diagnostics never stops watch mode, and watch mode always exits 0 after a graceful stop. Use codeguard check in CI for exit codes based on errors.
• An invalid project root exits with code 2. Analysis failures, such as an invalid configuration, are reported and watching continues so you can fix the problem.

Limitations and security

• The same ignore rules as codeguard check apply: node_modules, dist, build, .git, .next, coverage, environment files, key files, and files named like secrets, credentials, or tokens never trigger analysis. Configured ignore patterns also apply.
• One non-recursive watcher is created per real directory. Symlinked directories are not followed, and at most 2,000 directories are watched; a warning appears if the limit is reached.
• At most 100 changed paths are remembered between runs, so memory stays bounded.
• Watching depends on native filesystem notifications. Network drives and some container mounts may not deliver events; use codeguard check there.
• Watch mode is read-only: it never modifies files, runs project code, or contacts the network.