LocAgent: Graph-Guided Code Localization

• LocAgent is a framework for code localization that identifies precise code regions by modeling repository structure as a directed heterogeneous graph.
• It combines BM25-based lexical search with multi-hop graph traversal to bridge gaps between natural-language issues and code implementation.
• Demonstrated on Python repositories, LocAgent achieves up to 92.70% file localization accuracy at lower cost compared to proprietary agents.

Searching arXiv for the primary LocAgent paper and closely related code-localization follow-ups. LocAgent is a framework for code localization, defined as the task of identifying precisely where in a repository changes need to be made in response to a natural-language software issue. It formulates localization as graph-guided agentic search over a codebase parsed into a directed heterogeneous graph, so that an LLM can traverse structural and dependency relations rather than relying only on flat lexical retrieval. In its primary formulation, LocAgent targets Python repositories, couples BM25-based entity lookup with multi-hop graph exploration, and uses a single-turn chain-of-thought-driven agent equipped with three graph tools. Reported results show file-level localization accuracy up to 92.70% on SWE-Bench-Lite with a fine-tuned Qwen-2.5-Coder-Instruct-32B model, performance comparable to a state-of-the-art proprietary agent at substantially lower cost, and measurable gains in downstream issue resolution (Chen et al., 12 Mar 2025).

1. Problem setting and conceptual basis

LocAgent addresses a recurrent failure mode in repository-level software engineering: natural-language issue descriptions rarely identify the exact files, classes, or functions that must be edited. The core difficulty is not merely retrieval, but reasoning across hierarchical structure and multiple dependencies. A bug report may mention a symptom in one module while the required modification lies in a helper, imported utility, inherited method, or deeper invocation chain. LocAgent is designed specifically for that mismatch between issue text and implementation topology (Chen et al., 12 Mar 2025).

The framework represents a codebase as a lightweight directed heterogeneous graph

$$\mathcal{G} = (\mathcal{V}, \mathcal{E}, \mathcal{A}, \mathcal{R}),$$

where $\mathcal{V}$ is the node set, $\mathcal{E}$ the directed edge set, $$\mathcal{A}=\{\text{directory},\text{file},\text{class},\text{function}\}$$ the node-type vocabulary, and $$\mathcal{R}=\{\text{contain},\text{import},\text{invoke},\text{inherit}\}$$ the relation vocabulary. Every node has a type $\tau(v)\in\mathcal{A}$ and every edge has a type $\phi(e)\in\mathcal{R}$ (Chen et al., 12 Mar 2025).

This design places LocAgent within a broader shift from one-shot repository retrieval toward structured exploration. A plausible implication is that the method treats localization less as nearest-neighbor search over code text and more as constrained reasoning over program organization and inter-entity dependencies. That interpretation is reinforced by the framework’s explicit use of multi-hop traversal and self-consistency ranking.

2. Graph construction and repository indexing

For Python repositories, LocAgent constructs its graph in three stages. First, it parses the directory tree so that each directory and each .py file becomes a node, with contain edges encoding the filesystem hierarchy. Second, for each file it builds an AST; every class and every nested function definition yields an additional node, and further contain edges connect file-to-class, file-to-function, and class-to-inner-function relations. Third, it records cross-module relations: import edges from file nodes to imported classes or functions, invoke edges from function or class nodes to called or instantiated functions and classes, and inherit edges between superclass and subclass class nodes (Chen et al., 12 Mar 2025).

The resulting graph combines two kinds of information that are often separated in earlier localization pipelines: hierarchical containment and semantic dependency structure. Containment encodes where an entity lives; import, invocation, and inheritance edges encode how execution or reuse may connect seemingly distant regions of the repository. This is the substrate that enables multi-hop reasoning from a symptom-bearing node to a root-cause node.

LocAgent supplements the graph with sparse text indexes. It builds BM25 inverted indexes over each node’s source code snippet and mappings from simple names to fully qualified entity identifiers. These indexes are not auxiliary conveniences; the ablation study shows that removing SearchEntity, effectively discarding the text index, produces the single largest performance loss, exceeding 20 points in function Acc@10 (Chen et al., 12 Mar 2025). That result directly counters a common misconception that graph reasoning alone is sufficient. In LocAgent, graph traversal depends on a strong lexical entry point.

The framework is described as lightweight, with indexing time of a few seconds for a medium-sized Python repository and minimal storage overhead for the node store and inverted index. This suggests that the graph is intended as an operational search structure rather than a heavyweight whole-program analysis artifact.

3. Agent architecture and reasoning loop

LocAgent implements a single-turn LLM agent that interleaves reasoning with three unified tool calls (Chen et al., 12 Mar 2025).

Tool	Input	Output
SearchEntity	keyword list	top-$k$ matching entity IDs and snippet previews
TraverseGraph	start IDs, direction, hops, filters	tree-formatted subgraph
RetrieveEntity	entity IDs	file path, line spans, source code

