FastCode: Structural Code Reasoning Framework

• FastCode is a repository-scale code reasoning framework that uses lightweight structural scouting to identify high-value code units before full content ingestion.
• It employs a multi-layered graph representation and hybrid indexing, combining lexical and semantic signals for efficient repository navigation.
• Evaluations show that FastCode achieves significant cost reductions and improved accuracy over traditional full-context methods in various benchmarks.

Searching arXiv for the FastCode paper and closely related repository-scale code reasoning work to ground the article. FastCode is a repository-scale code reasoning framework for AI-assisted software engineering that is designed to improve the accuracy–cost trade-off by decoupling repository exploration from content consumption. Instead of treating a codebase as flat text or repeatedly opening files during an iterative agent loop, it first scouts the repository through lightweight structural evidence, identifies likely-relevant code units, and only then ingests full source content for a small, high-value context. In the formulation introduced with the framework, repository reasoning is organized around structural scouting, graph-guided navigation, and cost-aware context construction rather than full-text exploration by default (Li et al., 1 Mar 2026).

1. Problem setting and conceptual departure

FastCode addresses a central bottleneck in repository-level code reasoning: balancing reasoning quality against context cost. Modern coding agents and long-context LLM workflows can support question answering, bug localization, and repository-scale task execution, but they often do so by repeatedly inspecting source files, revising hypotheses, and accumulating large interaction histories. The result is high token consumption and, in many cases, structurally noisy contexts. FastCode is explicitly positioned against three broad alternatives: iterative agentic exploration, flat retrieval-augmented generation, and full-context strategies that attempt to feed large portions of a repository directly into the model (Li et al., 1 Mar 2026).

The framework’s conceptual departure is the claim that a repository should not be “read” uniformly during search. Instead, it should first be navigated through structure. This means using paths, signatures, metadata, imports, inheritance links, and call relations as the primary substrate for exploration, while delaying full source ingestion until the system has localized a compact set of likely-relevant targets. The paper identifies this as a scouting-first strategy: exploration is cheap, content reading is selective, and prompt construction is treated as an optimization problem rather than a by-product of repeated tool use.

This design directly targets the failure modes of flat chunk-based retrieval. Chunking may sever imports, inheritance relationships, or call chains, thereby obscuring dependencies that are fundamental for repository-scale reasoning. Long-context approaches avoid retrieval misses but incur large context costs and may still expose the model to substantial irrelevant material. FastCode therefore separates “where to look” from “what to read,” and treats that separation as the basis for improved efficiency.

2. Repository representation and structural priors

FastCode formalizes a repository as a directed semantic map

$\mathcal{G}=(\mathcal{U},\mathcal{E}),$

where $\mathcal{U}$ denotes hierarchical code units and $\mathcal{E}$ denotes dependencies (Li et al., 1 Mar 2026). The hierarchy has four levels: file, class, function, and documentation. Each unit stores lightweight metadata such as signatures, docstrings, and line ranges rather than full implementations. This representation is intended to preserve repository shape while keeping exploration inexpensive.

On the retrieval side, FastCode uses multi-grained hybrid indexing. A sparse BM25 index provides lexical matching, while a dense embedding index provides semantic matching. The combination is meant to recover both exact symbol-level matches and semantically related code units that might not share surface forms. The system therefore does not rely on either pure sparse lookup or pure dense similarity.

The structural layer is a multi-layered graph consisting of dependency edges $G_{dep}$, inheritance edges $G_{inh}$, and call edges $G_{call}$. In the appendix, graph construction is described as AST-based, augmented with global symbol resolution for aliased and relative imports and scope-constrained type inference for dynamic call resolution such as self.loader.load(). This is a notable aspect of the framework because the graph is not merely a static file-linking device; it is the medium through which code units can be expanded during navigation.

A plausible implication is that FastCode treats repository reasoning as a structured search problem over graph-linked abstractions rather than a retrieval problem over isolated text spans. That interpretation is consistent with the paper’s emphasis on semantic-structural maps and graph expansion.

3. Structural scouting and navigation loop

FastCode begins reasoning with query augmentation. The query is analyzed for intent, rewritten to align more closely with repository semantics, and expanded with keywords. The framework can also generate pseudocode hints with the LLM to surface algorithmic structure, API usage, and control-flow patterns that may not appear verbatim in the original query (Li et al., 1 Mar 2026). The result is three complementary query views: semantic, lexical, and structural.

