CodePilot-Agent

Input a GitHub repository URL, and it produces three things: an architecture analysis report traceable to specific files, single-turn code Q&A for that repository, and a code review with three categories of checks: structure / error handling / security. The repository analysis capability is also exposed externally as an MCP server, callable directly by clients such as Claude Code and Cursor.

How it differs from similar tools

Every conclusion in the report must be traceable to a file path, and this is enforced by program logic rather than by prompt constraints — the referenced path must actually exist and the line number must be within the file's actual line count; conclusions that fail the check are discarded and counted in the report's omission notes. That is why you will never see an empty sentence like "this project adopts a layered architecture with a clear structure" that could apply to any repository.

Related MCP server: github-repo-intel-mcp

Architecture

仓库地址 → clone 与语言识别 → 静态解析层（tree-sitter）
                                    ↓
                        结构骨架：符号表 · 依赖图 · 模块聚类 · 入口点
                                    ↓
              ┌─────────────────────┼─────────────────────┐
              ↓                     ↓                     ↓
     Planner 定深挖范围        Reviewer 三类检查      切块与向量索引
              ↓                     ↓                     ↓
   模块子 Agent 并行分析         评审发现            单轮代码问答
              ↓
      汇总 + 引用校验 → 架构报告

The parts that are known use known methods: the file tree, the import dependency graph, module clustering, entry points, and tech stack identification are all produced by static parsing, not by an LLM. The Agent is used only where interpretation is required — the Planner decides which modules to dig into, module sub-Agents use tools to read the code, and the Reviewer's candidate points are emitted by AST once located, leaving the model the final word.

RAG serves only the Q&A path. Architecture questions (how many layers, who depends on whom, where the entry points are) are graph problems, which embedding similarity cannot answer.

Quick Start

Using Docker (recommended)

cp .env.example .env
# 编辑 .env，至少填 DEEPSEEK_API_KEY
docker compose up --build

Open http://localhost from any window.

Both ports are bound only to 127.0.0.1 — the backend has no auth layer (a deliberate choice for single-user local runs), and it can clone any repository and spend LLM quota. To access it from another machine, you have to add your own auth entry, and must not just change the binding to 0.0.0.0.

The index cache lives in the named volume codepilot-data, and the storage remains after container restarts. Running the same repository through a second time will hit the cache and skip vectorization.

Local Development

# 后端
pip install -e ".[dev]"
python -m uvicorn backend.main:get_app --factory --port 8000

# 前端（另开一个终端）
cd frontend && npm install && npm run dev

The frontend is served at http://localhost:5173, and Vite's proxy will forward /api to port 8000.

Configuration

Copy .env.example over to .env. Only one of the items is required:

The ones you will most likely want to tweak:

.env is the only hidden one: it is neither versioned nor baked into the image; .dockerignore excludes it, and the compose env_file injects it in a runtime config step.

⚠️ docker compose config will nevertheless print the secrets as clear text. While compose resolves settings it expands the values of env_file into the output, so that command's output will contain the real keys. This is precisely why you should not post compose config output into an issue, logs, or chat during troubleshooting – it would leak your keys. If you want the structure and not the secrets-in-addition, to filter out the environment variable's block, you can already discard the container in the same output, with the compositions slow line.

"

MCP server

**Not inside the "container": it uses the stdio transport and is spawned by the client itself. The configuration manual and the tool list are in [backend/mcp_server/README.md].

Minimum configuration (within Claude Code .mcp.json):

{
  "mcpServers": {
    "codepilot": {
      "command": "python",
      "args": ["-m", "backend.mcp_server.server"],
      "cwd": "/绝对路径/CodePilot-Agent"
    }
  }
}

The tool reads the local data of already-analyzed repositories, so you first submit one analysis via either the UI or the API.

Development

python -m pytest              # 后端测试
python -m mypy backend        # 类型检查
cd frontend && npm test       # 前端测试
cd frontend && npm run build  # 前端构建（含类型检查）

Known limitations

These are deliberate and conscious trade-offs, not a leftover todo:

Symbol-level parsing only covers Python and TypeScript. Other languages' files are counted into size statistics and the file tree, but they never into symbol tables, and they are not edged into the graph of dependencies, and never chunk. They are still reflected in the missing-lying part of the report on demand.

find_references is a text-matching pass in the boundaries of the dependency graph, not a symbol resolution setup. The arche controller does not make the extraction of calls, so it finds the defining file via the index table first and then does the text pattern on the files that import it — much tighter than grepping the whole tree, but the same-named local variables are thus also strings and errors. The tool returns an explanatory line appended to its result.

"Dead code" is not emitted as a finding. The file-based heuristics (zero out-degree and entry-point-only) produce a false-positive rate closer to 100% on our benchmark repos — a typical test, a config, a LED, an entry packet, are external to the repo. Making that honestly requires a symbolic analysis. What the review structure checks produce is a warning count, not per-line items.

The Q&A is single-turn. No context preservation would stay, and nothing structure of the query is rewritten. It is trivial, non-sequential by definition.

No authentication layer. Both the backend API and the MCP are designed for single-user local operation.

Analysis task state total is in the process memory. When the service is restarted, an unfinished task is lost; the completed indexing cache is still in place, so a resubmission of the same repository hits the cache within a second. This is also why the backend is deliberately pinned to a single worker.

License

Opened exactly at "un set".