SWE-Adept: An LLM-Based Agentic Framework for Deep Codebase Analysis and Structured Issue Resolution

SWE-Adept is an LLM-based two-agent framework that enhances repository-level software engineering by combining agent-directed depth-first search for precise code localization with adaptive planning and Git-integrated version control for systematic, test-driven issue resolution, achieving state-of-the-art performance on SWE-Bench benchmarks.

The Gist

Imagine you are a master detective trying to solve a massive, chaotic crime scene inside a library that contains millions of books (the codebase). The library is so big that if you try to read every book to find the one with the clue, your brain will explode from information overload.

Most current "AI detectives" (Large Language Models) are smart, but they struggle with this specific job. They either get lost in the stacks, read too many irrelevant books, or try to fix the problem by randomly scribbling in the books until they accidentally make it worse.

SWE-Adept is a new, super-organized detective team designed to solve these massive library mysteries. Instead of one detective doing everything, it uses a two-person team with a very specific workflow and a magical filing system.

Here is how it works, broken down into simple analogies:

1. The Two-Person Team

Instead of one agent trying to do everything, SWE-Adept splits the job:

• The Locator (The Detective): This agent's only job is to find exactly where the problem is. They don't try to fix it yet; they just find the right page in the right book.
• The Fixer (The Restorer): Once the Locator points to the specific page, the Fixer takes over. Their job is to carefully edit the text, test if the story makes sense, and save the changes.

2. How the Locator Finds the Clue (The "Smart Search")

Imagine the library has a giant, messy map of how every book connects to every other book.

• Old Way: The AI would try to read the whole map at once, getting overwhelmed by irrelevant connections (like reading a cookbook when looking for a mystery novel).
• SWE-Adept's Way (Agent-Directed Depth-First Search): The Locator acts like a hiker with a compass. Instead of looking at the whole map, they pick one path that looks promising and follow it deep into the woods.
  • They only look at the "skeleton" of the books first (the table of contents) to see if it's worth reading the full text.
  • If a path leads to a dead end, they immediately turn back and try a different path.
  • Result: They find the exact page with the clue without reading 99% of the library, saving their brainpower for the important stuff.

3. How the Fixer Solves the Problem (The "Time-Traveling Editor")

Once the Fixer knows where the problem is, they start editing. But here is the tricky part: fixing complex code is like trying to fix a broken clock while it's still ticking. If you make a mistake, you might break the whole thing.

• The Old Way: The AI would just keep typing, making changes, and hoping it works. If it messed up, it would be hard to undo because it forgot what the code looked like five minutes ago.
• SWE-Adept's Way (The "Save Point" System):
  • Hypothesis Branching: Before making a big change, the Fixer creates a "parallel universe" (a new branch). They try Solution A in this universe. If it fails, they can just delete that universe and try Solution B in a fresh one, without messing up the original.
  • Checkpointing: Every time the Fixer finishes a small step (like "changed this line" or "ran this test"), they hit a Save Point.
  • The Magic: If they realize, "Oh no, this new idea is wrong," they don't have to start over from scratch. They can use their "Time Machine" to instantly jump back to the last Save Point where everything was working, and try a different path.

4. The Shared Memory (The "Case File")

Both agents share a giant, organized digital notebook (Working Memory).

• It remembers every "Save Point" (Git hash).
• It remembers every "What if" scenario (Hypothesis).
• It remembers why a certain path failed (Insights).

This ensures that even if the AI gets confused after 50 steps, it can look at its notebook and say, "Wait, I tried this before, and it failed because of X. Let's try Y instead."

Why This Matters

In the real world, software bugs are rarely simple. They are like tangled knots in a giant ball of yarn.

• Previous AI would pull on the yarn randomly, often making the knot tighter.
• SWE-Adept carefully traces the yarn to the knot (Localization), then uses a systematic approach to untie it, keeping a map of every move so it can undo mistakes instantly (Resolution).

The Result: In tests, this team solved software problems significantly better than previous methods, fixing about 4.7% more bugs and finding the right location for the fix 5.4% more accurately. It's the difference between a detective guessing where the suspect is, and a detective with a perfect map and a time machine.

Technical Summary

1. Problem Statement

While Large Language Models (LLMs) excel at self-contained programming tasks, they struggle with repository-level software engineering (SWE) issues. The authors identify two primary bottlenecks:

1. Deep Codebase Navigation & Context Management: Real-world repositories contain thousands of files with dense cross-file dependencies. Existing methods often inject excessive, irrelevant information into the agent's context window or use indiscriminate breadth-first search, leading to context overflow and poor localization accuracy.
2. Systematic Issue Resolution: Current debugging approaches often rely on "free-form" iterative editing without explicit planning or state tracking. As iterations accumulate, the working state becomes disorganized. Crucially, existing methods lack robust checkpointing mechanisms, making it difficult for agents to reliably revert failed edits or branch off to explore alternative solutions without losing progress.

