Skip to content

RepoNav: From Snippet Retrieval to File-Centered Repository Navigation for Code Agents

Conference: EMNLP 2026
Paper: ACL Anthology
Code: https://github.com/CCChz233/reponav
Area: LLM Reasoning
Keywords: Code Agents, Repository Navigation, Code Retrieval, Structured Scaffold, Fine-Grained Localization

TL;DR

Addressing the pervasive "file-to-function gap" where code agents successfully surface the correct file but fail to locate the target function, RepoNav introduces a lightweight post-retrieval interface that reorganizes flat snippets into file-centered tree scaffolds paired with an on-demand symbol browsing tool, significantly boosting function-level localization across seven LLMs without requiring repository-wide graph indexing.

Background & Motivation

In autonomous software engineering driven by large language models, resolving real-world repository issues or localizing bugs requires agents to navigate across multiple granularities: first identifying relevant files within vast codebases, and then pinpointing the specific functions, methods, or classes within those files. Modern code agents typically interface with repositories through raw command-line shells (such as Bash) or dense/sparse retrieval tools that return flat lists of top-scoring code chunks. While flat snippet retrieval effectively surfaces coarse-grained candidate files, it strips away the structural hierarchy inherent to source code, presenting code chunks as detached fragments with minimal contextual information about what else exists in the enclosing file.

A fine-grained failure analysis across diverse LLM backbones on LocBench reveals a critical structural bottleneck: between 44% and 58% of function-level localization misses occur after the agent has already navigated to the correct file (the "Correct File, Wrong Function" failure mode). Deep inspection demonstrates that this discrepancy is driven by premature anchoring: when presented with flat snippet outputs, agents fixate on the most salient entry-point symbols—such as public wrappers, request handlers, or high-scoring dispatchers—and commit to them before examining sibling functions or inspecting the broader file layout. Flat snippet retrieval exacerbates this fixation by mixing relevant targets and distractor chunks without exposing the underlying file skeleton or offering clear continuation pathways, trapping the agent in an attention deficit akin to the "lost in the middle" phenomenon.

While recent research has explored building repository-wide structural representations—such as code knowledge graphs and static dependency databases in RepoGraph, CodexGraph, and LocAgent—these heavyweight approaches require costly offline precomputation, complex graph storage infrastructure, and specialized query syntaxes that increase deployment friction. This paper investigates an orthogonal perspective: can post-retrieval evidence presentation alone bridge the file-to-function gap without altering the underlying dense retrieval index or prebuilding global graphs? Core idea: reorganize retrieved code chunks into a lightweight, file-centered tree scaffold with lexical anchors, structural glimpses, and actionable target shortlists, complemented by on-demand symbol browsing that prompts agents to inspect sibling symbols before commitment.

Method

Overall Architecture

RepoNav operates as a pure post-retrieval interface layer that preserves the underlying dense retrieval backend, chunk embeddings, and similarity scores. Its workflow consists of two deterministic, local stages: first, candidate file aggregation via a hybrid scoring rule that combines peak evidence strength with distributed chunk support; second, dynamic structural extraction via Python's standard ast module for only the top-\(k\) candidate files (\(k=5\)), auto-expanding the top three candidate files into a compact, indentation-based plain-text tree scaffold. Additionally, the environment provides an on-demand tool, list_symbols, allowing the agent to inspect file skeletons interactively.

%%{init: {'flowchart': {'rankSpacing': 24, 'nodeSpacing': 28, 'padding': 6, 'wrappingWidth': 400}}}%%
flowchart TD
    A["Agent Retrieval Query"] --> B["Stage 1: Hybrid File Aggregation Scoring<br/>Balance Peak Evidence & Multi-Region Support"]
    B --> C["Stage 2: Three-Block Tree Scaffold Construction<br/>Dynamic AST Extract: Anchors + Glimpse + Candidates"]
    C --> D["Stage 3: On-Demand Symbol Browsing & Verification<br/>Interactive list_symbols to Compare Sibling Symbols"]
    D -->|Termination| E["Function-Level Target Selection Output"]

Key Designs

