PatchPilots

A team of AI agents that reviews and improves your code automatically.

     ○      ○      ○      ○      ○      ○      ○      ○
    /|\    /|\    /|\    /|\    /|\    /|\    /|\    /|\
    / \    / \    / \    / \    / \    / \    / \    / \
     🧠      🔍      ✨      🧪      📝      🔒      🎨      🎯
  Planner Reviewer  Coder   Tester   Docs  Security Designer Orchestrator

    ____        __       __    ____  _ __      __
   / __ \____ _/ /______/ /_  / __ \(_) /___  / /______
  / /_/ / __ `/ __/ ___/ __ \/ /_/ / / / __ \/ __/ ___/
 / ____/ /_/ / /_/ /__/ / / / ____/ / / /_/ / /_(__  )
/_/    \__,_/\__/\___/_/ /_/_/   /_/_/\____/\__/____/

     ○      ○      ○      ○      ○      ○      ○      ○
    /|\    /|\    /|\    /|\    /|\    /|\    /|\    /|\
    / \    / \    / \    / \    / \    / \    / \    / \

    Your code crew is ready. One dev. Eight agents. Zero bugs.

One dev. Eight AI agents. Zero excuses.

Built for solo developers and hobby projects — when you don't have a team to review your PRs, PatchPilots is your crew.

See it in action

PatchPilots Reviewer and Coder in action on CLI.

PatchPilots auto-reviews PRs and posts findings as comments.

Use it 4 ways

`npx` — no install, one-off

npx patchpilots audit ./src

Global install — your machine, any project

npm install -g patchpilots
patchpilots audit ./src

GitHub Action — automatic on every PR

- uses: alavesa/patchpilots@main
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

MCP Server — security scanning inside your IDE

{
  "mcpServers": {
    "patchpilots": {
      "command": "npx",
      "args": ["-y", "patchpilots-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Works with Claude Code, Cursor, VS Code, and any MCP-compatible IDE. Exposes the security agent and a supply chain dependency scanner as conversational tools — ask your AI assistant to scan your code and it calls PatchPilots automatically. See patchpilots-mcp for setup details.

The CLI and Action give you all 8 agents. The MCP server brings security scanning into your editor conversation. Same analysis, different delivery.

The Killer Feature

patchpilots audit — run all 8 agents in one command. No other tool does this.

npx patchpilots audit ./src --write

⚡ TypeScript → 🧠 Planner → 🔍 Reviewer → 🔒 Security → 🎨 Designer → ✨ Coder → 🧪 Tester → 📝 Docs

One command gives you: TypeScript pre-check (free), implementation plan, code review, security audit, design & accessibility audit, auto-fixes, unit tests, and documentation. Skip what you don't need:

npx patchpilots audit ./src --skip plan,docs --write

The Crew

Agent	Command	What it does
🎯 Orchestrator	`patchpilots audit`	Runs the full pipeline in one command
🧠 Planner	`patchpilots plan`	Analyzes codebase and breaks down work into tasks
🔍 Reviewer	`patchpilots review`	Finds bugs, security issues, and code smells
✨ Coder	`patchpilots improve`	Fixes code based on review findings (diff-based patches)
🧪 Tester	`patchpilots test`	Generates unit tests for your source files
📝 Docs	`patchpilots docs`	Generates JSDoc/TSDoc documentation
🔒 Security	`patchpilots security`	OWASP Top 10 audit, secrets detection, auth analysis
🎨 Designer	`patchpilots designer`	WCAG 2.1 AA accessibility, design tokens, CSS consistency

Quick start

# Set your API key (get one at https://console.anthropic.com/settings/keys)
# Option 1: Global config (set once, works everywhere)
echo '{"apiKey": "sk-ant-..."}' > ~/.patchpilots.json

# Option 2: Environment variable
export ANTHROPIC_API_KEY=your-key-here

# Run the full audit
npx patchpilots audit ./src --write

# Or run individual agents:
npx patchpilots review ./src
npx patchpilots security ./src
npx patchpilots designer ./src
npx patchpilots improve ./src --write
npx patchpilots test ./src --write
npx patchpilots docs ./src --write
npx patchpilots plan ./src --task "add authentication"

CLI commands

`patchpilots audit <path>`

Runs all agents in sequence: TypeScript pre-check → plan → review → security → designer → improve → test → docs.

Before any AI agent runs, PatchPilots executes tsc --noEmit to catch TypeScript errors instantly — unused imports, type mismatches, missing arguments. These findings are free (no API tokens) and get merged into the review results.

Option	Description
`--write`	Apply patches and write tests/docs to disk
`--backup`	Create `.bak` files before patching
`--skip <agents>`	Skip agents (comma-separated: `plan,test,docs`)
`--severity <level>`	Minimum severity for review findings
`--framework <name>`	Test framework (default: `vitest`)
`--json`	Output raw JSON
`--verbose`	Show per-agent token usage
`--routing`	Smart model routing (Haiku/Sonnet/Opus by file complexity)
`-m, --model <model>`	Claude model to use

`patchpilots review <path>`

Runs a TypeScript pre-check, then analyzes your code with AI. Findings grouped by file, color-coded by severity.

Option	Description
`-m, --model <model>`	Claude model to use
`-c, --config <path>`	Path to config file
`--severity <level>`	Minimum severity: `critical`, `warning`, `info`
`--json`	Output raw JSON
`--verbose`	Show token usage and thinking progress

`patchpilots improve <path>`

Reviews code and generates search-and-replace patches to fix issues.

All review options plus:

Option	Description
`--write`	Apply patches to disk (default: dry-run)
`--backup`	Create `.bak` files before patching

`patchpilots test <path>`

Generates unit tests for source files.

Option	Description
`--write`	Write test files to disk
`--framework <name>`	Test framework to use (default: `vitest`)

`patchpilots plan <path>`

Analyzes codebase and creates a structured implementation plan.

Option	Description
`-t, --task <description>`	Specific task to plan for

`patchpilots docs <path>`

Generates documentation for source files.

Option	Description
`--write`	Write documented files to disk
`--backup`	Create `.bak` files before overwriting

`patchpilots security <path>`

Runs a security audit focused on OWASP Top 10, secrets detection, and auth patterns.

Option	Description
`--severity <level>`	Minimum severity: `critical`, `high`, `medium`, `low`
`--json`	Output raw JSON
`--verbose`	Show token usage and timing

`patchpilots designer <path>`

Audits accessibility (WCAG 2.1 AA), design tokens, CSS consistency, and component markup.

Option	Description
`--severity <level>`	Minimum severity: `critical`, `high`, `medium`, `low`
`--json`	Output raw JSON
`--verbose`	Show token usage and timing

`patchpilots custom <agent-name> <path>`

Runs a custom agent you defined in .patchpilots.json. List available agents with patchpilots custom list ..

`patchpilots memory <path>`

View or clear project memory from previous runs.

Option	Description
`--clear`	Clear all project memory
`--json`	Output raw JSON

Project Memory

PatchPilots remembers. After each review or security audit, findings are tracked in .patchpilots-memory.json. On the next run, agents get context about:

Recurring issues — found multiple times across runs, flagged for extra attention
Recently fixed — verified to stay fixed
Open vs closed — track what's been addressed

# View memory status
npx patchpilots memory ./src

# Clear memory
npx patchpilots memory ./src --clear

Memory makes every subsequent review smarter — agents know what was found before, what keeps coming back, and what's been fixed.

Custom Agents

Define your own review rules in .patchpilots.json:

{
  "customAgents": [
    {
      "name": "naming",
      "description": "Check naming conventions",
      "prompt": "Review code for our naming rules: components PascalCase, hooks use*, utils camelCase, constants UPPER_SNAKE"
    },
    {
      "name": "api-patterns",
      "description": "Verify API patterns",
      "prompt": "Check that all API calls use our fetchWrapper, have error handling, and include loading states"
    }
  ]
}

Then run:

# Run your custom agent
npx patchpilots custom naming ./src

# List available custom agents
npx patchpilots custom list .

No other AI code review tool lets you define your own agents like this.

Configuration

Set your API key once globally so it works for every project:

echo '{"apiKey": "sk-ant-..."}' > ~/.patchpilots.json

Or create a per-project .patchpilots.json:

{
  "model": "claude-sonnet-4-6",
  "maxTokens": 64000,
  "include": ["**/*.ts", "**/*.js", "**/*.tsx", "**/*.jsx", "**/*.html", "**/*.css"],
  "exclude": ["node_modules/**", "dist/**"],
  "maxFileSize": 100000,
  "maxFiles": 20
}

Config resolution order: CLI flags > project .patchpilots.json > global ~/.patchpilots.json > ANTHROPIC_API_KEY env var.

Smart Model Routing

Route files to different Claude models based on complexity — simple files go to Haiku (cheap + fast), most code to Sonnet, and complex/security-critical files to Opus.

# Enable via CLI flag
npx patchpilots audit ./src --routing

# Or in .patchpilots.json

{
  "modelRouting": {
    "enabled": true,
    "fast": "claude-haiku-4-5",
    "standard": "claude-sonnet-4-6",
    "deep": "claude-opus-4-6",
    "fastMaxLines": 50,
    "deepMinLines": 500,
    "fastPatterns": ["types", "constants", "config", "index"],
    "deepPatterns": ["auth", "crypto", "security", "middleware", "payment", "database"]
  }
}

Tier	Default model	When
fast	claude-haiku-4-5	Files under 50 lines, or matching `types`, `config`, `constants`, `index`, `.d.ts`
standard	claude-sonnet-4-6	Everything else
deep	claude-opus-4-6	Files over 500 lines, or matching `auth`, `crypto`, `security`, `middleware`, `payment`, `database`, `migration`

Pattern matching takes priority over line count. All thresholds and patterns are configurable.

Supported file types

TypeScript, JavaScript, JSX/TSX, Python, Go, Rust, Java, Ruby, PHP, C/C++, C#, Swift, Kotlin, HTML, CSS, SCSS, Vue, Svelte.

GitHub Action

Auto-review every PR with one workflow file:

# .github/workflows/patchpilots.yml
name: PatchPilots Review
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: alavesa/patchpilots@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          path: './src'

The action posts findings as a PR comment (updated on each push, no spam). Critical findings fail the check by default.

Input	Default	Description
`anthropic_api_key`	(required)	Your Anthropic API key
`path`	`./src`	Path to review
`model`	`claude-sonnet-4-6`	Claude model to use
`skip`		Agents to skip (e.g. `plan,test,docs`)
`severity`	`info`	Minimum severity to report
`fail_on_critical`	`true`	Fail the check on critical findings
`changed_only`	`false`	Only review files changed in the PR (faster, cheaper)

Powered by Claude API

Structured outputs — guaranteed schema compliance via JSON schema enforcement
Adaptive thinking — deeper reasoning catches bugs a surface scan misses
Streaming — real-time response delivery, no timeouts
Prompt caching — ~90% cost savings on repeat runs
Smart model routing — Haiku for simple files, Sonnet for most code, Opus for complex/critical
Cost tracking — per-agent token usage and USD estimate after every run
Diff-based patches — search-and-replace instead of full files, works on large codebases

Architecture

Every agent extends BaseAgent<T> and implements three methods:

class MyAgent extends BaseAgent<MyOutputType> {
  getSystemPrompt()          // What the agent's role is
  buildUserMessage(context)  // How to format the input
  getOutputSchema()          // Zod schema — guarantees output shape
}

Adding a new agent is one file + three methods.

Roadmap

Done

Next up

GitHub Action — auto-review PRs and post findings as comments
Parallel file review — review in batches instead of one giant prompt
Changed files only — GitHub Action reviews only files touched in the PR for faster, cheaper runs
Smart model routing — Haiku for simple files, Sonnet for most code, Opus for complex/critical
Custom agents — define your own agents via .patchpilots.json
Designer agent — WCAG 2.1 AA accessibility, design tokens, CSS consistency, component markup

Future agents

Code quality

🌍 i18n — hardcoded strings, RTL issues, locale assumptions
⚡ Performance — bundle size, render patterns, lazy loading opportunities
📊 Analytics — event tracking coverage, naming consistency, missing flow events
♻️ Refactor — duplication detection, abstraction suggestions
🧓 Legacy — flags patterns that made sense in 2019 but not anymore

Design systems

📐 Consistency — same pattern implemented 3 different ways across components
🧩 API — component prop naming consistency, missing variants, breaking changes

Solo dev tools

🚢 ShipPilot — "is this actually ready to deploy?" checklist agent
📣 Changelog — auto-generates release notes from diffs
💸 CostPilot — estimates Claude API spend before running the full audit

Future platforms

🔌 MCP Server — security agent inside Claude Code, Cursor, and any MCP-compatible IDE (patchpilots-mcp)
🌐 Web UI — drag and drop a repo, get a report. No CLI needed

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 94 Commits
.github/workflows		.github/workflows
action		action
bin		bin
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

PatchPilots

See it in action

Use it 4 ways

npx — no install, one-off

Global install — your machine, any project

GitHub Action — automatic on every PR

MCP Server — security scanning inside your IDE

The Killer Feature

The Crew

Quick start

CLI commands

patchpilots audit <path>

patchpilots review <path>

patchpilots improve <path>

patchpilots test <path>

patchpilots plan <path>

patchpilots docs <path>

patchpilots security <path>

patchpilots designer <path>

patchpilots custom <agent-name> <path>

patchpilots memory <path>

Project Memory

Custom Agents

Configuration

Smart Model Routing

Supported file types

GitHub Action

Powered by Claude API

Architecture

Roadmap

Done

Next up

Future agents

Future platforms

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`npx` — no install, one-off

`patchpilots audit <path>`

`patchpilots review <path>`

`patchpilots improve <path>`

`patchpilots test <path>`

`patchpilots plan <path>`

`patchpilots docs <path>`

`patchpilots security <path>`

`patchpilots designer <path>`

`patchpilots custom <agent-name> <path>`

`patchpilots memory <path>`

Packages