RepoPilot

Web3 and hackathon repos routinely ship at 3 AM with broken build scripts, uncommitted configs, and missing license headers. Human reviewers waste hours on trivial triage. RepoPilot is a cynical, headless release gate server. It parses public GitHub repositories via zero-execution static analysis (pure AST and deterministic regexes) and emits an unforgiving ship-or-block verdict. Every finding is backed by absolute line-level evidence (path:line:reason) and an actionable fix plan directly callable by Codex, Claude Code, or OpenCode via MCP.

Web3 与黑客松竞赛项目在午夜提交代码时，充斥着残缺的构建脚本、未提交的本地环境变量与毫无防御的配置漏洞。代码评审员不该在基础排错上浪费生命。RepoPilot 是一座冷酷无情的无头静态审计网关：输入 GitHub 仓库 URL，系统在 5–15 秒内完成 100% 静态 AST 与正则语法树审计（绝不执行不可信的任意代码），输出非黑即白的准入裁决。每一项拦截漏洞均携带绝对行号证据（path:line:reason），并生成可直接通过 MCP 协议派发给自主编程智能体的确定性修复计划。

Ask for mode: 'full' and the same report also carries the deployment plan and the launch copy you ship with. The measurement is identical either way, and so is the price.

It closes the loop: gate → fix plan → fix → re-gate → compare. The comparison attributes score movement rule by rule and splits findings into resolved, new and still-open. Built for Web3 developers, hackathon contestants, and other AI agents.

📚 Looking for a specific doc? Start at docs/INDEX.md — it lists every document with one-line descriptions and points you at the right one.

RepoPilot runs static analysis only. It does not execute the audited repository's code. It does not perform a formal security audit. It does not custody funds or read private keys.

Contents

• Why RepoPilot

• What a verdict contains

• Quick start

• Use it from an MCP client

• Documentation

• Project layout

• Scripts

• Tech stack

• Known limitations

• License

Related MCP server: repo-doctor

Why RepoPilot

• Evidence first. Every finding has at least one path:line:reason pointer, and so does every fix step. The score is rule-based and reproducible.

• A plan, not just a report. Each finding gets a fix plan with ordered steps, tests to add, acceptance criteria, estimated effort and risks — plus an agentInstructions block you can hand straight to Codex, Claude Code or OpenCode.

• Before/after, attributed. Re-audit after fixing and RepoPilot says what moved: the score delta per dimension, the exact scoring rules that changed, and which findings were resolved, appeared or persist.

• Built for AI agents. The report is a single JSON document with a stable schema (reportVersion: "<!-- docs-facts:report-version -->1.5<!-- docs-facts:end -->";

  still parse). The MCP server exposes

  tools and marks which of them are free, so any MCP-compatible client can drive the whole loop.

• No surprise charges, and no tiers. A read-only triage probe is free (POST /api/v1/free-check, or free_check over MCP), and so is reading a fix plan or a comparison — only running a gate costs anything. A gate costs one price whatever mode you ask for: mode selects how much of the report you receive, never what is measured or what it costs. The number is in MARKETPLACE_LISTING.md, which pnpm docs:check keeps in step with the server. A MockPaymentAdapter is the default, the real OkxPaymentAdapter is opt-in. See docs/EXTERNAL_ACTIONS.md for the Beta gate.

• No execution, and no LLM anywhere. The pipeline reads text only. Binary files are skipped and prompt-injection patterns are reported as findings. Scores, priorities, evidence, the summary and the launch copy are all produced by deterministic rules and templates — there is no model in the path and no LLM configuration to set. The provider interface that used to exist was removed in R-38, because nothing consumed it.

