RepoPilot

Audit your repository locally, turn the results into AI-ready remediation context, and ship safer changes without sending source code to a hosted scanner.

RepoPilot is a local-first CLI for architecture, security, code quality, testing, and framework health checks. It gives developers useful terminal reports, CI gates, SARIF for GitHub Code Scanning, and Markdown briefs that can be pasted into Claude Code, ChatGPT, Cursor, or another coding assistant.

Version 0.10.0 is an adoption and stability release: it focuses on cleaner rollout diagnostics, reproducible audit receipts, CI artifacts, and 0.x command compatibility while keeping all scans local.

Why RepoPilot?

Most linters and audit tools stop at the terminal. RepoPilot bridges the gap to your AI assistant:

	SonarQube / CodeClimate	ESLint / language linters	RepoPilot
Runs offline	❌	✅	✅
No code upload	❌	✅	✅
Cross-language architecture analysis	✅	❌	✅
LLM-ready output	❌	❌	✅
Fits in a model context window	❌	❌	✅
CI gate on new findings only	✅	partial	✅

repopilot ai context . | pbcopy   # macOS: paste into your coding assistant

Features

Repository scanning for projects, folders, and individual files
Gitignore-aware walking with built-in ignores for common build, cache, vendor, and native platform directories
Architecture findings: oversized files, deep nesting, deep relative imports, risky barrel files, too many modules per directory
Coupling analysis: excessive fan-out, high-instability hubs, circular dependencies
Code quality findings: cyclomatic complexity density, long functions, TODO/FIXME/HACK markers
Security findings: hardcoded secret candidates, committed private keys, committed .env files
Testing findings: missing test folder, source files without test counterparts
Framework findings for JavaScript, React, React Native, Expo, and Django projects
React Native architecture profile: project kind, New Architecture, Hermes, Codegen, platform mismatch, and package manager signals
Workspace scanning (--workspace) for npm, yarn, pnpm, and Cargo workspaces with per-package risk summary — parallel per-package scans
Evidence-backed findings with stable rule IDs, severity, file paths, line numbers, and snippets
46 built-in rules with titles, descriptions, recommendations, and docs links
repopilot.toml configuration generated by repopilot init
Configuration presets (--preset strict|balanced|lenient) for quick threshold tuning
Baseline workflow for accepting existing findings in legacy repositories
CI-friendly failure thresholds with --fail-on
Git diff-aware review mode for prioritizing findings introduced by changed lines
Doctor adoption guidance for config, baseline, CI gate, report, and receipt readiness
Audit receipt JSON from repopilot scan --receipt for reproducible scan evidence
Console, JSON, Markdown, HTML, and SARIF (2.1.0) scan output — SARIF includes per-result category and workspace package properties
First-party GitHub Action wrapper for scan, review, compare, and ai workflows, with optional SARIF upload and receipt output for scans
Compare mode for diffing two JSON scan reports
repopilot ai context — formats scan output as LLM-ready markdown, paste into Claude Code or ChatGPT to start remediating
repopilot ai plan — turns findings into a prioritized remediation plan
repopilot ai prompt — exports an AI-ready remediation prompt with RepoPilot context

See docs/rulesets.md for the full list of rules and severity levels.

Install

cargo install repopilot

Install with npm:

npm install -g repopilot

Install with Homebrew:

brew tap mykytastel/repopilot
brew install repopilot

Install with curl (Linux/macOS):

curl -fsSL https://raw.githubusercontent.com/MykytaStel/repopilot/main/install.sh | bash

The curl installer verifies the GitHub Release SHA256 checksum and aborts if the checksum cannot be downloaded or verified.

Upgrade:

cargo install repopilot --force
npm update -g repopilot
brew update && brew upgrade repopilot

Build from source:

git clone https://github.com/MykytaStel/repopilot.git
cd repopilot
cargo build --release

Quick Start

No config needed. Run this in any repository and see findings immediately:

repopilot scan .

Then get an AI-ready brief to paste into Claude Code, Cursor, or ChatGPT:

