LocAgent: Graph-Guided LLM Agents for Code Localization

TL;DR

This paper tackles code localization by bridging natural language issue descriptions to precise code changes through LocAgent, a framework that represents codebases as a heterogeneous directed graph of files, classes, and functions with rich dependency edges. It introduces a lightweight, sparse indexing scheme and a unified set of agent tools (SearchEntity, TraverseGraph, RetrieveEntity) to enable multi-hop reasoning by LLMs, yielding strong localization performance at reduced cost. To support robust evaluation, Loc-Bench is proposed as a diverse benchmark addressing contamination and maintenance-task coverage beyond bug fixes, demonstrating the practicality of open-source model fine-tuning (Qwen-2.5-Coder-Instruct) via LoRA to rival proprietary models. The results show improved localization accuracy and positive downstream effects on GitHub issue repair, underscoring the method’s potential for real-world software maintenance and scalable deployment.

Abstract

Code localization--identifying precisely where in a codebase changes need to be made--is a fundamental yet challenging task in software maintenance. Existing approaches struggle to efficiently navigate complex codebases when identifying relevant code sections. The challenge lies in bridging natural language problem descriptions with the appropriate code elements, often requiring reasoning across hierarchical structures and multiple dependencies. We introduce LocAgent, a framework that addresses code localization through graph-based representation. By parsing codebases into directed heterogeneous graphs, LocAgent creates a lightweight representation that captures code structures (files, classes, functions) and their dependencies (imports, invocations, inheritance), enabling LLM agents to effectively search and locate relevant entities through powerful multi-hop reasoning. Experimental results on real-world benchmarks demonstrate that our approach significantly enhances accuracy in code localization. Notably, our method with the fine-tuned Qwen-2.5-Coder-Instruct-32B model achieves comparable results to SOTA proprietary models at greatly reduced cost (approximately 86% reduction), reaching up to 92.7% accuracy on file-level localization while improving downstream GitHub issue resolution success rates by 12% for multiple attempts (Pass@10). Our code is available at https://github.com/gersteinlab/LocAgent.

Figures (8)

• Figure 1: Code localization across four common programming scenarios. Given a codebase and an issue description, the goal of code localization is to identify the relevant code snippets that require modification to resolve the issue.
• Figure 2: Overview of LocAgent framework. LocAgent first parses the given codebase to build a graph-based code representation with various types of entities and relations. It then constructs sparse indexes for exploring structures and searching content. Using these indexes, it performs agent-guided searches that combine the graph and tools.
• Figure 3: Performance analysis at different difficulty levels for file- and function-level localization. All agent-based methods and Agentless use Claude-3.5 as the localization model. Hop $N$ refers to the distances between functions mentioned in the issue description and the ground truth patch on our code graph.
• Figure 4: Comparison of performance between the original and fine-tuned Qwen models. The metrics used are file-level Acc@5 and module/function-level Acc@10. Dashed lines represent the performance of the Claude-3.5 model for reference.
• Figure 5: Performance analysis at different difficulty category for file- and function-level localization. All agent-based baselines and Agentless use Claude-3.5 as the localization model.

Theorems & Definitions (1)

• Remark