Transcript Watcher

The transcript watcher monitors your coding agent's activity and automatically indexes files as they're accessed. This enables ultrasync to learn which files are relevant to your work without requiring manual indexing.

How It Works

1. Monitors transcripts - Watches the coding agent's session files
2. Detects file access - Identifies Read, Write, Edit, Grep, and Glob operations
3. Triggers indexing - Automatically indexes accessed files
4. Caches patterns - Remembers grep/glob patterns for future search

When Claude Code or Codex reads a file, that file gets indexed. When a grep pattern is used, the pattern and matching files are cached so future semantic searches can find them.

Supported Agents

The transcript watcher supports:

• Claude Code - Monitors ~/.claude/projects/ transcripts
• Codex CLI - Monitors Codex session files

The appropriate parser is selected automatically based on detected agent.

What Gets Indexed

File Operations

Any file accessed through these tools:

• Read - File contents read
• Write - New file created
• Edit - File modified
• Bash commands that read files

Pattern Caching

Grep and glob patterns are cached for semantic retrieval:

# This grep pattern gets cached
grep "handleAuth" --type ts

# Later, searching for "authentication" can find these cached results
search("authentication")

This bridges the gap between literal pattern matching and semantic search.

Managing the Watcher

Check Status

watcher_stats()

Returns:

• Whether the watcher is running
• Which agent is being watched
• Files indexed in current session
• Patterns cached

Start/Stop

watcher_start()
watcher_stop()

The watcher starts automatically when ultrasync initializes. You can stop it if you want to disable automatic indexing.

Reprocess Transcripts

If ultrasync was restarted mid-session and missed some activity:

watcher_reprocess()

This clears position markers and re-reads transcripts from the beginning.

Leader Election

When multiple MCP server instances run (e.g., multiple editor windows), only one acts as the watcher leader. This prevents duplicate indexing.

The leader is determined by file lock - the first instance to acquire the lock becomes the watcher. If that instance exits, another takes over.

Learning from Patterns

With learning enabled (ULTRASYNC_LEARN_FROM_SEARCH=true), the watcher can improve search quality over time:

1. Observes which grep/glob patterns you use frequently
2. Notes which files are accessed together
3. Builds associations between search patterns and relevant files

This helps future semantic searches return more relevant results based on your actual usage patterns.

Performance

The watcher is designed for minimal overhead:

• Uses file position tracking (only reads new content)
• Batches indexing operations
• Respects rate limits on pattern caching
• Skips already-indexed files unless modified

Typical impact is negligible - a few milliseconds per file access.