1. Hybrid File Aggregation Scoring: Problem of single-chunk distortion -> Mechanism of combining max-pooling and mean-pooling -> Effect of robust file-level prioritization Standard chunk retrieval ranks evidence strictly by individual chunk cosine similarities, which frequently promotes files containing a single spurious keyword match while penalizing files whose relevance is distributed across multiple moderately scored methods. In Stage 1, RepoNav groups all retrieved chunks belonging to candidate file \(f\) into set \(C_f\), ordered such that \(s_{f,(1)} \ge s_{f,(2)} \ge \dots\). To balance peak relevance against multi-region consistency, RepoNav aggregates the top \(m_f = \min(m, |C_f|)\) chunk scores (with \(m=3\) by default) using a hybrid weighting parameter \(\alpha \in [0, 1]\): $\(\text{Score}(f) = \alpha s_{f,(1)} + \frac{1 - \alpha}{m_f} \sum_{i=1}^{m_f} s_{f,(i)}\)$ The first term preserves the sharp signal of an exact top match, while the second term rewards candidate files supported by multiple coherent regions across the file body. Extensive sensitivity experiments demonstrate that ranking performance is remarkably stable across \(\alpha \in [0.3, 0.7]\) (fixed to \(\alpha=0.5\) across all evaluations), reliably surfacing the most credible candidate files for downstream structural parsing without requiring manual tuning.

2. Three-Block Tree Scaffold Construction: Problem of premature anchoring and token overflow -> Mechanism of dynamic AST extraction into anchors, glimpses, and candidate shortlists -> Effect of action-oriented exploration guidance Dumping full file contents into the agent prompt triggers context bloating and distraction, whereas raw snippets offer zero structural cues. In Stage 2, RepoNav applies Python's lightweight built-in ast module (with a median latency of 0.34 seconds) exclusively to the top-\(k\) files (\(k=5\)). For the top three candidate files, it auto-expands an indentation-based tree containing three standardized blocks: (1) [ANCHORS]: up to two symbols identified by case-insensitive substring matching against query tokens, annotated with line ranges and intra-file call neighborhoods (invokes -> and invoked-by <-); (2) [GLIMPSE]: up to three non-anchor structural symbols (or five if no anchor matches) providing a bird's-eye view of other classes and functions in the file to deter premature fixation; (3) [CANDIDATE_TARGETS]: an actionable shortlist capped at four symbols (ordered by anchors, same-file callers/callees, and glimpse symbols) terminated by an explicit continuation cue (>> Next: run list_symbols on this file to inspect sibling symbols.). This turns passive text into an active, navigable menu.

3. On-Demand Symbol Browsing and Verification Protocol: Problem of blind whole-file reading and sibling indistinguishability -> Mechanism of lightweight AST skeleton querying -> Effect of targeted candidate discrimination To verify whether an anchor or a neighboring function constitutes the true target without loading hundreds of lines of implementation logic, RepoNav introduces the environment tool list_symbols(file_path). When invoked by the agent, it executes on-the-fly AST parsing to return imports, class names, top-level functions, methods, their line spans, and parameter signatures, strictly omitting function bodies. The tool performs no ranking and injects no additional retrieval evidence; instead, it acts as an exploratory microscope. In tandem with the scaffold's continuation cues, this protocol nudges the agent to actively inspect sibling definitions and disambiguate public wrapper methods from internal core functions before finalizing its predictions.

Benchmark & Evaluation Protocol

All experiments are implemented on top of the standardized mini-SWE-agent framework with fixed prompts, tool execution limits, and interaction loops. - LocBench Localization Benchmark: Comprises 560 real-world Python repository issues paired with ground-truth modified files and functions. We benchmark four exploration modalities: Bash (shell-only), Snippet Search (flat dense chunks), Snippet+ListSym (flat snippet search with tool-matched list_symbols access to control for browsing capability), and RepoNav. - Retrieval Substrate: CodeRankEmbed embeddings over function-level chunks retrieving 80 raw chunks per query, with UniXcoder evaluated in a 100-instance pilot to verify embedder-agnostic transfer. - SWE-QA-Bench Repository QA Benchmark: Evaluates beyond localization on complex multi-hop code reasoning, scored on a 20-point scale across five criteria: Correctness, Completeness, Relevance, Clarity, and Reasoning (100 points maximum).

Key Experimental Results

Main Results: LocBench Localization Performance

Table 1 reports localization performance across seven state-of-the-art open-weight and proprietary LLMs on all 560 LocBench instances. Metrics include File Acc@5, Module Acc@5, Function Acc@5, and Function Rec@10 (abbreviations: B = Bash, S = Snippet Search, S+L = Snippet+ListSym, R = RepoNav):

