PostToolUse Build Detection & File Tracking
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
PostToolUse Build Detection & File Tracking is a critical subsystem of Continuous Claude designed to capture artifacts, changes, and observations immediately following the execution of MCP (Model Context Protocol) tools. This system ensures that every file modification, task outcome, and build signal is recorded into the persistent Context Graph, preventing context loss during session resets or compactions.
The primary goal of this mechanism is to automate the extraction of "what was done" and "what changed" so that subsequent sessions can resume with high fidelity. It bridges the gap between raw tool execution and structured session memory by leveraging hooks that trigger analysis scripts, such as artifact_index.py and braintrust_analyze.py, to update local ledgers and remote tracing databases.
Sources: CLAUDE_ONBOARDING.md:12-25, CLAUDE.md:144-150
Architecture and Data Flow
The system operates as a reactive pipeline triggered by the PostToolUse event. When a tool finishes execution, the Claude Code environment invokes a registered hook which then orchestrates file tracking and builds detection.
Lifecycle of PostToolUse Tracking
- Tool Completion: An MCP tool (e.g.,
edit_fileorbash) completes its operation. - Hook Execution: The
PostToolUsehook is triggered (e.g.,save-hook.js). - Observation Capture: The system captures raw observations from the tool's output.
- Artifact Indexing: The
artifact_index.pyscript parses modified files and updates the SQLite-based Context Graph. - Build/Validation Detection: The system checks for success or failure signals (e.g., build logs or test results).
The diagram shows how a single tool completion triggers multiple parallel tracking paths for memory, artifact indexing, and performance analysis.
Sources: CLAUDE.md:152-162, scripts/artifact_index.py:270-300
File Tracking and Artifact Indexing
File tracking is primarily handled by the artifact_index.py script, which identifies changes in specific project directories like thoughts/shared/handoffs and thoughts/shared/plans. It uses MD5 hashing to generate unique IDs for file snapshots and extracts metadata such as task numbers and session names.
The Indexing Logic
The indexer performs regex-based extraction to identify modified files listed within markdown handoffs. It looks for patterns like backticked paths (e.g., `src/main.py`) or explicit **File**: headers.
def extract_files(content: str) -> list:
"""Extract file paths from markdown content."""
files = []
for line in content.split("\n"):
# Match common patterns like "- `path/to/file.py`"
matches = re.findall(r"`([^`]+\.[a-z]+)(:[^`]*)?`", line)
files.extend([m[0] for m in matches])
# Match **File**: format
matches = re.findall(r"\*\*File\*\*:\s*`?([^\s`]+)`?", line)
files.extend(matches)
return files
Sources: scripts/artifact_index.py:108-119, scripts/artifact_index.py:140-155
Database Schema for Tracking
The tracking information is stored in a SQLite database (context.db) with FTS5 enabled for full-text search. The handoffs table is central to tracking file modifications and outcomes.
| Field | Type | Description |
|---|---|---|
id | TEXT | Primary Key (MD5 prefix of file path) |
files_modified | TEXT | JSON array of paths modified in the task |
outcome | TEXT | Canonical status (SUCCEEDED, FAILED, etc.) |
root_span_id | TEXT | Braintrust trace ID for session correlation |
Sources: scripts/artifact_schema.sql:18-42
Build Detection and Qualitative Scoring
Build detection involves analyzing the "What Worked" and "What Failed" sections of artifacts generated after tool use. The braintrust_analyze.py script provides an LLM-as-judge interface to detect build failures or requirement gaps.
Outcome Classification
The system maps various tool and task statuses into a canonical outcome set used for subsequent retrieval during the SessionStart hook.
This state machine illustrates how the system classifies the result of a tool-induced build or change.
Sources: scripts/artifact_index.py:121-133, scripts/braintrust_analyze.py:530-550
Post-Mortem Analysis
The PostToolUse logic encourages the capture of "Post-Mortems" which are stored in the Context Graph. This includes:
- What Worked: Successful patterns detected after tool execution.
- What Failed: Specific error messages or blocked approaches (e.g., regex being too greedy).
- Key Decisions: Rationale for choosing a specific implementation (e.g., SQLite vs Postgres).
Sources: scripts/artifact_index.py:80-95, scripts/braintrust_analyze.py:650-670
Conclusion
The PostToolUse Build Detection & File Tracking system is the foundation of the project's continuity. By automatically indexing file changes and detecting build outcomes immediately after tool usage, it ensures that the Context Graph remains an accurate reflection of the project's state. This allows Continuous Claude to survive context wipes (/clear) by providing a searchable, high-fidelity history of every technical decision and modification made during a session.