Passive Capture

Watch Daemon

Background process that keeps your context warm without any manual commands.

Starting the Watcher

$ contxt watch              # Foreground mode (Ctrl+C to stop)
$ contxt watch --daemon    # Background daemon
$ contxt watch:stop        # Stop the daemon
$ contxt watch:status      # Check if running

What It Monitors

Source file changes

Updates context.files with a 30-second debounce to avoid noise during active editing sessions. Respects .contxtignore and .gitignore.

.contxt/rules.md

Automatically runs contxt rules sync whenever the file is saved. Edit the markdown file in your IDE and memory updates within seconds.

.git/HEAD

Detects branch switches and updates the active memory branch to match. Complements the post-checkout hook for teams who prefer not to install git hooks.

Session timing

Tracks work sessions with a 30-minute inactivity timeout. Session data informs context summaries and the pre-push hook report.

Files with @tags

When a file containing Contxt annotations is modified, runs an incremental re-scan of just that file — not the entire project. New or changed tags become drafts immediately.

Foreground Output

When running in foreground mode, the watcher prints a live activity log with timestamps and event types:

contxt watch — monitoring my-app (main)

  14:32  files   src/api/billing.ts, src/lib/stripe.ts
  14:35  scan    + DECISION "Use Stripe Connect" (draft)
  14:52  context session active — 20 min, 4 files
  15:22  session ended — 50 min, 6 files touched
  15:22  rules   rules.md changed — syncing 2 updates

Daemon Mode

When started with --daemon, the watcher detaches from your terminal and runs as a background process. Its state is tracked via two files:

  • .contxt/.watch.pid

    Contains the process ID of the running daemon. Deleted automatically when the daemon stops cleanly.

  • .contxt/watch.log

    Rolling log of all watcher events. Rotated at 5MB. Review with tail -f .contxt/watch.log.

Resource Usage

The watcher is designed to be invisible in the background:

  • Memory: under 50MB RAM
  • Polling: native OS file events via chokidar (1s fallback)
  • Ignored automatically: node_modules, dist, build, and .contxtignore patterns