🔄 System Architecture (系统架构与执行流水线)

                   ┌──────────────────────────────────────────────┐
                   │  Clients                                     │
                   │  - Web UI (apps/web)                         │
                   │  - MCP Clients (Claude Code, Codex, Cursor)  │
                   │  - Autonomous AI Agents (HTTP REST / STDIO)  │
                   └──────────────────────┬───────────────────────┘
                                          │
                                          ▼
                   ┌──────────────────────────────────────────────┐
                   │  apps/api (Fastify Gateway)                  │
                   │  ┌────────────┐  ┌─────────────┐             │
                   │  │  /health   │  │  /audits    │             │
                   │  └────────────┘  └─────────────┘             │
                   │  ┌──────────────────────────────────────┐    │
                   │  │  PaymentAdapter                      │    │
                   │  │   ├─ MockPaymentAdapter (default)   │    │
                   │  │   └─ OkxPaymentAdapter (x402 v2)    │    │
                   │  └──────────────────────────────────────┘    │
                   │  ┌────────────┐  ┌─────────────────────┐     │
                   │  │  Drizzle   │  │  AuditPipeline      │     │
                   │  │  (SQLite/  │  │   └─ packages/core  │     │
                   │  │   Postgres)│  │                     │     │
                   │  └────────────┘  └─────────────────────┘     │
                   └──────────────────────┬───────────────────────┘
                                          │
                                          ▼
                   ┌──────────────────────────────────────────────┐
                   │  packages/core (Zero Arbitrary Execution)    │
                   │  ┌──────────────────────────────────────┐    │
                   │  │  GitFetcher (allowlist, no exec)     │    │
                   │  └──────────────────────────────────────┘    │
                   │  ┌──────────────────────────────────────┐    │
                   │  │  Analyzers (deterministic AST/regex) │    │
                   │  │   - stack           - documentation  │    │
                   │  │   - reproducibility - secrets        │    │
                   │  │   - web3            - hackathon      │    │
                   │  │   - hygiene         - ai-patterns    │    │
                   │  │   - prompt-injection                 │    │
                   │  └──────────────────────────────────────┘    │
                   │  ┌──────────────────────────────────────┐    │
                   │  │  RuleScorer -> Actionable Fix Plan   │    │
                   │  │   - path:line:reason pointers        │    │
                   │  └──────────────────────────────────────┘    │
                   └──────────────────────────────────────────────┘

What a verdict contains

A gate returns one JSON document. The parts that decide the verdict:

• scores — overall from 0 to 100, plus one score per dimension (documentation, reproducibility, securityHygiene, deploymentReadiness). Each dimension carries a breakdown naming the rules that fired and the delta each one applied, so a score movement can be attributed rule by rule rather than guessed at.

• Findings, split by what they mean rather than by which analyzer found them: blockers, documentationGaps, securityFindings, qualityFindings (code hygiene — deliberately outside the score, because a leftover TODO does not change launch readiness) and fixtureFindings (real findings under test and fixture paths, kept separate because their blast radius is smaller). Every one carries path:line:reason.

• The forward-looking sections — deploymentPlan, recommendedTasks and launchChecklist, plus launchCopy on mode: 'full'.

• omittedSections — how you tell "this report has no deployment plan" from "this tier does not include one". Absent and empty are different claims; read this field, never auditMode.

The verdict itself is the quality contract: pass, pass_with_warnings or blocked, with the fingerprint of each finding that blocks a release. Over MCP that is quality_status; over HTTP it is GET /api/v1/audits/:jobId/quality. Field-by-field reference: docs/API.md.

⚡ 30-Second Quick Start (30 秒极速开箱)

Requirements: Node.js 22 LTS and pnpm 11.x. No database server — SQLite is the default, and Postgres is opt-in.

git clone https://github.com/AZEN-jc/repopilot.git
cd repopilot
pnpm install
cp .env.example .env
pnpm db:migrate
pnpm build
pnpm --filter @repopilot/api start
# API on http://localhost:4000
# Web on http://localhost:5173 (run pnpm --filter @repopilot/web dev in another shell)

Or run both apps at once with pnpm dev.

Or with Docker — the API image. docs/DEPLOYMENT.md has the production path (PAYMENT_MODE=okx, Postgres, pg-boss):

