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 findings: oversized files, deep nesting, 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
• 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, HTML, and SARIF 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 .

Commands

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

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. Use Markdown for human-readable reports. Use SARIF for CI and code scanning integrations, including GitHub Code Scanning.

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.

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

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

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

Roadmap

These are planned ideas, not current features:

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

Documentation

License

RepoPilot is licensed under MIT OR Apache-2.0.