repopilot 0.11.0

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

RepoPilot

Crates.io npm CI GitHub Release License GitHub Stars

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.11.0 is a signal quality and CI polish release: it reduces low-value self-audit findings, adds first-party Action parity for priority/rule filters, and tightens the doctor -> scan/review -> ai context -> CI gate loop 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 scan . --min-priority p2 --rule security.secret-candidate
repopilot ai context . --focus security                     # prepare local AI context
repopilot baseline create .                                 # accept existing findings as known debt
repopilot review . --base origin/main --fail-on-priority p1 # CI gate on high-priority risk

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-priority p1
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 risk clusters, 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: doctor, command: ai-context, command: ai-plan, or command: ai-prompt; AI commands emit Markdown and do not produce SARIF. Prefer typed action inputs such as path, config, baseline, fail-on, fail-on-priority, min-priority, rule, timing, 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

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/risk-engine.md Risk scoring, priority buckets, signals, and calibration policy
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-announcement-0.11.md 0.11.0 launch post and post-publish checks
docs/release-checklist-0.11.md 0.11.0 release readiness checklist
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.