# RepoPilot
[](https://crates.io/crates/repopilot)
[](https://www.npmjs.com/package/repopilot)
[](https://github.com/MykytaStel/repopilot/actions)
[](https://github.com/MykytaStel/repopilot/releases)
[](LICENSE)
[](https://github.com/MykytaStel/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:
| 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 | ✅ |
```bash
## 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](docs/rulesets.md) for the full list of rules and severity levels.
## Install
```bash
cargo install repopilot
```
Install with npm:
```bash
npm install -g repopilot
```
Install with Homebrew:
```bash
brew tap mykytastel/repopilot
brew install repopilot
```
Install with curl (Linux/macOS):
```bash
The curl installer verifies the GitHub Release SHA256 checksum and aborts if the checksum cannot be downloaded or verified.
Upgrade:
```bash
cargo install repopilot --force
npm update -g repopilot
brew update && brew upgrade repopilot
```
Build from source:
```bash
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:
```bash
repopilot scan .
```
Then get an AI-ready brief to paste into Claude Code, Cursor, or ChatGPT:
```bash
```
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:
```bash
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:
```bash
repopilot scan . --format markdown --output repopilot-report.md --receipt .repopilot/receipt.json
```
Reduce scan noise while iterating:
```bash
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.
```bash
# 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)
## 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.
```bash
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
| `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:
```bash
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:
```text
CLI args > repopilot.toml > built-in defaults
```
Generate a default config:
```bash
repopilot init
repopilot init --force
repopilot init --path ./repopilot.toml
```
Use an explicit config path:
```bash
repopilot scan . --config repopilot.toml
```
Example `repopilot.toml`:
```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:
```bash
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.
```bash
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.
```bash
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:
```bash
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
```bash
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
```bash
repopilot scan . --format sarif --output repopilot.sarif
```
If your installed RepoPilot version does not support `--output`, redirect stdout instead:
```bash
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](docs/integrations/github-code-scanning.md) for a copy-paste GitHub Actions workflow, required permissions, and local validation commands.
Compare two JSON reports:
```bash
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.
```yaml
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
| [docs/install.md](docs/install.md) | Installation options for Cargo, npm, Homebrew, curl, and source builds |
| [docs/ai-workflows.md](docs/ai-workflows.md) | Claude Code, ChatGPT, Cursor, and AI remediation workflows |
| [docs/security.md](docs/security.md) | Local-first trust model, installer security, and vulnerability reporting |
| [docs/configuration.md](docs/configuration.md) | `repopilot.toml`, presets, ignore files, and baseline adoption |
| [docs/language-support.md](docs/language-support.md) | Supported language/framework tiers, rule families, and limitations |
| [docs/cli.md](docs/cli.md) | Complete CLI reference — all commands, flags, and exit codes |
| [docs/commands.md](docs/commands.md) | Task-oriented command guide and common patterns |
| [docs/rulesets.md](docs/rulesets.md) | Implemented audit rules, categories, and severity levels |
| [docs/react-native.md](docs/react-native.md) | React Native and Expo detection, findings, and limitations |
| [docs/integrations/github-code-scanning.md](docs/integrations/github-code-scanning.md) | GitHub Code Scanning SARIF workflow |
| [docs/release.md](docs/release.md) | Manual release process |
| [docs/release-checklist-0.10.md](docs/release-checklist-0.10.md) | 0.10.0 release readiness checklist |
| [docs/distribution.md](docs/distribution.md) | Distribution channels |
| [docs/github-ruleset.md](docs/github-ruleset.md) | GitHub branch ruleset configuration |
| [CHANGELOG.md](CHANGELOG.md) | Version history |
## License
RepoPilot is licensed under MIT OR Apache-2.0.