The core navigation mechanism is structural scouting. Rather than immediately opening files, the system uses lightweight tools: directory traversal and regex-enhanced codebase search. Directory traversal returns files under a path; codebase search returns file paths and match counts without loading full file contents. These results are transformed into structural metadata, including paths, signatures, match density, and related units. The agent reasons over this metadata to prioritize candidates before any expensive content ingestion occurs.

The paper describes navigation as an iterative decision process over rounds $t \in \{1,\dots,T\}$. In each round, candidates from retrieval and tools are merged, expanded through the repository graph, and consolidated into a metadata list. Each candidate is represented by provenance, structural identity, and cost metrics. The agent then decides whether to keep a unit, continue scouting, or terminate exploration. This organization makes the navigation loop neither purely symbolic nor purely retrieval-driven; it is a mixed agentic process constrained by structure.

The practical significance of this loop lies in what it avoids. FastCode does not repeatedly inspect arbitrary full-text chunks simply because they were retrieved. Instead, it uses structural evidence to defer reading until the candidate set is already filtered. The paper’s ablation study identifies this scouting-and-navigation stage as the most critical source of benefit, with the largest degradations occurring when query augmentation and tool-based exploration are removed (Li et al., 1 Mar 2026).

4. Cost-aware context construction

FastCode formulates repository reasoning as selecting an optimal context

$$y = \mathcal{M}(q, \mathcal{C}^*), \quad \mathcal{C}^* = \operatorname*{argmax}_{\mathcal{C} \subset \mathcal{U}} \big[\operatorname{Rel}(\mathcal{C}\mid q) - \lambda \Omega(\mathcal{C})\big].$$

Here $\operatorname{Rel}$ measures utility for the query, $\Omega$ measures computational or token overhead, and $\mathcal{U}$0 controls the trade-off (Li et al., 1 Mar 2026). This is the framework’s formal statement of the accuracy–cost objective.

To operationalize this inside the agent loop, FastCode defines a state vector

$\mathcal{U}$1

where $\mathcal{U}$2 is estimated query complexity, $\mathcal{U}$3 is repository entropy or structural complexity, $\mathcal{U}$4 is cumulative context size, $\mathcal{U}$5 is iteration depth, and $\mathcal{U}$6 is epistemic confidence. The dynamic budget is set proportional to query complexity and repository entropy, $\mathcal{U}$7. This means context expansion is not fixed globally; it adapts to the estimated difficulty of both the query and the codebase.

Stopping is governed by confidence and information gain. The paper defines an information gain rate

$\mathcal{U}$8

and continues exploration only while new context materially improves confidence (Li et al., 1 Mar 2026). Termination occurs when confidence exceeds a threshold $\mathcal{U}$9, when consecutive steps provide low gain, or when the budget is exhausted. There is also a fast path: if initial scouting already yields high confidence, the framework bypasses further exploration and proceeds to verification or refinement.

When choosing among candidate units, FastCode uses the priority function

$\mathcal{E}$0

In practice, units are greedily retained until the line budget $\mathcal{E}$1 is reached. This selection rule encodes the framework’s preference for small, high-value contexts over expansive but weakly relevant ones. A plausible implication is that FastCode replaces naive “retrieve more context” behavior with a bounded resource-allocation policy for code understanding.

5. Evaluation and empirical profile

FastCode is evaluated on SWE-QA, LongCodeQA, LOC-BENCH, and GitTaskBench, covering repository-level question answering, long-context comprehension, file localization, and end-to-end repository tasks (Li et al., 1 Mar 2026). The baselines span direct prompting, retrieval-augmented methods, agentic systems, and commercial tools, including zero-shot and full-context prompting, Func RAG, Sliding RAG, File BM25 RAG, SWEQA-Agent, Agentless, MoatlessTools, SWE-agent, OpenHands, LocAgent, DeepWiki, CodeWiki, Gemini Code, Claude Code, and Cursor.

The reported results emphasize both reasoning performance and cost control.