repopilot ai context . | pbcopy   # macOS — copies to clipboard
repopilot ai context .            # print to terminal

That's the two-minute loop. Scan, read the output, paste the context into your assistant, fix.

Going deeper

Once you want CI integration, baseline tracking, or tighter configuration:

repopilot init                                              # generate repopilot.toml
repopilot doctor .                                          # check CI / baseline readiness
repopilot baseline create .                                 # accept existing findings as known debt
repopilot review . --base origin/main --fail-on new-high    # CI gate on new findings only

Save a shareable report:

repopilot scan . --format markdown --output repopilot-report.md --receipt .repopilot/receipt.json

Reduce scan noise while iterating:

repopilot scan . --min-severity high
repopilot scan . --workspace --min-severity medium
repopilot scan . --exclude fixtures --max-file-size 1mb --max-files 500

By default, RepoPilot skips low-signal audit paths such as tests, fixtures, examples, generated files, and benchmarks. Use --include-low-signal when you want those paths analyzed too.

Local-First AI Workflow

RepoPilot does not call LLM APIs. AI commands scan local files and produce Markdown that you decide where to paste.

repopilot ai context scans a project and formats all findings as structured markdown ready to paste into Claude Code, Cursor, ChatGPT, or any LLM assistant. It includes a risk level, tech stack summary, findings grouped by category with evidence snippets and fix recommendations, and a token-count estimate.

# Paste into Claude Code or ChatGPT
repopilot ai context .

# Focus on security only, keep it short
repopilot ai context . --focus security --budget 2k

# Save to file
repopilot ai context . --output repopilot-context.md

# Pipe directly into clipboard (macOS)
repopilot ai context . --no-header | pbcopy

Example Output

$ repopilot ai context .

# RepoPilot Vibe Check — my-app

**Risk Level:** 🟠 ELEVATED
**Tech Stack:** React Native (New Arch), Expo, TypeScript
**Size:** 94 files · 8,340 LOC · ~42k tokens
**Health:** 18 findings · 2.2/kloc — 4 high, 9 medium

## Security (2 high)
1. [HIGH] Possible secret detected — `src/config/api.ts:12`

const API_KEY = "sk_live_…"

> **Fix:** Move to environment variables or a secrets manager.

## Architecture (2 high)
1. [HIGH] Circular dependency detected — `src/store/index.ts`
> **Fix:** Extract shared types to a separate module to break the cycle.

## Top Recommendations
1. **Move hardcoded API key** (src/config/api.ts:12) — use process.env or a vault
2. **Break circular dependency** (src/store/index.ts) — extract shared types

---
*~3.8k tokens (budget: 4k) · scanned in 312ms — paste into Claude Code, Cursor, or ChatGPT*

Paste this into a coding assistant and ask for a focused patch. For larger repositories, start with one focus area instead of asking for every finding at once.

Recommended Remediation Loop

RepoPilot is a local-first safety layer for AI-assisted and vibe-coded changes. Run it after generating or refactoring code to catch newly introduced high-risk findings, workspace hotspots, missing tests, and architecture drift without uploading source code to an external service.

repopilot ai context . --focus security    # get an LLM brief for Claude Code
repopilot ai plan . --focus security       # get a prioritized hardening plan
repopilot ai prompt . --budget 8k          # generate a paste-ready remediation prompt
repopilot review . --base origin/main --baseline .repopilot/baseline.json --fail-on new-high
repopilot scan . --workspace --min-severity medium --format markdown --output repopilot-report.md

Commands

Command	Alias	Description
`repopilot scan <path>`	`s`	Scan a project, folder, or file for findings
`repopilot review [path]`	`r`	Review findings that touch changed Git diff lines
`repopilot ai context <path>`	—	LLM-ready context from a scan
`repopilot ai plan <path>`	—	Prioritized remediation plan
`repopilot ai prompt <path>`	—	AI-ready remediation prompt
`repopilot compare <before> <after>`	`cmp`	Compare two JSON scan reports and show what changed
`repopilot baseline create <path>`	`bl`	Scan a path and store current findings as accepted debt
`repopilot doctor [path]`	`d`	Diagnose audit readiness
`repopilot init`	—	Generate a default `repopilot.toml` configuration file

