RepoPilot

Local-first CLI for repository audit, architecture risk detection, baseline tracking, and CI-friendly code review.

RepoPilot does not upload your repository. It helps developers understand what changed, what became riskier, and where to review first.

Why RepoPilot?

Modern developers ship more code than they can carefully review, especially with AI-assisted workflows.

RepoPilot helps you understand:

• what changed;
• what became riskier;
• which findings are new;
• which findings already existed;
• where to review first.

RepoPilot runs locally and does not upload your repository.

Features

• Repository scanning for projects, folders, and individual files
• Gitignore-aware walking with built-in ignores for common build and service directories
• Architecture, testing, code-quality, and security-oriented findings
• Evidence-backed findings with stable rule IDs, severity, file paths, line numbers, and snippets
• repopilot.toml configuration generated by repopilot init
• 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
• Console, JSON, Markdown, and HTML scan output
• Compare mode for diffing two JSON scan reports

See docs/rulesets.md for the implemented rules and severity levels.

Installation

cargo install repopilot

Upgrade:

cargo install repopilot --force

Build from source:

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

Quick Start

repopilot init
repopilot scan .

Useful help commands:

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",
  "coverage"
]

[architecture]
max_file_lines = 300
huge_file_lines = 1000
max_directory_modules = 20
max_directory_depth = 5
detect_empty_directories = true
detect_suspicious_names = true
detect_large_files = true

[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

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

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.

name: RepoPilot

on:
  pull_request:

jobs:
  repopilot:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - 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

Roadmap

These are planned ideas, not current features:

• Change Risk Map
• AI-ready review context export
• Better architecture drift detection
• GitHub Action integration

Documentation

License

RepoPilot is licensed under MIT OR Apache-2.0.