RepoPilot

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

RepoPilot runs on your machine and 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
Framework findings for JavaScript, React, React Native, and Expo 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
Evidence-backed findings with stable rule IDs, severity, file paths, line numbers, and snippets
36 built-in rules with titles, descriptions, recommendations, and docs links
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 (2.1.0) scan output — SARIF includes per-result category and workspace package properties
First-party GitHub Action wrapper with optional SARIF upload
Compare mode for diffing two JSON scan reports

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

Installation

cargo install repopilot

Install with npm:

npm install -g repopilot

Upgrade:

cargo install repopilot --force
npm update -g repopilot

Build from source:

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

Quick Start

repopilot init
repopilot scan .

React Native quick scan:

repopilot scan . --format markdown --output repopilot-report.md
repopilot review . --base origin/main --baseline .repopilot/baseline.json --fail-on new-high

Reduce scan noise while iterating:

repopilot scan . --min-severity high
repopilot scan . --workspace --min-severity medium

AI-Assisted Workflow

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 review . --base origin/main --baseline .repopilot/baseline.json --fail-on new-high
repopilot scan . --workspace --min-severity medium --format markdown --output repopilot-report.md

The v0.7.0 release does not add new vibe, harden, or AI prompt commands. Those are planned as deterministic post-0.7 workflows built on the existing scan and review data.

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 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 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",
  "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:

Vibe Check command for AI-assisted codebase readiness
Hardening Plan output based on existing findings
AI-agent prompt/context export
Change Risk Map
Better architecture drift detection
Optional per-platform npm binary packages for faster installs

Documentation

Document	Description
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/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.

repopilot 0.7.0