RepoPilot
Evidence-grounded code repair for Python repositories. Retrieve the right context, review the plan, test an exact patch, and keep the human in control.
- Type
- Local-first repair agent
- Role
- Software & AI engineering
- Source
- GitHub ↗
- Scope
- Python repositories · two human checkpoints
Tech stack
- Python
- FastAPI
- React
- TypeScript
- LangGraph
- tree-sitter
- SQLite / BM25
- Chroma
- Gemma
- Gemini
- Pydantic
- Docker
- pytest
Python
FastAPI
React
TypeScript
LangGraph
Gemini
DockerA repair agent with a human at the controls
A useful code repair needs more than a plausible diff. It needs relevant repository context, a diagnosis that points to real evidence, a bounded file scope, and tests that ran against the exact patch being reviewed.
RepoPilot turns that into an inspectable workflow. Given a Python repository and an issue, it retrieves structural evidence, proposes a repair plan, and waits for approval. Only then does it generate a patch in an isolated workspace, run pytest in Docker, and ask for a second approval before exporting it.
Find the evidence before proposing the fix
Repository discovery and tree-sitter parsing produce code chunks with source provenance. Retrieval combines two complementary signals: SQLite FTS5 / BM25 for lexical matches and EmbeddingGemma with Chroma for semantic similarity.
Reciprocal Rank Fusion combines the ranked lists without relying on their score scales. One-hop structural expansion adds related local imports, parent/child relationships, and tests. Whole chunks are then packed into a bounded ContextPack with hard budget limits.
Dense retrieval can fail or become unavailable. In that case, the system can explicitly degrade to lexical evidence rather than concealing the missing retrieval path. The repair plan still has to pass exact evidence-citation checks.
On the frozen M8-v2 retrieval suite, reducing returned depth from ten to five preserved full hybrid Hit@1, Hit@5, and MRR while improving context precision and reducing token waste.
Two approvals, bound to exact artifacts
The first checkpoint reviews diagnosis, repair steps, exact file scope, supporting evidence, and suggested tests. The approved plan and scope are hash-bound: a later model response cannot silently expand that authority.
Patch generation uses exact-match replacements, rejects stale source, and enforces the approved files. A canonical diff and patch hash identify the candidate that enters testing.
The second checkpoint presents the final diff, changed files, Docker test evidence, patch/test identity, and attempt history. Final approval binds to the exact tested patch. The output is an export; the system does not autonomously apply it, commit, push, merge, or open a pull request.
Test in isolation. Keep retries bounded.
The canonical repository is not directly edited during a repair. Tests run against a disposable snapshot in a restricted Docker runner, with bounded resources and no autonomous image pull during the repair.
A genuine test failure may trigger one critic-assisted retry. The critic must remain grounded, the approved scope still applies, and the total patch-attempt limit remains two. Provider errors and validator failures do not become permission to enter an unbounded repair loop.
SQLite workflow checkpoints support durable pause and resume. The React workbench can revisit completed stages in read-only form; workflow authority remains in the backend, rather than in the navigation state of the UI.
Trade-offs
| Choice | Why | Cost |
|---|---|---|
| Hybrid lexical + dense retrieval | Identifiers and semantic relevance contribute different evidence. | Local embeddings add availability and configuration concerns. |
| Whole-chunk context budgets | Keep provenance intact and enforce a hard context bound. | Relevant surrounding material can still consume tokens. |
| Two human checkpoints | Make scope and tested patch identity explicit. | Repairs require reviewer attention at two stages. |
| Docker test snapshots | Separate execution from the canonical repository. | Docker and a configured test image are required locally. |
| Local generation with an optional hosted provider | Keep a local path while allowing controlled provider comparisons. | CPU generation is slower; Gemini sends bounded generation context off-machine. |
| Python-only V1 | Concentrate on depth, validation, and measurable evidence. | Other languages are outside the implemented scope. |
Measured results
The controlled provider comparison held the retrieval pipeline, prompts, validators, approvals, Docker policy, and retry limit fixed. It ran the same six frozen defects across three public Python repositories; only the generation provider changed.
| Metric | Local Gemma · CPU | Gemini 3.1 Flash-Lite |
|---|---|---|
| Successful repairs | 1 / 6 | 6 / 6 |
| Grounded plans | 3 / 6 | 6 / 6 |
| Exact citation validity | 3 / 6 | 6 / 6 |
| Median planner latency | 85.169 s | 2.288 s |
| Median workflow latency | 110.912 s | 20.928 s |
The frozen M8-v2 safety suite passed 33 / 33 deterministic scenarios, covering out-of-scope edits, invented evidence, stale approvals, patch identity, retry limits, canonical-repository mutation, and export ordering. Final project verification included 350 backend tests plus the frontend test, build, and typecheck gates.
Current boundaries & next questions
V1 deliberately excludes unrestricted shell access, autonomous Git operations, multi-agent swarms, a full IDE, and multi-language support. Its goal is an inspectable repair loop with bounded authority.
The controlled retrieval and repair suites leave a clear next evaluation question: how well do the same boundaries and retrieval choices generalize to a larger, more varied issue set? The README does not claim that result yet.
Local CPU latency and embedding-provider instability are also documented limitations. The hosted Gemini path improves the measured workflow latency, but changes where generation context is processed. That remains an explicit configuration choice.
FAQ
Does RepoPilot change my repository automatically?
No. Repairs are prepared in an isolated workspace and exported only after final approval. RepoPilot does not automatically apply a patch, commit, push, merge, or create a PR.
What are the two human checkpoints?
First, approve the evidence-grounded repair plan and exact file scope. Second, review and approve the exact tested patch before export. Approvals are bound to artifact identity.
Can it work with a local model?
Yes. Ollama / local Gemma is the default generation path. An optional Gemini provider uses the same workflow and validation boundaries. Local retrieval can remain independently configured.
What happens if the tests fail?
A genuine test failure may receive one grounded critic-assisted retry. There are at most two patch attempts; there is no unbounded repair loop.
Which repositories does V1 support?
Python repositories. The implementation uses tree-sitter parsing and runs pytest in a restricted Docker sandbox. Multi-language support is outside V1.
Do six successful repairs imply production accuracy?
No. The hosted provider repaired six controlled defects in the frozen comparison. That is useful bounded evidence, not an independent benchmark or a production accuracy estimate.