RepoPilot

One repo in. A ship-or-block verdict out.

RepoPilot is a release gate for public GitHub repositories. Give it a repo URL and it returns a ship-or-block verdict with the findings that block the gate — documentation gaps, reproducibility problems, deployment blockers, Web3 configuration issues — each carrying file-and-line evidence, plus the prioritised fixes that clear it.

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

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: "1.3"; "1.2", "1.1" and "1.0" still parse). The MCP server exposes 14 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.

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.

Quick start

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/azen07508-debug/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>"

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

Doc	What's in it
docs/INDEX.md	Every document, grouped by role — start here
docs/ARCHITECTURE.md	Layering, data flow, evidence rules
docs/DEPLOYMENT.md	Docker, nginx, Caddy, Railway, Render, VPS
docs/SECURITY.md	Threat model, mitigations, redaction
docs/API.md	Full HTTP API reference
docs/MCP_CLIENT_SETUP.md	Claude Code / Codex / OpenClaw / generic
docs/REPOSITORY_INTELLIGENCE_PLAN.md	Repository intelligence roadmap
docs/EXTERNAL_ACTIONS.md	The only place that lists what a human must do
docs/RELEASE_CHECKLIST.md	Pre-tag checklist
docs/OKX_LIVE_INTEGRATION.md	Which OKX CLI steps are ready, which need you
docs/OKX_REQUIREMENTS_SNAPSHOT.md	The OKX.AI requirements, captured before GA
docs/HERO_IMAGE_BRIEF.md	Marketplace hero spec
docs/AVATAR_BRIEF.md	Marketplace avatar spec
README_OKX.md	OKX.AI / Agent Payments Protocol integration
MARKETPLACE_LISTING.md	EN + CN marketplace copy

Project meta:

File	Purpose
PROJECT_STATE.md	What the project is, right now
ROADMAP.md	What's next
BACKLOG.md	Prioritised TODO list
DECISIONS.md	Architecture Decision Records
RISKS.md	Active risks + mitigations
CHANGELOG.md	Per-release notes

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.

Command	What it does
pnpm install	Install all workspace deps
pnpm dev	Run the API and the web app together
pnpm dev:worker	Run the worker on its own (the split production shape)
pnpm build	All packages and apps
pnpm typecheck	tsc --noEmit in every workspace, plus scripts/
pnpm test	All unit + integration tests
pnpm lint	tsc + custom static rules
pnpm start	Start the API server
pnpm mcp	Start the MCP server over stdio
pnpm db:migrate	Apply DB migrations (SQLite + Postgres)
pnpm db:seed	Seed one example audit job, for the admin UI
pnpm env:check	Validate env (no secret values printed)
pnpm docs:check	Recompute the facts the docs state, and fail on divergence
pnpm docs:facts	Rewrite the generated doc blocks in place
pnpm docker:check	Static Docker check (or full build if Docker is present)
pnpm compose:check	Static docker-compose review
pnpm test:baseline	Check the documented test totals against a real run
pnpm preflight:production	Pre-registration self-check: production config + assets
pnpm verify:release	End-to-end smoke (env → lint → test → build → API → MCP)
pnpm audit:diff	Re-run the four reference audits and diff against baseline
pnpm intelligence:smoke	Exercise the four repository-intelligence tools for real
pnpm probe:child-wait	Probe the shared child-process wait's failure branches
pnpm clean	Remove dist, node_modules and .turbo
make help	make aliases for the common targets above

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.