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 covering three categories of checks — structure, error handling, and security. The repository analysis capability is also exposed as an MCP server, so clients like Claude Code and Cursor can call it directly.

How It Differs from Similar Tools

Every conclusion in the report must be traceable to a file path, and this is enforced by program validation rather than prompt constraints — referenced paths must actually exist, and line numbers must fall within the file's actual line count. Conclusions that fail validation are dropped and counted in the report's missing-coverage section. So you won't see sentences such as "this project uses a layered architecture with clean code structure" that would hold true for any repository.

Related MCP server: github-repo-intel-mcp

Architecture

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

Parts that are deterministic are handled by deterministic means: the file tree, import dependency graph, module clustering, entry points, and tech stack detection are all produced by static parsing, not an LLM. Only the parts that require judgment get an Agent — the Planner decides which modules to dig into, module sub-agents read code with tools, and the Reviewer's candidate points, after being located by the AST, are passed to a model to decide what to keep.

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

Quick Start

Using Docker (Recommended)

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

Open http://localhost.

Both ports bind to 127.0.0.1 only — the backend has no authentication layer (an intentional choice for single-user local running), and it can clone any repository and consume LLM quota. If you need to access it from another machine, add your own; do not just change it to 0.0.0.0.

The index cache lives in the codepilot-data named volume and is retained through container restarts; a second analysis of the same repository will hit the cache and skip vectorization.

Local Development

Then

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

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

The frontend is at http://localhost:51753, and Vite's proxy forwards /api to 8000.

Configuration

Copy .env.example to .env. Only one variable is required:

| Variable | Description | | ------- | ---------------- | | DEEPSEEK_API_KEY` | The LLM API key. The variable name follows DeepSeek, but any endpoint compatible with the OpenAI protocol works |

Commonly-tuned settings:

| Variable | Default | Description | | ------- | -------------- | ------- | | DEEPSEEK_BASE_URL|https://api.deepseek.com` | An OpenAI-compatible endpoint | | LLM_MODEL_FLASH | — | Fan-out tier (high-frequency, low-judgment): module analysis | | LFLM_MODEL_PRO | — | Summary tier (low-frequency, high-judgment): Planner, review judgments, report aggregation | | EMBEDDING_PROVIDER | local | In local mode the model is downloaded on first run; api mode uses a remote endpoint | | LLM_MAX_CONCURRENCY | 2 | Number of LLM requests inflight. Through a relay gateway, high concurrency triggers upstream timeouts | | MAX_PARSEABLE_FILES | 1500 | Admission threshold. TS projects naturally have more files than Python projects the same size, so you may need to raise it |

.env is never committed to the repository, nor built into the image — .dockerignore excludes it, and compose injects it at runtime via env_file.

docker compose config prints the actual keys in cleartext. Compose expands the env_file values while parsing the config, so the command output contains real keys — when debugging configuration, do not paste that output into issues, logs, or chat messages. To inspect the structure without exposing values, filter out environment sections before reading.

MCP server

Not in the container. It communicates over stdio, and the client launches the subprocess itself. See backend/mcp_server/README.md for configuration and the tool list.

Minimal configuration (Claude Code's .mcp.json):

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

The tools read local data for repositories already analyzed, so submit a analysis first through the UI or API.

Development

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

Known Boundaries

These are intentional trade-off, not a backlog:

Symbol-level parsing supports only Python and TypeScript. Files in other languages count toward the file tree and size stats, but are not added to the symbol table, dependency graph, or chunks — the report's missing section lists them.

find_references is a text match constrained by the dependency graph, not a reference resolution. The parse layer does not extract call sites; it first uncts the definition file from the symbol table and then does a text search within the files that import that file — far more accurate than problems for whole-repository grep, but local variables with the same name, and comments will also hit. The tool result includes a note explaining this.

"Dead code" is not a finding type. The file-level registry criteria (zero in-degree and not an entry point) produces false positives on the baseline repository — tests, config, and toolchain entries all have callers outside the repository. Doing it properly would require symbol-level reference analysis. The structural checks give a count, but are not listed one by one.

Q&A is a single turn — it valuable — it does not preserve context and does no query rewriting.

There is no authentication layer. Both the backend API and the MCP server assume a single-user local deployment.

Analysis task state is in process memory. Any unfinished task is lost when the service restarts; completed index cache remains, and resubmitting, the same repo is near-instant. This also why the backend is fixed to a single worker.

License

Not a license is specified.