Use --help on any command for the full description and examples:

repopilot --help
repopilot scan --help
repopilot review --help
repopilot baseline create --help

Configuration

RepoPilot automatically reads repopilot.toml from the current working directory when running scan.

Configuration precedence:

CLI args > repopilot.toml > built-in defaults

Generate a default config:

repopilot init
repopilot init --force
repopilot init --path ./repopilot.toml

Use an explicit config path:

repopilot scan . --config repopilot.toml

Example repopilot.toml:

[scan]
ignore = [
  ".git",
  ".github",
  ".repopilot",
  "target",
  "node_modules",
  "dist",
  "build",
  ".next",
  ".nuxt",
  ".cache",
  "coverage",
  "vendor",
  "Pods",
  "DerivedData"
]
max_file_bytes = 2097152

[architecture]
max_file_lines = 300
huge_file_lines = 1000
max_directory_modules = 20
max_directory_depth = 5
max_function_lines = 50
max_fan_out = 15
instability_hub_min_fan_in = 5
instability_hub_min_instability_pct = 75

[testing]
detect_missing_tests = true

[security]
detect_secret_like_names = true

[output]
default_format = "console"

CLI threshold overrides:

repopilot scan . --max-file-loc 500
repopilot scan . --max-directory-modules 25
repopilot scan . --max-directory-depth 6
repopilot scan . --max-file-size 1mb
repopilot scan . --max-files 1000
repopilot scan . --exclude generated
repopilot scan . --include-low-signal

--max-file-size accepts raw bytes or kb, mb, and gb suffixes. --exclude matches an exact path relative to the scan root or a file/directory name; repeat it for multiple paths.

JSON output includes scan input accounting fields: files_discovered for files found after ignore/exclude filters, files_count for analyzed text files, files_skipped_low_signal for default low-signal skips, and binary_files_skipped for unreadable/binary files.

Baseline Workflow

Existing repositories often have findings that cannot all be fixed before adopting a new audit tool. A baseline stores accepted existing findings so future scans can distinguish new findings from existing ones.

repopilot baseline create .
repopilot scan . --baseline .repopilot/baseline.json
repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high

By default, baseline create writes .repopilot/baseline.json and creates the .repopilot/ directory if needed. Use --output ./baseline.json for a custom path. Existing baseline files are not overwritten unless you pass --force.

Baseline files store accepted existing findings. Future scans can mark findings as new or existing, which is useful for legacy repositories and CI. Do not refresh a baseline blindly unless the team accepts those findings as technical debt.

Review Workflow

Use review when you want RepoPilot to focus on findings that touch changed Git diff lines.

repopilot review .
repopilot review . --format json --output review.json
repopilot review . --baseline .repopilot/baseline.json --fail-on new-high

By default, review compares the working tree against HEAD, including staged, unstaged, and untracked files. For branch or CI review, pass a base ref:

repopilot review . --base origin/main
repopilot review . --base origin/main --head HEAD --format markdown

Review mode still scans the repository with the normal rules, but separates findings into in-diff and out-of-diff groups. When import coupling data is available, it also shows blast radius: files that import changed files and may need extra review. When --fail-on is used, the CI gate evaluates only in-diff findings.

Output Formats

repopilot scan . --format console
repopilot scan . --format json --output report.json
repopilot scan . --format markdown --output report.md
repopilot scan . --format html --output report.html
repopilot scan . --format sarif --output repopilot.sarif

SARIF output

repopilot scan . --format sarif --output repopilot.sarif

If your installed RepoPilot version does not support --output, redirect stdout instead:

repopilot scan . --format sarif > repopilot.sarif

Use JSON when custom scripts need to parse RepoPilot results. Console, Markdown, and HTML reports include the RepoPilot version, risk summary, top rules, and grouped findings for human review. Use SARIF for CI and code scanning integrations, including GitHub Code Scanning. Use --receipt <path> with scan when CI or release processes need compact evidence of the exact RepoPilot version, git state, scan scope, finding counts, language counts, and health score.