2. Methodology: SWE-Adept Framework

SWE-Adept is a two-agent framework designed to decouple Issue Localization from Issue Resolution, allowing each agent to operate with specialized tools and distinct context windows.

A. Codebase Representation

• Definition-Level Indexing: Instead of indexing entire files, the framework uses tree-sitter to parse code into fine-grained units (functions and classes).
• Code-Structure Tree: A dependency-aware tree is constructed where nodes are code units and edges represent "contains" or "invokes" relationships.
• Efficient Storage: Instead of a monolithic global graph, each unit stores a lightweight adjacency list of its children, reducing traversal overhead.

B. Issue Localization Agent

This agent identifies the root cause code locations using a two-stage filtering process:

1. Agent-Directed Depth-First Search (DFS): The agent performs a selective DFS over the code-structure tree. It uses search tools to retrieve only lightweight structural information (code skeletons, previews, and metadata) rather than full file contents. This minimizes context consumption.
2. Two-Stage Filtering:
   • Stage 1 (Heuristics): The agent ranks candidates based on code previews and location metadata, discarding clearly irrelevant paths.
   • Stage 2 (Content Analysis): Only for the shortlisted candidates does the system retrieve full source code for deep analysis and final re-ranking.

C. Issue Resolution Agent

This agent implements fixes using structured problem solving and version control:

1. Hypothesis-Driven Planning: The agent formulates one or more repair hypotheses. For complex issues, it explores multiple competing hypotheses.
2. Dynamic To-Do Lists: For each hypothesis, the agent creates a granular to-do list (edit/test actions). This list is adaptive; if test feedback reveals edge cases, the agent expands the plan.
3. Tool-Memory Interface & Checkpointing:
   • The agent uses two specialized CLI-based tool families: hypothesis_plan (for planning/insights) and hypothesis_git (for version control).
   • Backend Working Memory: A shared memory stores code-state checkpoints indexed by semantic execution steps (e.g., "Commit A1: Fix Subquery").
   • Branching & Reverting: The agent can branch to explore alternative solutions. If a hypothesis fails partially, it can revert to a specific prior checkpoint (e.g., a successful intermediate step) and branch off to try a new direction, rather than restarting from scratch.
4. Final Selection: After exploring all hypotheses, the agent compares them based on status, code diffs, and insights, then merges the best solution into the original code state.

3. Key Contributions

1. SWE-Adept Framework: A novel two-agent architecture that separates localization and resolution, preventing context accumulation and enabling specialized tool usage.
2. Agentic Traversal: Introduction of a dependency-guided DFS strategy combined with two-stage filtering, which significantly improves localization accuracy while minimizing context window usage.
3. Tool-Memory Interface for Version Control: A design where agents manage code-state checkpoints via a semantic interface (hypothesis/to-do names) rather than raw Git hashes. This enables reliable, long-horizon operations like branching and reverting failed edits.

4. Experimental Results

The framework was evaluated on SWE-Bench Lite and SWE-Bench Pro using GPT-5.2 and Claude-Sonnet-4.5.

• Issue Localization:
  • SWE-Adept achieved the best results in both file-level (Acc@3) and function-level (Acc@5) localization.
  • On SWE-Bench Lite, it improved function-level accuracy by 5.4% (GPT-5.2) and 4.1% (Claude-4.5) over the strongest baseline.
  • It consumed significantly fewer tokens than graph-based baselines due to efficient context management.
• Issue Resolution (End-to-End):
  • SWE-Adept improved the end-to-end resolve rate by up to 4.7% on SWE-Bench Pro.
  • Ablation Studies: Removing the specialized localization or resolution modules caused performance drops. Crucially, replacing the hypothesis_git tool with raw Git commands resulted in lower performance on complex tasks (SWE-Bench Pro), proving that the semantic checkpointing interface is vital for long-horizon reliability.
• Behavioral Analysis: The agent frequently utilized multi-hypothesis branching and dynamic to-do expansion, behaviors that correlated with higher success rates on complex issues.

5. Significance

SWE-Adept addresses the critical gap between LLM capabilities and the demands of real-world software engineering. By introducing structured context management (via selective DFS) and systematic state tracking (via semantic checkpointing), it enables agents to handle long-horizon, multi-step debugging tasks that previously caused agents to fail due to context overflow or state confusion. The framework demonstrates that combining precise localization with robust, version-controlled resolution strategies is essential for autonomous software engineering.