RepoPilot

One repo in. A launch-ready plan out.

RepoPilot is the quality layer for agents that ship code. Point it at a public GitHub repository and get a structured launch-readiness report — evidence-backed findings, explainable scoring, and ready-to-paste launch copy — plus a fix plan per finding that an agent can act on directly.

It closes the loop: audit → fix plan → fix → re-audit → 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.

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.1"; "1.0" still parses). The MCP server exposes seven tools and marks which of them are free, so any MCP-compatible client can drive the whole loop.
• No surprise charges. Reading a fix plan or a comparison is free; only running an audit costs anything. 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 in the scoring. The pipeline reads text only. Binary files are skipped, prompt-injection patterns are reported as findings, and the LLM (when enabled) may only rewrite natural language — never a score, a priority or a piece of evidence.

Quick start

git clone <repo>
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 with Docker:

docker build -t repopilot:0.1.0-rc.2 .
docker run --rm -p 4000:4000 \
  -e NODE_ENV=production -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.2

A first audit takes 5–15 seconds for a typical mode: 'quick':

# 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>"

Documentation

Doc	What's in it
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/HERO_IMAGE_BRIEF.md	Marketplace hero 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 + llm
                 + fixplan (report -> fix plan) + diff (report -> diff)
    mcp-server/  MCP server (stdio), seven tools
    okx-adapter/ PaymentAdapter interface, mock + OKX implementations
  fixtures/      6 sample repos for tests
  docs/          ARCHITECTURE / DEPLOYMENT / SECURITY / API / MCP / EXTERNAL
  scripts/       env-check, verify-release, docker-check, lint
  .github/workflows/  ci.yml + docker.yml

See docs/ARCHITECTURE.md for the layering diagram.

Scripts

Command	What it does
pnpm install	Install all workspace deps
pnpm -r typecheck	tsc --noEmit in every package
pnpm -r test	All unit + integration tests
pnpm lint	tsc + custom static rules
pnpm build	All packages and apps
pnpm env:check	Validate env (no secret values printed)
pnpm docker:check	Static Docker check (or full build if Docker is present)
pnpm compose:check	Static docker-compose review
pnpm verify:release	End-to-end smoke (env → lint → test → build → API → MCP)
pnpm db:migrate	Apply DB migrations (SQLite + Postgres)
pnpm mcp	Start the MCP server over stdio
pnpm start	Start the API server
make help	See all targets (Makefile mirrors the above)

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. 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 full audit flow works without external services.
• mode: 'full' runs synchronously inside the HTTP request. Very large repos (> 50 MiB / 2000 files) may time out. A background worker is on the P1 backlog.
• The LLM is optional. With LLM_PROVIDER=noop the summary and launchCopy are template-generated; scores are always rule-based.

License

MIT — see LICENSE.