docker build -t repopilot:0.1.0-rc.3 .
mkdir -p data                                   # the container runs as uid 1000

# 1. Apply the schema. A fresh database has no tables, and `/health` probes one.
docker run --rm \
  -e NODE_ENV=development -e PAYMENT_MODE=mock \
  -e DATABASE_URL=file:/data/repopilot.db \
  -v $(pwd)/data:/data \
  repopilot:0.1.0-rc.3 \
  node apps/api/dist/db/migrate.js

# 2. Serve.
docker run --rm -p 127.0.0.1:4000:4000 \
  -e NODE_ENV=development -e PAYMENT_MODE=mock \
  -e DATABASE_URL=file:/data/repopilot.db \
  -e ALLOWED_REPO_HOSTS=github.com,raw.githubusercontent.com \
  -v $(pwd)/data:/data \
  repopilot:0.1.0-rc.3

NODE_ENV=development is deliberate, not a simplification: the API refuses to start with NODE_ENV=production and PAYMENT_MODE=mock (apps/api/src/config.ts, validateProductionConfig). The image itself sets NODE_ENV=production, so a local smoke run has to override it.

A gate takes 5–15 seconds for a typical public repository. The examples below pass mode: 'quick' — the verdict alone — to keep the responses small. The default is full, the shape the paid service is sold as:

# 1. Submit a repo for audit (returns 402 with a payment challenge)
curl -X POST http://localhost:4000/api/v1/audits \
  -H 'content-type: application/json' \
  -d '{"repoUrl":"https://github.com/octocat/Hello-World",
       "mode":"quick","target":"open_source","outputLanguage":"en"}'

# 2. Replay with the mock X-PAYMENT header (use the paymentId from step 1)
curl -X POST http://localhost:4000/api/v1/audits \
  -H 'content-type: application/json' \
  -H "x-payment: mock:mock_xxx" \
  -d '{"repoUrl":"https://github.com/octocat/Hello-World",
       "mode":"quick","target":"open_source","outputLanguage":"en"}'

Then close the loop. These three are free and never re-scan the repo:

# 3. Get an actionable plan for every finding
curl http://localhost:4000/api/v1/audits/<jobId>/fix-plan

# 4. Fix something, then audit the same repository again
curl -X POST http://localhost:4000/api/v1/repositories/octocat/Hello-World/reaudit

# 5. See what actually changed, attributed rule by rule
curl "http://localhost:4000/api/v1/audits/<newJobId>/diff?base=<jobId>"

Simulated Terminal Audit Output

$ repopilot audit https://github.com/example/web3-dapp --mode quick

 RepoPilot Release Gate v0.1.0-rc.3
 Fetching repository tree (git commit: a9f81bc) ... OK (42 files, 3.2s)
 Running deterministic analyzers [Doc, Repro, Sec, Deploy] ... OK

────────────────────────────────────────────────────────────────────────
 VERDICT : BLOCKED (Overall Score: 58/100)
────────────────────────────────────────────────────────────────────────
 [BLOCKERS]
   ✖ SEC-002: Hardcoded private key dummy in deploy script
     Evidence -> scripts/deploy.ts:7:const PRIVATE_KEY = "0xac0874..."
   ✖ DEP-001: Missing lockfile or non-deterministic package specifier
     Evidence -> package.json:18:"ethers": "^6.0.0" (no pnpm-lock.yaml)

 [ACTIONABLE FIX PLAN GENERATED]
   1. scripts/deploy.ts: Read signer private key strictly from process.env.DEPLOYER_KEY
   2. Root: Commit pnpm-lock.yaml or npm-shrinkwrap.json to freeze dependencies
   -> Hand off structured plan to AI Agent: `repopilot fix-plan --agent-prompt`
────────────────────────────────────────────────────────────────────────

Use it from an MCP client

The MCP server runs the analysis in-process — it does not call the HTTP API, and the API does not need to be running. Point a client at the built CLI, and give it a GitHub token: anonymous access is capped at 60 requests/hour, which is not enough for a gate.