The reasoning loop is governed by a chain-of-thought prompt template. Operationally, the agent extracts keywords from the issue description, invokes SearchEntity to obtain candidate code entities, repeatedly uses TraverseGraph for one-hop exploration over promising nodes with relation filters such as import, invoke, and inherit, and finally calls RetrieveEntity on high-confidence candidates to return the full code regions (Chen et al., 12 Mar 2025).

The paper’s pseudocode makes two additional design choices explicit. First, traversal is iterative and selective: the agent repeatedly chooses next-hop entities from the current subgraph and updates its reasoning state as new graph fragments are exposed. Second, final ranking is produced by RankByConsistency, which aggregates reciprocal-rank scores over multiple LLM invocations. In the paper’s terminology, this is “self-consistency over multiple runs” (Chen et al., 12 Mar 2025). A plausible implication is that LocAgent treats localization as a stochastic inference problem over search trajectories rather than a single deterministic pass.

The qualitative examples clarify the intended failure-recovery behavior. In an “XSS vulnerability in user profile” issue, the agent extracts sanitize, follows an import-to-invoke chain, and localizes to a shared validation helper file not named in the issue. In an “API response latency” issue, it traverses the call graph three hops from an endpoint to database client code and pinpoints missing index usage in a SQL builder class (Chen et al., 12 Mar 2025). These examples are illustrative rather than exhaustive, but they capture the framework’s central claim: graph-guided traversal is meant to recover latent causality that surface text does not directly expose.

4. Fine-tuning strategy and model variants

To reduce dependence on proprietary APIs, the primary open-model variant fine-tunes Qwen-2.5-Coder-Instruct-32B on 768 successful agent trajectories. The training set consists of 433 correct traces generated by Claude-3.5 on SWE-Bench training issues and 335 high-confidence traces generated by the initial Qwen-2.5-32B model. Fine-tuning uses supervised fine-tuning with LoRA adapters for 5 epochs, learning rate $2\times 10^{-4}$, maximum context length 128k tokens, and batch size tuned for GPU memory. The objective is standard next-token cross-entropy (Chen et al., 12 Mar 2025):

$$\mathcal{L}(\theta) = -\sum_{(x,y)\in\mathcal{D}} \sum_{t=1}^{|y|} \log P_\theta(y_t \mid y_{<t}, x).$$

The same trajectory set is then used to LoRA-fine-tune a smaller Qwen-2.5-7B variant by distillation (Chen et al., 12 Mar 2025). This two-model setup is significant because it separates two claims often conflated in agentic software engineering. One claim is architectural: graph-guided traversal improves localization. The other is model-specific: larger proprietary LLMs are needed to realize those gains. LocAgent’s training protocol is presented as evidence for the first claim while weakening the second.

The framework does not train a specialized graph neural network or an end-to-end policy learner. Instead, it trains the LLM to produce effective reasoning-and-tool-use trajectories over a fixed graph interface. This suggests that LocAgent’s inductive bias lies primarily in the repository representation and tool schema, with model adaptation serving to improve tool selection and reasoning consistency rather than to replace symbolic search with latent computation.

5. Evaluation protocol, performance, and empirical interpretation

LocAgent is evaluated on two datasets. SWE-Bench-Lite contains 274 Python issues, described as predominantly bug-fix patches. Loc-Bench contains 660 up-to-date GitHub issues spanning 282 bug reports, 203 feature requests, 31 security issues, and 144 performance issues (Chen et al., 12 Mar 2025).

The reported metrics distinguish multiple granularities. File-level localization uses

$\mathcal{V}$0

Module-level success is defined by finding any function in the affected module; function-level localization is the analogous Acc@k over functions; Pass@k measures downstream repair success when localization is paired with a separate LLM-based repair step (Chen et al., 12 Mar 2025).

