# Searchat — File Watching & Live Indexing

Event-Driven · Debounced · Queue-Based · Append-Only
v0.6.0 | Last updated: 2026-02-17
Python 3.10+ · watchdog · Queue · Background Thread
1
File System Event Detection
watchdog.Observer monitors conversation directories for file changes
Monitored Events: Created, Modified
Watched Directories: ~/.claude/projects/, ~/.vibe/logs/, ~/.local/share/opencode/
2
Extension Check & Connector Detection
Identifies file type and selects appropriate connector
Supported: .jsonl (Claude), .json (Vibe/OpenCode), .db (Cursor), .md (Aider)
Action: Unsupported extensions ignored
3
Debounce Gate2s / 5min
Time-based delay prevents indexing in-progress files
New Files: 2s delay (fast indexing for completed files)
Modified Files: 5min delay (prevents re-indexing during active editing)
4
Queue Enqueue
Event added to pending updates queue
Queue Type: Python Queue (thread-safe)
Batch Delay: 5s (groups multiple events)
5
Background Thread Consumption
Separate thread processes queued events without blocking
Method: _process_pending_updates()
Isolation: Indexing runs in background, UI remains responsive
6
Index Append Operation
Safe append-only indexing (never deletes existing data)
Method: indexer.index_append_only(file_paths)
Safety: Only adds new conversations, preserves all existing data
7
Watcher Stats Update
Updates statistics: indexed_count, last_update, in_progress flag
Tracked: Files indexed since start, timestamp of last update
API: GET /api/watcher/status
8
UI Refresh (Optional)
Web UI can poll for updated statistics and refresh results
Polling: Optional real-time updates via periodic API calls
Auto-Discovery: New conversations appear in search automatically
2s / 5min
Debounce Times
5s
Batch Delay
Queue
Thread-Safe
Append-Only
Safe Indexing