Auto Capture (Git Watcher)

The git watcher is the core capture system of the Contox VS Code extension. It runs in the background, tracking your git commits and file saves, and sends captured events to the Contox V2 ingest API.

What gets captured

The git watcher tracks three types of activity:

Git commits

When a new commit is detected, the watcher captures:

• SHA (first 12 characters)
• Commit message (truncated to 500 characters)
• Author name
• Timestamp
• Files changed (excluding excluded patterns)
• Insertions and deletions count
• Compact diff (if enabled, max 3000 characters per commit)

File saves

Every time you save a file in VS Code, the relative path is recorded. Excluded file patterns are filtered out.

Active editor files

The watcher tracks which files you open in the editor, providing additional context about which parts of the codebase you worked on.

How commit detection works

The watcher uses two strategies:

Primary: VS Code Git API -- The extension listens to the built-in Git extension's state change events. When HEAD changes (a new commit), the watcher captures the commit details and diffs.

Fallback: Polling -- If the VS Code Git extension is not available, the watcher falls back to polling git rev-parse HEAD every 15 seconds. When a new HEAD is detected, the same capture logic runs.

Diff capture

When contox.capture.includeDiffs is enabled (the default), the watcher runs git diff-tree -p -U4 for each commit and captures the unified diff output. This provides the enrichment pipeline with the actual code changes for richer context extraction.

Diff capture has several safeguards:

• Max size: Diffs are truncated to 3000 characters per commit
• Timeout: The git diff-tree command has a 5-second timeout
• Excluded files: Diffs for the following file types are filtered out:
  • Lock files (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, *.lock)
  • Minified files (*.min.js, *.min.css)
  • Source maps (*.map)
  • Binary assets (*.wasm, *.png, *.jpg, *.jpeg, *.gif, *.ico, *.svg)
  • Fonts (*.woff, *.woff2, *.ttf, *.eot)
• Binary diffs: Sections containing "Binary files" are skipped
• Anonymization: When contox.capture.anonymizeDiffs is enabled, code content is stripped and only file paths and stats are retained

File exclusion patterns

The watcher respects the contox.capture.excludePatterns setting. The default patterns exclude:

["*.env", "*.key", "*.pem", "*.p12", "*.pfx", "node_modules/**", ".git/**", "dist/**"]

Files matching these patterns are excluded from both the file save tracking and the commit file lists. Pattern matching supports two formats:

• *.ext -- Matches files ending with the extension
• dir/** -- Matches all files under the directory

Auto-flush triggers

Captured events are buffered in memory and flushed (sent to the API) when any of these conditions are met:

HMAC signing

All captured events are sent to POST /api/v2/ingest with an HMAC signature for authentication. The HMAC secret is resolved in this order:

1. VS Code SecretStorage (stored during setup)
2. contox.hmacSecret setting
3. Fetched from the API and cached in SecretStorage

If no HMAC secret is available, the watcher shows a one-time warning and suggests re-running the setup wizard.

Status bar indicator

While capturing, the status bar shows a live timer and event count. This tells you the capture system is active and how many events have been buffered since the last flush.

Disabling capture

To disable auto-capture entirely, set contox.capture.enabled to false in your VS Code settings:

{
  "contox.capture.enabled": false
}

To disable only diff capture while keeping commit and file tracking:

{
  "contox.capture.includeDiffs": false
}

Next steps

• Session Management -- How sessions and the enrichment pipeline are tracked
• Settings -- All capture-related settings