Setting	Result	Context
LocAgent + Qwen-2.5-32B(ft)	92.70% file Acc@5	SWE-Bench-Lite
Claude-3.5 (SOTA agent)	94.16% file Acc@5	SWE-Bench-Lite
Cost per example	$\mathcal{V}$$10.66</td> <td>LocAgent vs. Claude-3.5</td> </tr> <tr> <td><strong>Pass@10 improvement</strong></td> <td>+12<td>over Agentless</td> </tr> </tbody></table></div> <p>On Loc-Bench, file Acc@10 reaches 87.06$$0.05 per example (Chen et al., 12 Mar 2025). The paper also states an approximate 86% cost reduction for the fine-tuned 32B open model relative to the proprietary baseline. The ablation results are especially informative. Performance degrades gracefully as the graph distance between symptom and fix increases, but LocAgent still outperforms retrieval and Agentless by 10–20 points at higher distances. Removing traversal edges or restricting hops to 1 causes a 4–5 point drop in function Acc@10. Dropping SearchEntity causes a loss exceeding 20 points (Chen et al., 12 Mar 2025). These results suggest a two-stage dependency: lexical search provides the initial candidate frontier, while graph traversal becomes increasingly valuable as causal distance grows. Cross-benchmark evidence adds nuance to these results. In SWE-Explore, which isolates repository exploration under a fixed line budget, LocAgent achieves HitRegion 0.472, precision 0.642, line-level recall 0.191, nDCG@500 0.950, and context efficiency 0.799 (Zhang et al., 5 Jun 2026). This indicates that modern file-level localization strength does not automatically translate into high line-level recall. By contrast, OrcaLoca reports a function match rate of 65.33% and file match rate of 83.33% on SWE-bench Lite, with a different emphasis on scheduling, action decomposition, and context pruning (Yu et al., 1 Feb 2025). Taken together, these comparisons suggest that LocAgent’s strength lies in high-precision graph-guided repository navigation, while fine-grained span coverage remains an active optimization target. 6. Extensions, scope, and disambiguation LocAgent has already become a substrate for follow-on systems. “Improving Code Localization with Repository Memory” augments vanilla LocAgent with non-parametric repository memory built from commit history. Its episodic and semantic memory modules add tools such as SearchCommit, ExamineCommit, SearchSummary, and ViewSummary. On SWE-bench-verified and SWE-bench-live, the combined memory variant improves file-level Acc@5 over vanilla LocAgent by 4.9 points and 3.1 points, respectively, while reducing TraverseGraph calls by approximately 40% (Wang et al., 1 Oct 2025). This suggests that graph reasoning and repository history are complementary rather than competing sources of signal. “Multi-CoLoR” generalizes the framework beyond Python by combining a similar issue context module with an extended LocAgent traversal agent for C++ and QML codebases. In that setting, Multi-CoLoR improves Acc@5 over both lexical and graph-only baselines while reducing or matching tool calls, with particularly large gains on QML and C++ subsets (Vats et al., 23 Feb 2026). A plausible implication is that the core LocAgent idea is not intrinsically Python-specific, even though the original implementation is. The primary limitations are explicit. LocAgent is currently Python-only because graph construction depends on a Python AST parser; supporting additional languages requires new parsers. The dependence on chain-of-thought prompting and self-consistency adds latency, reported as 5–9 LLM calls per instance, although the system remains cost-effective. Future work in the original paper includes broader base models such as CodeLlama and Mistral, richer downstream tasks such as refactoring and performance tuning, and expanded multi-language support (Chen et al., 12 Mar 2025). The term “LocAgent” is also used in unrelated literatures. In wireless and mobile-agent localization, it refers to a distributed linear localization methodology based on barycentric coordinates and Cayley–Menger determinants (Safavi et al., 2018). In later geolocation research, near-homonymous or explicitly glossed usages appear in image geolocation systems such as “LocationAgent” and in descriptions of “GeoAgent” (Li et al., 27 Jan 2026, Jin et al., 13 Feb 2026). In software engineering, however, the term denotes the graph-guided LLM agent framework for code localization introduced in 2025 (Chen et al., 12 Mar 2025). Within repository-level software engineering, LocAgent is best understood as a graph-first localization architecture: a compact heterogeneous code graph, sparse lexical indexing, and an LLM agent trained to use tool-mediated multi-hop reasoning. Its empirical profile is correspondingly specific. It is not an end-to-end repair system, not a pure retriever, and not merely a prompt engineering variant. It is a localization front-end whose defining claim is that code search becomes materially more effective when issue text is grounded in repository structure and traversed through explicit graph operations (Chen et al., 12 Mar 2025). Topic to Video (Beta) No one has generated a video about this topic yet. Whiteboard No one has generated a whiteboard explanation for this topic yet. Follow Topic Get notified by email when new papers are published related to LocAgent. Continue Learning How does LocAgent integrate BM25 search with graph-guided traversal for improved code localization?  What role does the directed heterogeneous graph play in modeling repository structure within LocAgent?  How does the single-turn LLM agent in LocAgent leverage chain-of-thought prompting to guide its tool calls?  What are the potential limitations and future directions for extending LocAgent to programming languages beyond Python?  Find recent papers about graph-guided code localization.  Related Topics GraphCodeAgent: Dual-Graph Code Generation  Graph-Based Learning for Function Localization  FastCode: Structural Code Reasoning Framework  Software Engineering Agents (SWE-Agents)  SWE-Explore Benchmark  Prometheus: Multi-Agent Issue Resolution  SHERLOC: Code Repair Localization  Repository Structural Semantic Graph (RSSG)  Source Code Agent Framework  RepoTransAgent: Repo-Aware Code Translation  Content Overview References Topic to Video Whiteboard Follow Topic Continue Learning Related Topics Stay informed about trending AI papers: About Whiteboards Videos Labs Email Digest Chrome Extension RSS Terms Privacy Contact Twitter Discord YouTube