Model File Acc@5 (B / S / S+L / R) Module Acc@5 (B / S / S+L / R) Function Acc@5 (B / S / S+L / R) Function Rec@10 (B / S / S+L / R)
Qwen2.5-72B 0.589 / 0.680 / 0.673 / 0.698 0.396 / 0.461 / 0.562 / 0.570 0.254 / 0.300 / 0.384 / 0.434 0.307 / 0.377 / 0.490 / 0.549
GPT-OSS-120B 0.705 / 0.759 / 0.759 / 0.770 0.500 / 0.613 / 0.630 / 0.650 0.339 / 0.464 / 0.488 / 0.527 0.417 / 0.571 / 0.586 / 0.618
Qwen3-Next-80B 0.734 / 0.732 / 0.733 / 0.739 0.523 / 0.568 / 0.589 / 0.632 0.339 / 0.411 / 0.454 / 0.498 0.410 / 0.517 / 0.564 / 0.622
Qwen3-Coder-30B 0.700 / 0.693 / 0.707 / 0.727 0.564 / 0.584 / 0.598 / 0.629 0.420 / 0.459 / 0.476 / 0.516 0.498 / 0.551 / 0.572 / 0.618
MiniMax-M2.5 0.760 / 0.764 / 0.780 / 0.803 0.660 / 0.671 / 0.671 / 0.691 0.525 / 0.532 / 0.534 / 0.601 0.633 / 0.641 / 0.652 / 0.708
GLM-4.7 0.808 / 0.821 / 0.812 / 0.839 0.685 / 0.698 / 0.709 / 0.734 0.585 / 0.600 / 0.577 / 0.632 0.714 / 0.722 / 0.695 / 0.783
Gemini-3-Flash 0.836 / 0.823 / 0.822 / 0.840 0.709 / 0.702 / 0.717 / 0.752 0.625 / 0.623 / 0.648 / 0.689 0.737 / 0.722 / 0.739 / 0.803
Average 0.733 / 0.753 / 0.755 / 0.774 0.577 / 0.614 / 0.639 / 0.665 0.441 / 0.484 / 0.509 / 0.557 0.531 / 0.586 / 0.614 / 0.672

Ablation Study: Representation Volume vs. Navigational Actionability (RQ2)

To investigate whether RepoNav's advantage stems from the raw quantity of structural information or its action-oriented organization, Table 2 evaluates three presentation variants on 560 LocBench instances with GPT-OSS-120B under identical retrieval results, workflows, and tool access:

Interface Variant Func. Acc@5 (%) Func. Rec@10 (%) ListSym Invocation Rate (%) Files Inspected Steps Taken Trace Tokens
File-Only 32.61 44.29 39.11 2.587 10.587 50.2k
Inline Scaffold 46.96 53.84 36.96 2.457 9.630 56.2k
Tree Scaffold (RepoNav) 52.13 60.98 56.61 2.304 9.391 47.2k
Tree vs. Inline \(\Delta\) +5.17 pp +7.14 pp +19.65 pp -6.2% -2.5% -16.0%

Furthermore, block-level leave-one-out ablations (Table 11) confirm the contribution of every scaffold block: - Full Scaffold: Function Acc@5 = 52.13%, Function Rec@10 = 60.98%, ListSym = 56.61%, Tokens = 52.6k. - w/o [ANCHORS]: Acc@5 drops to 48.90% (-3.23 pp), Rec@10 to 57.10% (-3.88 pp), ListSym increases to 68.00%, Tokens rise to 62.8k. - w/o [GLIMPSE]: Acc@5 drops to 49.60% (-2.53 pp), Rec@10 to 58.10% (-2.88 pp), ListSym increases to 66.20%, Tokens rise to 58.7k. - w/o [CANDIDATE_TARGETS]: Acc@5 drops sharply to 44.50% (-7.63 pp), Rec@10 to 53.50% (-7.48 pp), ListSym plummets to 36.60%, Tokens = 54.2k.

Transfer Results: SWE-QA-Bench Repository-Level Question Answering

On SWE-QA-Bench, evaluating cross-file code comprehension across four backbones highlights consistent transfer benefits (Table 3):

Model Bash Total Score Snippet Search Total Score RepoNav Total Score \(\Delta\) vs. Snippet (\(\Delta S\)) \(\Delta\) vs. Bash (\(\Delta B\))
GPT-OSS-120B 76.12 78.97 80.33 +1.36 +4.21
Qwen3-Next-80B 71.72 74.31 76.29 +1.98 +4.57
GLM-4.7 84.96 84.75 86.84 +2.09 +1.88
Gemini-3-Flash 86.53 86.55 88.14 +1.59 +1.61
Average 79.83 81.15 82.90 +1.76 +3.07