See docs/integrations/github-code-scanning.md for a copy-paste GitHub Actions workflow, required permissions, and local validation commands.

Compare two JSON reports:

repopilot scan . --format json --output before.json
repopilot scan . --format json --output after.json
repopilot compare before.json after.json
repopilot compare before.json after.json --format markdown
repopilot compare before.json after.json --format json --output diff.json

CI Usage

Use --fail-on new-high to fail CI only when new high or critical findings are introduced. Supported new-finding thresholds are new-low, new-medium, new-high, and new-critical.

When --fail-on new-* is used without --baseline, RepoPilot treats all current findings as new. For baseline-based adoption, commit an accepted baseline and scan against it in CI.

To upload RepoPilot findings to GitHub Code Scanning, generate SARIF and use github/codeql-action/upload-sarif. The workflow must include security-events: write. The first-party action can also run command: ai-context, command: ai-plan, or command: ai-prompt; those commands emit Markdown and do not produce SARIF. Prefer typed action inputs such as path, config, baseline, fail-on, focus, budget, output, and receipt; args remains available for advanced flags.

name: RepoPilot

on:
  pull_request:

permissions:
  contents: read
  security-events: write

jobs:
  repopilot:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install RepoPilot
        run: cargo install repopilot

      - name: Run RepoPilot
        run: repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high --receipt repopilot-receipt.json

      - name: Run RepoPilot (SARIF)
        run: repopilot scan . --format sarif --output repopilot.sarif

      - name: Upload to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v4
        if: always()
        with:
          sarif_file: repopilot.sarif

      - name: Upload audit receipt
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: repopilot-receipt
          path: repopilot-receipt.json

Roadmap

These are planned ideas, not current features:

Change Risk Map
Better architecture drift detection
Optional per-platform npm binary packages for faster installs

Documentation

Document	Description
docs/install.md	Installation options for Cargo, npm, Homebrew, curl, and source builds
docs/ai-workflows.md	Claude Code, ChatGPT, Cursor, and AI remediation workflows
docs/security.md	Local-first trust model, installer security, and vulnerability reporting
docs/configuration.md	`repopilot.toml`, presets, ignore files, and baseline adoption
docs/language-support.md	Supported language/framework tiers, rule families, and limitations
docs/cli.md	Complete CLI reference — all commands, flags, and exit codes
docs/commands.md	Task-oriented command guide and common patterns
docs/rulesets.md	Implemented audit rules, categories, and severity levels
docs/react-native.md	React Native and Expo detection, findings, and limitations
docs/integrations/github-code-scanning.md	GitHub Code Scanning SARIF workflow
docs/release.md	Manual release process
docs/release-checklist-0.10.md	0.10.0 release readiness checklist
docs/distribution.md	Distribution channels
docs/github-ruleset.md	GitHub branch ruleset configuration
CHANGELOG.md	Version history

License

RepoPilot is licensed under MIT OR Apache-2.0.

Name		Name	Last commit message	Last commit date
Latest commit History 80 Commits
.github		.github
Formula		Formula
bin		bin
docs		docs
examples		examples
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
action.yml		action.yml
deny.toml		deny.toml
install.sh		install.sh
package.json		package.json
repopilot.toml		repopilot.toml
rust-toolchain.toml		rust-toolchain.toml
rustfmt.toml		rustfmt.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

RepoPilot

Why RepoPilot?

Features

Install

Quick Start

Going deeper

Local-First AI Workflow

Example Output

Recommended Remediation Loop

Commands

Configuration

Baseline Workflow

Review Workflow

Output Formats

SARIF output

CI Usage

Roadmap

Documentation

License

About

Uh oh!

Releases 9

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

RepoPilot

Why RepoPilot?

Features

Install

Quick Start

Going deeper

Local-First AI Workflow

Example Output

Recommended Remediation Loop

Commands

Configuration

Baseline Workflow

Review Workflow

Output Formats

SARIF output

CI Usage

Roadmap

Documentation

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages