Hybrid repository intelligence for maintainers and coding agents.
RepoPilot scans your codebase and generates structured operating manuals for AI coding agents (Claude Code, Cursor, Copilot, Codex, Windsurf) and audit reports for human maintainers. It combines deterministic static analysis with optional AI-assisted synthesis, keeping facts strictly separated from interpretation.
AI coding agents work better when they understand your project. But most agents start cold — no context about your repo's structure, risk areas, validation commands, or trust boundaries.
RepoPilot solves this by analyzing your repository and producing a targeted instruction file. The agent gets a map of your codebase before it writes a single line of code: what to read first, what's risky, what commands to run, and when to stop and ask.
What makes it different:
- Evidence-backed, not prompt-stuffed. Outputs cite specific files, config entries, and directory signals — not vague generalizations.
- Trust model built in. Observed facts, inferred conclusions, and AI synthesis are never mixed. Contradictions are surfaced, not hidden.
- Works without AI. Static mode requires no API key and produces useful results from file scanning alone.
- Multi-agent support. Generates target-specific instruction files for Claude Code (
CLAUDE.md), Cursor (.cursorrules), GitHub Copilot (COPILOT.md), OpenAI Codex (AGENTS.md), and Windsurf (.windsurfrules). - Auditable. Maintainers get a structured report showing exactly what was analyzed, what the tool concluded, and what still needs human review.
| Feature | Description |
|---|---|
| Static Analysis | Deterministic scanning of file trees, dependency manifests, CI configs, test frameworks, linting tools, and command risk classification. No API key needed. |
| AI-Assisted Synthesis | Optional multi-pass LLM analysis over staged file reads. Produces architectural briefings, risk areas, and codebase explanations — all explicitly labeled as AI interpretation. |
| Repository Inventory | Every file classified by kind, semantic role, and importance. Read plans assign full, partial, summary, or skip modes based on repository scale. |
| Kind Classification | Scored repository-kind candidates (product, service, library, CLI, test-harness, etc.) with reasoning — not just a single label. |
| Trust Model | Rigorous separation of observed facts, inferred conclusions, AI synthesis, contradictions, and maintainer review items. |
| Change Impact Map | Shows how changes in one area affect other areas, with risk levels, relevant tests, and validation commands. |
| Agent Edit Strategies | Task-type-specific guidance: what to read first, what to run, when to escalate. |
| Hybrid Verdicts | When AI augments static analysis, merged conclusions surface contradictions and trust adjustments for review. |
| Explain This Repo | A dedicated human-readable briefing mode for developer onboarding. |
Scans the file tree, discovers frameworks from config files, classifies command risk levels, builds a repository inventory, and synthesizes a structured understanding — all deterministically. No API key required.
repopilot scan /path/to/repoAugments static evidence with staged LLM synthesis over actual file contents. RepoPilot inventories the repository, selects the highest-value files for reading, then runs five structured passes: identity, structure, risk/workflow, review/contradiction, and final synthesis.
AI output never overwrites static facts. It is reconciled into the structured result and explicitly labeled.
repopilot scan /path/to/repo --aiGenerates a comprehensive, human-readable briefing — purpose, architecture, functional areas, entrypoints, and onboarding context. Useful for new team members.
repopilot scan /path/to/repo --explainnpm install -g repopilotOr run without installing:
npx repopilot scan /path/to/repoRequirements: Node.js 18+
# Static analysis (no API key needed)
repopilot scan .
# AI-assisted analysis
repopilot scan . --ai
# Explain this repo (human-readable briefing)
repopilot scan . --explain
# JSON output to stdout
repopilot scan . --json
# Generate for a specific AI agent
repopilot scan . --target cursorDouble-click run.bat for an interactive guided experience. The launcher provides a menu for analysis, AI configuration, diagnostics, and output management. It handles first-time setup automatically.
By default, RepoPilot writes output to the .repopilot/ directory:
| File | Purpose |
|---|---|
CLAUDE.md |
Agent instruction file (or .cursorrules, AGENTS.md, etc. depending on --target) |
REPO-BRIEF.md |
Human-readable repository briefing |
report.md |
Maintainer audit report with evidence, contradictions, and review queues |
report.json |
Structured analysis for CI automation and programmatic consumption |
Use --claude-md to also write the agent instruction file to the repository root.
RepoPilot supports OpenAI, Anthropic, Google Gemini, and OpenRouter.
export REPOPILOT_AI_PROVIDER=anthropic
export REPOPILOT_AI_KEY=sk-ant-...
repopilot scan . --airepopilot config:set --provider openai --key sk-... --model gpt-4o
repopilot scan . --aiConfiguration is stored in ~/.repopilot-config/ai-config.json. This path is gitignored by default.
repopilot scan . --ai --ai-provider anthropic --ai-key sk-ant-...Run run.bat and select Configure AI provider for a guided setup with masked key input.
repopilot doctorRepoPilot enforces strict trust separation across all outputs:
- Observed Facts — Direct evidence from files (e.g., "vitest is in package.json"). Immutable.
- Inferred Conclusions — Heuristic deductions (e.g., "This is a tooling repository"). Provisional.
- AI Synthesis — LLM interpretations over repository reads. Always explicitly labeled.
- Hybrid Verdicts — Merged static + AI conclusions with trust adjustments and contradiction flags.
- Contradictions — Flagged when AI disagrees with static facts. Static evidence wins by default.
- Maintainer Confirmations — Blocking unknowns that need human input before trusting automation.
AI-generated content never appears inside observed facts. The report shows exactly what evidence the AI received and what it did not.
- API keys are never logged, committed, or written into generated outputs. Stored keys are saved to the user's home directory (
~/.repopilot-config/), which is gitignored. - Error messages are sanitized to strip API key patterns before display.
- The Windows launcher uses secure string handling for API key input and zeroes sensitive memory after use.
- Generated reports contain no secrets. Output normalization strips any content that could leak credentials.
- Environment variables take precedence over stored configuration, enabling safe CI usage.
git clone https://github.com/repopilot/repopilot-oss.git
cd repopilot-oss
npm install
npm run build
npm test| Command | Purpose |
|---|---|
npm test |
Run all tests (vitest) |
npm run typecheck |
TypeScript type checking |
npm run build |
Build dist output (tsup) |
npm run dev |
Watch mode build |
See CONTRIBUTING.md for details on adding analyzers, generators, and contributing to the trust model.
- AI-assisted analysis requires an API key from a supported provider. Static mode works without one.
- AI synthesis quality depends on the model. Results may vary across providers. Always review AI-generated conclusions before relying on them.
- Large repositories use staged reading with prioritization. Some files may be partially read or skipped. The coverage report shows exactly what was and wasn't analyzed.
- Language detection is file-extension-based. It doesn't parse file contents to determine language.
- No runtime analysis. RepoPilot analyzes static repository structure, not running code behavior.
- Windows launcher requires PowerShell 5.1+ (included with Windows 7 SP1 and later).
See CONTRIBUTING.md for setup instructions, project structure, and contribution guidelines.