Key Findings

  • Tool access alone is insufficient; action-oriented organization unlocks performance: Providing the list_symbols tool to flat snippet search (S+L) yields an average Function Acc@5 increase of +2.5 pp (0.484 to 0.509). RepoNav delivers an additional +4.8 pp jump (to 0.557), demonstrating that the majority of gains stem from structuring evidence into actionable decision scaffolds rather than mere tool availability.
  • Substantial narrowing of the file-to-function gap: Under Bash and Snippet Search, the average file-to-function gap sits at 29.2 pp and 26.9 pp, respectively. RepoNav narrows this gap to 21.7 pp (a 5.2 pp net compression). Even for top models like Gemini-3-Flash where Snippet Search stalls relative to Bash (0.623 vs. 0.625), RepoNav drives Function Acc@5 to 0.689 (+6.6 pp gain).
  • Concentrated improvements on structurally challenging files: Median-split analysis by gold file complexity reveals that RepoNav gains over Snippet Search are magnified on files with more functions (\(\Delta\)Acc@5 +6.4 pp), longer files (+8.2 pp), and higher sibling symbol density (+6.0 pp), confirming its strength in resolving within-file ambiguity.
  • Transfer to multi-hop causal reasoning in QA: On SWE-QA-Bench, the greatest dimensional improvements occur in Correctness and Completeness, with question-type breakdowns showing the largest score leaps on "Why" questions that require synthesizing distributed execution paths across files.

Highlights & Insights

  • Root-Cause Attribution of the File-to-Function Gap: Rather than attributing localization failure to insufficient recall, the authors demonstrate that 44%–58% of errors occur inside the correct file, pinpointing "premature anchoring" as the core behavioral malfunction of code LLMs.
  • Zero-Index Lightweight Interface Architecture: Unlike graph-based code systems requiring gigabytes of static analysis storage and specialized graph query engines, RepoNav dynamically parses only the top-5 retrieved candidate files using Python's standard library AST (median tool latency of 0.34 s), achieving seamless plug-and-play adoption.
  • Active Navigation over Passive Context Stuffing: By paring down structural cues into compact anchors and glimpses followed by an explicit >> Next: run list_symbols ... continuation cue, RepoNav converts passive RAG context into an interactive decision tree, increasing tool utilization by 19.65 pp while slashing token costs by 16.0%.

Limitations & Future Work

  • Language Scope Restricted to Python: The current implementation relies on Python's native ast module for AST generation and intra-file call tracking. Adapting RepoNav to compiled and multi-file paradigms (Java, C/C++, Go, Rust) requires integrating language-agnostic parsers like Tree-sitter and tailored serialization heuristics.
  • Heuristic Intra-File Call Tracking: Call context is restricted to name-only matching within the same file without interprocedural static analysis. When a bug spans multiple indirect helper wrappers across files (e.g., in the yt-dlp-11615 case), the agent can still terminate exploration at intermediate wrapper layers.
  • Lack of Downstream End-to-End Patch Evaluation: The current study focuses on localization (LocBench) and repository QA (SWE-QA-Bench); validating whether the narrowed localization gap directly translates to higher end-to-end patch generation solve rates on SWE-bench remains open for future research.
  • vs. Flat Code Retrieval (RepoCoder / CodeRAG-Bench): Prior methods feed unstructured chunks directly to LLMs, disrupting file boundaries and causing models to anchor prematurely onto irrelevant wrapper code. RepoNav aggregates chunks into file-level entries and surfaces hierarchical structural sketches.
  • vs. Repository-Wide Code Graphs (RepoGraph / CodexGraph / LocAgent): Graph-guided agents precompute whole-repository dependency networks and require complex multi-hop graph queries. RepoNav keeps the standard dense vector retrieval backend untouched and performs instantaneous, local AST parsing on top candidate files, achieving comparable or superior navigation at virtually zero infrastructure cost.

Rating

  • Novelty: ⭐⭐⭐⭐☆ [Insightful diagnosis of premature anchoring and elegant, zero-overhead post-retrieval scaffold design]
  • Experimental Thoroughness: ⭐⭐⭐⭐⭐ [Evaluated across 7 models, multiple benchmarks, tool-matched baselines, rigorous CIs, and trajectory funnels]
  • Writing Quality: ⭐⭐⭐⭐⭐ [Exemplary clarity, compelling motivation, well-structured arguments, and transparent case studies]
  • Value: ⭐⭐⭐⭐⭐ [Highly practical and actionable design pattern for commercial and open-source code agent workflows]