Home › Entities › QueryEngine.ts

QueryEngine.ts

Description

QueryEngine.ts is the largest single file in the Claude Code codebase at approximately 46,000 lines -- not the 1,295 lines sometimes cited in earlier analyses, which refer to a smaller wrapper layer. This monolith is the core LLM API engine that handles streaming communication with Anthropic's API, tool execution orchestration, session transcript management, and state persistence. Every interface to Claude Code -- the terminal CLI, the bridge-system for VS Code and JetBrains, and the cc-protocol for remote sessions -- ultimately funnels through QueryEngine.ts.

Core Responsibilities

Responsibility Description
Streaming Manages Server-Sent Event (SSE) streams from the Anthropic API, parsing partial JSON tokens and feeding them to the streaming-tool-executor and terminal-renderer
Tool execution Dispatches tool calls to the appropriate tool implementation, manages the permission-pipeline approval flow, and collects tool results
Transcript recording Maintains the full conversation transcript with an asymmetric design: assistant messages are stored verbatim, but user messages may be normalized (see message-normalization)
readFileState cache Caches the contents of files read during a session to avoid redundant disk I/O; invalidated when the agent writes to a cached file
Session resume Supports resuming interrupted sessions from persisted state via session-persistence
Compaction Triggers the compaction-pipeline when the transcript approaches the context window limit

Asymmetric Transcript

A notable architectural choice is the asymmetric transcript format. The system records assistant messages with full fidelity (including chain-of-thought tokens when available), but user messages pass through message-normalization's 11 transformations before storage. This means the transcript is not a verbatim record of the conversation but a processed representation optimized for API replay and session resumption.

readFileState Cache

The readFileState cache is a performance optimization that avoids re-reading files from disk when the agent references them multiple times within a session. The cache is keyed by absolute file path and stores the file content at the time it was first read. When the agent uses the Write or Edit tool to modify a file, the cache entry for that path is invalidated so subsequent reads pick up the new content. This cache is distinct from the speculation-engine's prefetching, which predicts files the agent will need next.

Scale and Complexity

At 46K lines, QueryEngine.ts dwarfs most individual source files in major open-source projects. Its size reflects the same organic growth pattern seen in the tt-function -- rapid feature development where new capabilities were layered onto the existing engine rather than extracted into separate modules. The file contains the streaming logic, retry handling, cache-economics optimization, system-prompt-assembly, and the core agent loop that the tt-function orchestrates.

Integration

QueryEngine.ts is the gravitational center of the five-layer-architecture. It integrates with growthbook for feature flag evaluation, frustration-telemetry for user sentiment tracking, the auto-mode-classifier (via yolo-classifier) for permission decisions, and the memory-hierarchy for context enrichment. The forked-agent-pattern spawns child QueryEngine instances for parallel task execution.

Key claims

Relations

Sources

src-20260409-6913a0b93c8b