RepoPilot

RepoPilot is a verifiable code agent for Python repositories. It turns an issue into an evidence-backed plan, optionally asks an OpenAI-compatible model for a unified diff, and runs the reviewed patch in an isolated workspace. Every retrieval, tool call, patch, and test result is retained as a compact audit trace.

Why this is not another chat-with-your-code demo

• AST-aware indexing: extracts classes, functions, methods, signatures, imports, and call edges instead of splitting source into arbitrary chunks.
• Hybrid retrieval: combines issue-token relevance with symbol names, file paths, and call-graph evidence.
• Bounded workflow: retrieval, planning, human review, patch validation, isolated execution, and test verification have explicit states.
• Standard tools: repository map, symbol search, file reads, and reference lookup are exposed through the official MCP Python SDK.
• Guarded execution: patch size, paths, file types, and number of changed files are validated before a copy of the repository is modified.
• Objective evaluation: a JSONL benchmark runner reports Recall@K and mean reciprocal rank for related-file retrieval.

Architecture

flowchart LR
    UI[Web console] --> API[FastAPI]
    API --> IDX[Python AST indexer]
    IDX --> STORE[Persistent JSON indexes]
    API --> RET[Hybrid retriever]
    RET --> PLAN[Bounded planner]
    PLAN --> LLM[OpenAI-compatible LLM]
    PLAN --> MCP[MCP code tools]
    LLM --> REVIEW[Human patch review]
    REVIEW --> POLICY[Patch policy]
    POLICY --> WS[Isolated workspace]
    WS --> TEST[Fixed pytest runner]
    TEST --> TRACE[Auditable task trace]

The implementation deliberately separates read-only code tools from patch execution. An MCP client can inspect code without receiving a general-purpose shell tool.

Quick start

cd D:\ai-projects\repopilot
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -m repopilot

Open http://127.0.0.1:8765.

The repository includes a deliberately broken demo at examples/buggy_calculator. Index that directory, then use this issue:

divide should raise a clear ValueError when right is zero

If no model is running, create the plan and paste this reviewed patch into the execution panel:

diff --git a/calculator.py b/calculator.py
--- a/calculator.py
+++ b/calculator.py
@@ -1,2 +1,4 @@
 def divide(left: float, right: float) -> float:
+    if right == 0:
+        raise ValueError("right must not be zero")
     return left / right

The patch is applied only to workspaces/<task-id>; the indexed source repository is not modified.

Model configuration

RepoPilot uses the OpenAI-compatible /chat/completions API. The defaults target an Ollama installation:

REPOPILOT_LLM_BASE_URL=http://127.0.0.1:11434/v1
REPOPILOT_LLM_MODEL=qwen2.5-coder:7b
REPOPILOT_LLM_API_KEY=ollama

Planning has a deterministic fallback when the model is offline. Patch generation requires a configured model because silently inventing a patch would make the demo impossible to trust.

MCP server

Start the stdio MCP server:

.\.venv\Scripts\repopilot-mcp.exe

Tools:

• repository_map
• search_symbol
• read_file
• find_references

Each tool requires the ID of a previously indexed repository.

Evaluation

After indexing the demo repository, copy its ID from the UI or GET /api/repositories and run:

.\.venv\Scripts\repopilot-eval.exe <repository-id> examples\benchmark.jsonl --k 5

Benchmark cases use one JSON object per line:

{"id":"case-1","issue":"describe the failure","expected_files":["module.py"]}

The report includes per-case retrieved files, Recall@K, reciprocal rank, mean Recall@K, and MRR. This makes retrieval changes measurable and suitable for ablation experiments.

API overview

Method	Endpoint	Purpose
GET	/api/health	Service health
POST	/api/repositories	Index a local Python repository
GET	/api/repositories	List indexed repositories
POST	/api/repositories/{id}/search	Search symbols
POST	/api/repositories/{id}/tasks	Analyze an issue and create a plan
POST	/api/tasks/{id}/generate-patch	Generate a policy-checked diff
POST	/api/tasks/{id}/execute	Execute a reviewed patch and tests
GET	/api/tasks/{id}	Read the plan, trace, diff, and test result

Interactive API documentation is available at http://127.0.0.1:8765/docs.

Safety model

The local executor is intentionally constrained:

• source repositories are copied before modification;
• patch paths must remain inside the workspace;
• at most five text/source files and 100 KB may be changed;
• test execution is fixed to python -m pytest -q;
• subprocesses have a timeout and capped captured output;
• network proxy variables and unrelated environment variables are not passed;
• task events store concise action summaries, not private chain-of-thought.

The local executor is a development safety boundary, not a hostile-code sandbox. Run untrusted repositories only inside a disposable VM or container. See SECURITY.md.

Development

.\.venv\Scripts\python.exe -m pytest --cov=repopilot --cov-report=term-missing

The Git history is organized as reviewable implementation milestones:

1. service scaffold;
2. AST indexing and retrieval;
3. bounded planning and MCP tools;
4. guarded patch execution;
5. evaluation, UI, deployment, and documentation.