Capture
How Stoa automatically captures provenance from AI coding tools and file changes, without any manual documentation.
Capture is the input layer of Stoa. It automatically monitors your project, watches for AI coding sessions, and extracts provenance without any manual documentation effort.
How Capture Works
The system operates through three integrated components that work together to build a complete provenance record.
1. File Watcher
The daemon monitors your project directory for all file changes in real time:
| Change Type | What It Detects |
|---|---|
| Create | New files added to the project |
| Modify | Existing files changed |
| Delete | Files removed |
| Rename | Files moved (detected via content hash matching) |
Changes are detected via filesystem events (fsnotify) with a 30-second reconciliation loop as a safety net. All changes are written to the journal as the system of record.
2. Session Parser
The session parser extracts structured data from AI coding tool sessions. For Claude Code (the primary integration), it monitors:
~/.claude/projects/{project-path}/*.jsonlFrom each session, it extracts:
- User prompts (what you asked the AI to do)
- Agent replies (what the AI responded)
- File operations (Write, Edit, MultiEdit, Read, and 15+ other tool types)
- Content hashes for precise change matching
The parser normalizes all paths relative to the project root and handles tool-specific formats across all supported AI coding tools.
3. Correlation Engine
The correlation engine links filesystem changes to the AI exchanges that created them. It matches on:
- File paths: which files the exchange operated on
- Content hashes: precise match between session content and actual file content
- Timing: when the change occurred relative to the exchange
- Operation type: create, modify, delete
This creates provenance, the ability to trace any line of code back to the conversation that produced it.
What Gets Captured
| Source | Content |
|---|---|
| Claude Code | Full sessions with tool calls, file operations, prompts, and replies |
| Cursor CLI | Chat and Composer sessions with file operations |
| Codex CLI | Session capture with file operations and context |
| Gemini CLI | Session capture with file operations and context |
| Filesystem | All create, modify, delete, and rename operations with content hashes |
Offline Support
The catchup system ensures no changes are lost, even when the daemon isn't running:
- On startup, the daemon creates a baseline snapshot of all tracked files
- It compares the current state against the last known state
- Any changes that occurred while offline are detected and recorded
- Rename detection works even across offline periods via content hash matching
Configuration
Capture behavior is configured through .stoaignore (same syntax as .gitignore) to exclude paths from tracking:
# Dependencies
node_modules/
vendor/
# Build output
dist/
build/
# Large files
*.zip
*.tar.gz