Benchmark	FastCode result	Cost note
SWE-QA	43.28 total score	\$0.032
LongCodeQA	77.9 with Gemini 2.5 Pro at 32K	about \$\mathcal{E}$20.073 across lengths</td> </tr> <tr> <td>LOC-BENCH</td> <td style="text-align: right">86.13% Acc@1 with <a href="https://www.emergentmind.com/topics/gemini-3-flash-7074d7e4-1d0d-4a14-be69-abe7a93544ea" title="" rel="nofollow" data-turbo="false" class="assistant-link" x-data x-tooltip.raw="">Gemini-3-Flash</a></td> <td style="text-align: right">Qwen3-Coder-30B at \$0.0038 per instance
GitTaskBench	57.41% TPR and 74.07% ECR with Claude 3.7 Sonnet	reductions from about 15× to over 2000×

On SWE-QA, FastCode scores 43.28, slightly above Cursor’s 43.17 and above SWEQA-Agent’s 42.33. Against direct LLM prompting, the increase is from 32.30 to 43.28, with completeness rising from 3.71 to 7.94 and reasoning from 4.91 to 8.72. The appendix reports a cost of \$\mathcal{E}$30.057 for Claude Code and \$0.071 for Cursor, corresponding to a 43.86% reduction versus Claude Code and about 55% versus Cursor (Li et al., 1 Mar 2026).

On LongCodeQA, the framework’s cost profile remains near constant as context length grows, while direct full-context costs rise sharply. The paper highlights an average cost reduction of 83.01% on comparable lengths. As an example, Gemini 2.5 Pro rises from 65.5 at 32K to 77.9 with FastCode, and from 66.6 to 78.5 at 256K, with more than 90% cost reduction in the latter setting. This supports the claim that FastCode suppresses the context tax associated with long-context repository reasoning.

On LOC-BENCH, FastCode reaches 86.13% Acc@1 with Gemini-3-Flash, exceeding LocAgent’s 77.74% by 8.39 points. Its Acc@3 and Acc@5 are 94.16% and 95.62%. The paper also reports that a local Qwen3-Coder-30B variant achieves 75.55% Acc@1 at only \$0.0038 per instance, roughly 99.4% lower cost than the best baseline configuration (Li et al., 1 Mar 2026).

On GitTaskBench, FastCode achieves 46.30% TPR and 61.11% ECR with Claude 3.5 Sonnet, and 57.41% TPR and 74.07% ECR with Claude 3.7 Sonnet. The framework is described as capable of outperforming stronger, more expensive baselines at much lower cost; for example, FastCode with Gemini-3-Flash reaches 53.70% TPR at a small fraction of the cost of OpenHands.

6. Ablations, limitations, and position within code-reasoning research

The ablation study clarifies how FastCode’s components interact. Removing hybrid retrieval slightly reduces performance, indicating that lexical and dense search remain useful for initial candidate discovery. Removing graph expansion degrades results further, showing that dependency, inheritance, and call traversal contribute non-lexical evidence. Removing cost-aware context management also lowers performance, which the paper attributes to the loss of budget control and confidence-based stopping. The largest declines occur when navigation mechanisms are removed, especially query augmentation and tool-based exploration; removing tool scouting while keeping query augmentation still causes a substantial drop (Li et al., 1 Mar 2026).

The framework also exhibits backbone sensitivity in a favorable way: it improves both small and large models. On SWE-QA, reported gains include Ministral-3B from 27.39 to 36.13, DeepSeek-R1-8B from 30.11 to 38.56, Qwen3-Coder-30B from 35.77 to 41.44, and Gemini-3-Flash from 32.65 to 43.44. This suggests that context construction quality can be a stronger bottleneck than parameter count for repository reasoning.

The paper nevertheless identifies several limitations. FastCode depends on the quality of repository structure extraction and symbol resolution; dynamic language behavior, incomplete static analysis, or missing graph edges may cause relevant paths to be overlooked. Query complexity and repository entropy are heuristic estimates and may mischaracterize unusually ambiguous or cross-cutting tasks. The navigation loop assumes that metadata is sufficient to prune effectively, which may fail for weakly signposted tasks. In addition, the framework still relies on an LLM for query rewriting, pseudocode generation, and confidence assessment, so it is not a zero-overhead approach.

Within the broader landscape of AI-assisted software engineering, FastCode is best understood as a structural alternative to both flat retrieval and brute-force long-context ingestion. Its central claim is not merely that less context can be used, but that repository structure can be used to decide which context is worth paying for. This suggests a general shift in repository-scale reasoning: from text-first exploration to structure-first navigation, with full source consumption reserved for a final, deliberately constructed context (Li et al., 1 Mar 2026).