PaperlayerView exact revision on arXiv

Source-linked AI summary

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

Hongzheng Chai, Jiakun Li, Hongyue Yu, Yuan Yuan

arXiv:2609.08355v1cs.SEcs.CL

TL;DR

Repository-scale code agents often retrieve the right file but miss the target function because flat snippets provide insufficient structure for comparing sibling symbols. RepoNav reorganizes retrieved evidence into a file-centered scaffold with compact structural cues and on-demand browsing. Across seven LocBench models it improves function-level localization and narrows the file-to-function gap, while controlled ablations attribute gains to evidence organization rather than merely adding file structure.

  • Problem

    Flat code-retrieval outputs can surface relevant files but provide insufficient structure for agents to distinguish target functions from similar alternatives within those files.

  • Method

    RepoNav is a lightweight post-retrieval interface that organizes retrieved snippets into file-centered scaffolds with structural cues, candidate targets, and on-demand sibling-symbol browsing.

  • Results

    Across seven models on LocBench, RepoNav improves function-level localization and reduces the gap between file discovery and function discovery; it also improves repository-level question answering.

  • Takeaways & Limitations

    Controlled ablations show that the gains come from organizing retrieved evidence into a structured, navigable form rather than simply exposing more file-structure information.

  • Takeaways & Limitations

    Evaluation currently covers Python repositories and LocBench and SWE-QA-Bench, leaving other programming languages and downstream tasks for future work.

Abstract

from arXiv · show

Solving repository-level code tasks requires LLM-based agents to use code search tools to navigate large codebases and identify a small set of relevant files and functions. However, current retrieval tools typically return flat lists of isolated code snippets: such lists can surface relevant files, but provide insufficient structure for agents to distinguish the target function from semantically similar alternatives in the same file. We introduce RepoNav, a lightweight post-retrieval interface that reorganizes retrieved snippets into a file-centered navigation scaffold. By presenting compact structural cues and candidate targets, this scaffold guides on-demand file-structure browsing, helping agents compare sibling symbols before selecting a target function. Across diverse models on LocBench, RepoNav improves function-level localization and narrows the file-to-function gap. Controlled ablations demonstrate that these gains come from structured evidence organization rather than simply exposing additional file structure, and the approach also improves performance on a repository-level question-answering benchmark.

1 Introduction

Repository-scale agents often find the relevant file but miss the target function because flat retrieval encourages premature commitment to nearby symbols. RepoNav addresses this within-file navigation bottleneck by organizing retrieved evidence into a file-centered scaffold with structural cues and actionable candidates.

  • Motivation: 44–58% of function-level misses are Correct File, Wrong Function, revealing within-file navigation as a central bottleneck.Agents can reach the correct file yet still fail to identify the correct function.
  • Motivation: Premature anchoring causes agents to commit to salient nearby symbols before inspecting sibling definitions or file-structure views.Flat snippet retrieval presents relevant chunks and distractors as isolated evidence, with limited cues about what else the file contains.
  • Approach: RepoNav is a lightweight post-retrieval interface that reorganizes retrieved evidence into a file-centered navigation scaffold.It reuses the existing dense retrieval substrate without requiring a persistent structural index or repository-wide graph.
  • Approach: The scaffold exposes compact structural cues, candidate targets, and continuation hints while supporting on-demand browsing through list_symbols.This separates file discovery from within-file verification and encourages comparison of sibling symbols before commitment.
  • Results: Across seven models on LocBench, RepoNav improves function-level localization and reduces the gap between file discovery and function discovery.A Snippet+ListSym baseline shows that browsing helps, while RepoNav further improves by making browsing more actionable through file-centered organization.

2 Background and Related Work

