# 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)
Scan your repo. Paste the result into Claude Code or ChatGPT. Start fixing.
RepoPilot is a local-first CLI that audits architecture, security, code quality, and framework health — then formats everything as LLM-ready context you can drop directly into an AI assistant. No code leaves your machine.
## 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, 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 — parallel per-package scans
- 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`
- 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
- 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`, `vibe`, `harden`, and `prompt`, with optional SARIF upload for scans
- Compare mode for diffing two JSON scan reports
- **`repopilot vibe`** — new in v0.8: formats scan output as LLM-ready markdown, paste into Claude Code or ChatGPT to start remediating
- **`repopilot harden`** — new in v0.8: turns findings into a prioritized remediation plan
- **`repopilot prompt`** — new in v0.8: 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.
## Installation
```bash
cargo install repopilot
```
Install with npm:
```bash
npm install -g repopilot
```
Install with Homebrew:
```bash
brew install MykytaStel/repopilot/repopilot
```
Install with curl (Linux/macOS):
```bash
Upgrade:
```bash
cargo install repopilot --force
npm update -g repopilot
```
Build from source:
```bash
git clone https://github.com/MykytaStel/repopilot.git
cd repopilot
cargo build --release
```
## Quick Start
```bash
repopilot init
repopilot scan .
```
React Native quick scan:
```bash
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:
```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.
## Vibe Check (new in v0.8)
`repopilot vibe` 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 vibe .
# Focus on security only, keep it short
repopilot vibe . --focus security --budget 2k
# Save to file
repopilot vibe . --output vibe.md
# Pipe directly into clipboard (macOS)
## Example Output
```
$ repopilot vibe .
# 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 Claude Code and ask: *"Fix all findings."*
## 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.
```bash
repopilot vibe . --focus security # get an LLM brief for Claude Code
repopilot harden . --focus security # get a prioritized hardening plan
repopilot 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 vibe <path>` | `v` | **New in v0.8** — LLM-ready context from a scan |
| `repopilot harden <path>` | `h` | **New in v0.8** — prioritized remediation plan |
| `repopilot prompt <path>` | `p` | **New in v0.8** — AI-ready remediation prompt |
| `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:
```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.
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: vibe`, `command: harden`, or `command: prompt`; those commands emit Markdown and do not produce SARIF.
```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
- 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
```
## 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/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/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.