{
  "mcpServers": {
    "repopilot": {
      "command": "node",
      "args": [
        "/absolute/path/to/repopilot/packages/mcp-server/dist/cli.js"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "PAYMENT_MODE": "mock"
      }
    }
  }
}

PAYMENT_MODE=mock auto-settles so an agent gets a result without a settlement step; okx returns a challenge the caller settles. Per-client recipes (Claude Code, Codex, OpenClaw, generic stdio), the full environment list and the tool reference are in docs/MCP_CLIENT_SETUP.md.

Documentation

Project meta:

Project layout

repopilot/
  apps/
    api/      Fastify HTTP API
    web/      React + Vite admin UI
  packages/
    core/        analyzers + scoring + report + security + schemas
                 + fixplan (report -> fix plan) + diff (report -> diff)
    mcp-server/  MCP server (stdio)
    okx-adapter/ PaymentAdapter interface, mock + OKX implementations
  fixtures/      <!-- docs-facts:fixture-count -->6<!-- docs-facts:end --> sample repos for tests
  docs/          one file per topic; see docs/INDEX.md for the list
  scripts/       one check script per gate; see the Scripts table below
  .github/workflows/  ci.yml + docker.yml

See docs/ARCHITECTURE.md for the layering diagram.

Scripts

The gates are the point of this repository, so the list is worth reading rather than skimming. package.json is the source of truth; the Makefile covers the common ones for people who prefer make.

pnpm docs:check is the one that most often fails a change: it recomputes the counts the documentation states — workspaces, fixtures, MCP tools, compose services, prices, citations — and exits non-zero when a document and the code disagree. When it fails, run pnpm docs:facts and read the diff rather than editing the number by hand.

Tech stack

• Node.js 22 LTS, TypeScript 5.7 strict + NodeNext ESM

• pnpm 11.x workspaces

• Fastify 5, Zod 3.24, Octokit, Drizzle (SQLite + Postgres)

• Vitest, Pino 10, React 18 + Vite 6

• @modelcontextprotocol/sdk@1.22 (official MCP TS SDK, stdio)

• viem 2.x for EIP-3009 / EIP-712 in the OKX adapter

Known limitations

• OKX.AI Marketplace went GA on 2026-06-30. The OkxPaymentAdapter is fully wired (x402 v2 + EIP-3009 + EIP-712) and accepts PAYMENT_MODE=okx with a valid OKX_PAYMENT_ADDRESS and OKX_PAYMENT_RESOURCE_URL — the second is this deployment's own public https URL, and the 402 challenge shows it to the buyer as the resource being paid for. Both are required in production; pnpm preflight:production reports what is still missing. To publish the marketplace listing, run onchainos agent register --role asp (see docs/EXTERNAL_ACTIONS.md item 2). The product still ships with PAYMENT_MODE=mock as the default so the whole gate flow works without external services.

• mode selects the report, not the measurement. Both modes run every analyzer over the same archive and read the same commit history; full only adds two report sections — the deployment plan and the launch copy — and costs the same. The declaration and the consistency test that pins it are in packages/core/src/report/tiers.ts. What does bound a gate is the repository, not the mode: a very large one (> 50 MiB / 2000 files) can exceed the audit timeout. The gate is queued, not synchronous — POST /api/v1/audits answers 202 and a worker process runs the pipeline. In the default combined shape that worker lives in the API process; the split production shape runs it as its own service (see docs/DEPLOYMENT.md).

• The report is deterministic, and there is no LLM hook. Every score is rule-based, and summary / launchCopy are generated from templates in packages/core/src/report/templates.ts. @repopilot/core used to ship an OpenAICompatibleProvider and read LLM_PROVIDER; both were removed, because no code path in the API or the MCP server ever consumed them — setting the variable changed nothing about a report, while pnpm env:check refused to pass without credentials for it. There is no LLM configuration left to set. See RISKS.md R-38.

License

MIT — see LICENSE.