The paper frames function localization as a distinct challenge from file discovery: agents frequently reach the correct file but select the wrong internal symbol. This motivates navigation interfaces that organize evidence for sibling comparison rather than presenting isolated snippets or requiring heavyweight repository-wide graphs.

  • Background: Snippet-search interfaces typically present retrieved chunks as flat evidence, even though repository-level agents must navigate through interleaved reasoning and tool use.This limits structural context for distinguishing candidate functions within a file.
  • The File-to-Function Gap: Figure 2 contrasts helper-heavy flat retrieval, which misses Git.execute, with RepoNav’s scaffold and list_symbols browsing, which exposes Git.execute as a sibling candidate.The example illustrates how evidence organization can produce different function-level choices from the same general retrieval setting.
  • The File-to-Function Gap: 44–58% of all function-level misses are Correct File, Wrong Function, showing that reaching the correct file does not reliably identify the target function.The failure taxonomy also distinguishes Wrong File and Same Name, Wrong Qualifier.
  • The File-to-Function Gap: Agents often anchor on a salient nearby symbol before inspecting sibling or structurally adjacent candidates.Typical anchors include public wrappers, request handlers, or entry methods.
  • Related Work: Repository-wide graph systems provide structural representations but introduce additional graph construction and traversal infrastructure for agents.RepoNav is positioned as a lighter interface-layer alternative built over existing retrieval outputs.
  • Research Questions: The paper asks whether the file-to-function gap persists across models, whether organization matters beyond structural-information volume, and whether benefits transfer to repository-level question answering.These questions connect localization behavior to evidence presentation and broader repository tasks.

3 RepoNav: A Navigation Interface for Repository Exploration

RepoNav converts chunk-level retrieval into a file-centered, structurally expandable scaffold that supports targeted within-file inspection. Its deterministic two-stage pipeline ranks candidate files from retrieved chunks, then extracts lightweight structure only from top-ranked files for agent navigation.

  • Interface Design: RepoNav deterministically aggregates retrieved chunks into file-level candidates without changing raw retrieval results or similarity scores.It turns retrieval hits into cues for comparing plausible symbols before commitment.
  • Interface Design: The interface aggregates evidence into candidate files, exposes compact file-internal structure, and adds continuation cues for targeted inspection.These principles avoid treating retrieved evidence as a terminal answer.
  • Scaffold Components: The scaffold uses anchors, a structural glimpse of non-anchor symbols, and a capped candidate-target shortlist.These blocks provide query-relevant entry points, alternative same-file symbols, and explicit inspection targets without dumping full bodies.
  • Scaffold Components: list_symbols returns a lightweight file skeleton with imports, classes, functions, methods, line ranges, and optional signatures, but not full function bodies.It supports comparison of sibling symbols without performing semantic search or ranking target functions.
  • Implementation: The two-stage pipeline first ranks files using a hybrid score combining peak chunk evidence with support from multiple high-scoring regions.The top mf = min(m, |Cf|) chunk scores are aggregated, and α controls the balance between peak evidence and multi-region support.
  • Implementation: RepoNav parses only the top k=5 files by default, auto-expands entries for the top three, and uses Python’s ast module for lightweight structural extraction.The process is deterministic and local, avoiding repository-wide graph construction while retaining candidate files for later inspection and cross-file pivoting.

4 Experimental Evaluation

