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

Automatic Setup with contxt init

You don't need to start the watcher manually. contxt init sets everything up automatically at the end of project initialization:

  • ✓
    Watch daemon started

    The background daemon is launched immediately so passive capture begins the moment your project is created.

  • ✓
    Auto-sync enabled

    The project config is written with autoSync: true. After every 30-second file flush the daemon automatically calls contxt sync push — no manual push needed.

  • ✓
    MCP config written

    Both .mcp.json (Claude Code) and .cursor/mcp.json are created so your AI editors can immediately access the Contxt MCP server.

  • ✓
    Git hooks installed

    post-commit and pre-push hooks are added to .git/hooks/ to sync context on every commit and push.

  • ✓
    Claude Code hook registered

    A UserPromptSubmit hook is added to ~/.claude/settings.json so Claude silently loads project context at the start of every session.

contxt init

✓ Project "my-app" created
✓ Git hooks installed
✓ MCP config written (.mcp.json, .cursor/mcp.json)
✓ Claude Code hook registered
✓ Watch daemon started (auto-sync enabled)

If the daemon is ever stopped, restart it with contxt watch --daemon. Use contxt watch:status to confirm it's 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