The evaluation tests RepoNav across LocBench localization, controlled scaffold ablations, and SWE-QA-Bench question answering. Results show that file-centered evidence organization improves function-level navigation beyond retrieval and file-structure access alone, while also adding interaction costs.

  • Experimental setup: The evaluation uses LocBench’s 560 Python instances and compares Bash, Snippet Search, Snippet+ListSym, and RepoNav under a common agent scaffold.The retrieval-based settings share the same chunk index, embedding model, retrieval backend, and raw similarity scores; RepoNav changes evidence organization after retrieval.
  • RQ1: File-to-function gap: RepoNav reduces the average file-to-function gap from 26.9 to 21.7 percentage points compared with Snippet Search.The gap remains after relevant files are retrieved because function-level gains do not keep pace with file-level gains.
  • RQ2: Structure and actionability: Under matched retrieval and workflow constraints, Function Acc@5 rises from 32.61% with File-Only to 46.96% with Inline Scaffold and 52.13% with Tree Scaffold.The ablation indicates that compact structural organization adds value beyond exposing more file-internal structure.
  • RQ2: Structure and actionability: Tree Scaffold uses 16% fewer tokens while increasing list_symbols use by 19.65 percentage points relative to Inline Scaffold.It also inspects fewer files and takes fewer steps, suggesting more selective and actionable exploration rather than simply broader inspection.
  • Interaction costs: RepoNav increases average trace tokens from 31.7k to 62.4k and wall-clock time from 15.5 s to 25.3 s versus Snippet Search.Its scaffold construction has 0.34 s median tool-side latency and requires no additional repository-wide index or graph.
  • RQ3: Transfer beyond localization: RepoNav achieves the highest SWE-QA-Bench total score across all four models, with average gains of +1.76 over Snippet Search and +3.07 over Bash.The gains concentrate in Correctness and Completeness and extend beyond explicit localization to repository-level question answering.

5 Conclusion

RepoNav studies how retrieval-output organization shapes repository-scale code-agent exploration. It narrows the file-to-function gap by structuring retrieved snippets into a navigable form, showing that organization matters in addition to retrieval content.

  • RepoNav narrows the persistent file-to-function gap without changing the underlying retriever.
  • Controlled ablations show that simply exposing more file-structure information is insufficient.
  • RepoNav’s gains come from organizing retrieved evidence into a structured, navigable form.

Limitations

The evaluation currently covers Python repositories and two benchmarks, leaving other programming languages and downstream tasks for future validation. The implementation’s Python-specific structure extraction limits current cross-language evidence.

  • The evaluation focuses on Python repositories and the LocBench and SWE-QA-Bench benchmarks.
  • Validation on Java, C, C++, Go, and Rust repositories remains future work because these languages may require language-specific extraction and serialization.
  • The experiments assess localization and repository-level question answering, not patch generation, long-horizon maintenance, or interactive developer workflows.

A Parameter Sensitivity Analysis

The hybrid file-ranking rule is robust across the tested α range. Ranking metrics peak near α=0.5, recall metrics plateau for α ≥0.7, and the paper fixes α=0.5 for all experiments.

  • The hybrid scoring rule balances peak evidence from the highest-scoring chunk against consistency across retrieved chunks.
  • File-level retrieval metrics remain stable across the full α range, with Acc@1 and MRR peaking near α=0.5.
  • Recall metrics reach a broad plateau for α ≥0.7, while pure averaging and pure max pooling remain competitive.
  • The experiments fix α=0.5 throughout the reported results.

B Retrieval Configuration and Baseline Performance

RepoNav uses the same dense retrieval substrate as the snippet baseline, with 80 raw chunks per query and a fixed post-aggregation file budget. Retrieval improves with depth before saturating, while downstream results reveal a substantial file-to-function gap and positive transfer to UniXcoder.

  • All retrieval-based settings share the same function-level chunking, dense index, embedding model, backend, and raw similarity scores.
  • The main experiments retrieve 80 raw chunks per query before file-level aggregation, with a post-aggregation file budget fixed at 15.
  • Increasing retrieval depth from 20 to 80 yields clear gains, while increasing it from 80 to 100 provides only marginal improvement.
  • File Acc@5 reaches 0.721 in retrieval-only evaluation, whereas Function Acc@5 reaches 0.348.
  • A fixed 100-instance UniXcoder pilot improves Function Acc@5 by 4.0 points and Function Rec@10 by 5.6 points over Snippet Search.

C Full LocBench Results

Complete LocBench results show that RepoNav improves function-level localization while preserving broad file coverage. Its behavioral profiles reveal a trade-off between broad inspection and selective, successful verification.

  • Localization results: RepoNav’s gains remain consistent across ranking cutoffs, with larger improvements in recall than accuracy at comparable k values.File-level recall is largely preserved, while module- and function-level localization improve; some models show small file-level drops.
  • Localization results: Both confidence intervals exclude zero, providing statistical evidence for improvements on the two primary function-level localization metrics.
  • Behavioral diagnostics: The evidence funnel separates coverage, inspection, and resolution as conditional trajectory diagnostics rather than a multiplicative endpoint estimate.Coverage may arise from retrieval or later shell exploration.
  • Behavioral diagnostics: Inline Scaffold reaches 97.30% inspection, whereas Tree Scaffold reaches 97.50% resolution after inspection.Inline Scaffold encourages broad reading, while Tree Scaffold promotes more selective inspection and tool-based verification.
  • Behavioral diagnostics: Inline Scaffold maximizes gold-file inspection, while Tree Scaffold improves correct action after inspection through compact cues and continuation prompts.

D.2 Block-level Scaffold Ablation

Controlled ablations show that RepoNav’s scaffold blocks each contribute to function-level localization, with candidate targets having the largest measured effect. Gains also grow with within-file complexity and extend to question answering.

  • Block-level ablation: Removing any scaffold block reduces function-level localization, with [CANDIDATE_TARGETS] producing the largest degradation.Removing [CANDIDATE_TARGETS] lowers Function Acc@5 by 7.6 points and Function Rec@10 by 7.5 points.
  • Block-level ablation: Removing [ANCHORS] lowers Function Acc@5 by 3.2 points and Function Rec@10 by 3.9 points.
  • Block-level ablation: Removing [GLIMPSE] lowers Function Acc@5 by 2.5 points and Function Rec@10 by 2.9 points.
  • Complexity analysis: RepoNav’s gains are consistently larger on files with greater within-file complexity than on simpler files.The analysis stratifies files by function count, file length, and sibling-symbol count.
  • Question answering: Across all four models, RepoNav achieves the highest score on every SWE-QA-Bench dimension.The strongest gains appear in Correctness and Completeness, while Relevance, Clarity, and Reasoning also improve.

E.2 Question-Type Breakdown

RepoNav improves SWE-QA-Bench scores across all question types, with the largest and most consistent gains on Why questions. Interaction savings occur for most models but vary by model-specific exploration behavior.

  • Question-type performance: Score improvements occur across How, What, Where, and Why questions, with the largest gains on Why questions.
  • Question-type performance: Why questions benefit most consistently, aligning with their need to synthesize evidence across files and trace causal chains.
  • Interaction efficiency: Interaction savings are substantial for three of four models, while GPT-OSS-120B shows smaller and mixed savings.The result suggests that efficiency gains depend on model-specific exploration behavior.

F Additional Case Studies

Additional cases show that RepoNav reduces wrong-file fixation but residual errors remain concentrated in fine-grained within-file discrimination. Its compact serialized scaffold supports explicit continuation into symbol-level browsing.

  • Residual failures: A remaining failure occurs when agents stop at salient wrapper methods instead of inspecting lower-level helper functions several call-hops away.The [GLIMPSE] block lists the helpers, but the agent does not inspect them further.
  • Scaffold design: RepoNav uses fixed serialization budgets and deterministic ordering rules to keep the scaffold compact and reproducible.The scaffold caps anchors at two, glimpse symbols at three per file, and candidate targets at four entries.
  • Scaffold design: Call context records same-file caller and callee names without bodies, arguments, or interprocedural analysis.RepoNav parses the top five candidate files and auto-expands full scaffolds for the top three.
  • Scaffold design: The serialized output organizes evidence as an indentation-based tree with anchors, a structural glimpse, candidate targets, and an explicit list_symbols continuation cue.The format requires no specialized query language or structured API from the agent.
Loading 2609.08355v1…