🧭 RepoPilot — Local Repository Analyzer

RepoPilot is a local-first repository intelligence engine and architectural analyzer that helps developers understand, inspect, document, and improve software repositories.

It combines repository scanning, Abstract Syntax Tree (AST) analysis, static code checks, dependency inspection, architecture extraction, and local AI inference through Ollama to produce structured software engineering intelligence across 18 analysis dimensions.

RepoPilot also provides an interactive architecture explorer, evidence-oriented code findings, AI-assisted issue resolution, repository rebuild-prompt generation, and CLI-based developer workflows.

Core idea: Understand any codebase, discover its architectural structure, identify engineering risks, and help developers fix issues without depending on cloud LLM APIs.

---

📑 Table of Contents

• Overview
• Why RepoPilot
• Architecture
• Autonomous Repository Repair Engine (Stages A–G)
• NVIDIA and Nebius AI Cloud Integration
• Safe Code Execution and Sandbox Isolation
• Reproducible Benchmark Suite
• Deterministic Seeded Demonstration
• The 18 Analysis Modules
• Platform Features
• Interactive Architecture Explorer
• Live AI Issue Solver
• Technology Stack
• Repository Structure
• Getting Started
• API Reference
• CLI Reference
• Inference Backends
• Security and Execution Safety
• Testing and Verification
• Roadmap
• Contributing
• License

---

🎯 Overview

Understanding an unfamiliar codebase is one of the most time-consuming parts of software development. Developers often need to inspect numerous files, trace dependencies, identify entry points, understand API routes, and reconstruct the architecture before they can safely make changes.

RepoPilot streamlines this process by combining deterministic repository inspection with AI-assisted analysis.

The problem

• Large repositories take time to understand.
• Architecture diagrams and documentation can become outdated.
• Dependencies, routes, database models, and services are scattered across files.
• Security issues and maintainability problems can be difficult to discover manually.
• New developers need a reliable onboarding path.
• Debugging unfamiliar projects requires tracing code and understanding dependencies.
• Rebuilding a project from scratch requires a detailed understanding of its behavior and architecture.

The solution

RepoPilot accepts a repository URL or supported local path, inspects the codebase, collects structural evidence, runs available static checks, and uses a configured inference backend to synthesize the results into a structured engineering report.

Design principles

• Local-first AI: Ollama provides local inference without requiring a cloud LLM API key.
• Evidence-oriented analysis: Repository files and static findings provide the foundation for analysis.
• Dynamic architecture discovery: Build architecture representations from discovered repository structure rather than fixed project templates.
• Structured output: Organize analysis into distinct engineering dimensions.
• Developer-controlled remediation: Review generated patches and validate changes before trusting them.
• Modular workflows: Use the web dashboard or CLI for supported repository operations.

---

🏗️ Architecture

RepoPilot follows a staged analysis pipeline that combines deterministic scanning with local AI synthesis.

flowchart TD
    A["Repository URL or Local Path"] --> B["Repository Validator"]
    B --> C["Isolated Repository Workspace"]
    C --> D["Repository Scanner"]
    D --> E["Language and Framework Detection"]
    D --> F["Dependency Analysis"]
    D --> G["AST and Static Audits"]
    E --> H["Context Builder and Chunking"]
    F --> H
    G --> H
    H --> I["Inference Backend"]
    I --> J["Validated Structured Analysis"]
    J --> K["18 Analysis Modules"]
    K --> L["Frontend Dashboard"]
    K --> M["Architecture Explorer"]
    K --> N["Issue Solver and Recommendations"]

Loading

Architecture components

Component	Responsibility
Repository Validator	Validates supported repository inputs
Repository Workspace	Clones or prepares repository files for analysis
Repository Scanner	Filters files and respects configured ignore rules
Language and Framework Detector	Identifies supported languages, frameworks, and project tooling
Dependency Analyzer	Inspects manifests and dependency declarations
AST and Static Audits	Extracts code structure and detects supported static findings
Context Builder	Prepares bounded, relevant analysis context
Inference Backend	Uses the selected Ollama or configured alternative provider
Structured Output Validator	Validates analysis data before it is presented
Analysis Modules	Organize the results into 18 engineering dimensions
Frontend Dashboard	Presents analysis results and findings
Architecture Explorer	Visualizes repository components and their relationships
Issue Solver	Generates proposed fixes and validation instructions

Important: AI-generated conclusions are only as reliable as the available repository evidence, supported language analyzers, model output, and validation logic. Static findings should be distinguished from AI-generated interpretations.

---

🛠️ Autonomous Repository Repair Engine

RepoPilot includes a production-minded, closed-loop Autonomous Repository Repair Engine operating across 8 verified execution stages:

flowchart LR
    A["Stage A: Ingestion"] --> B["Stage B: Intelligence"]
    B --> C["Stage C: Understanding"]
    C --> D["Stage D: Investigation"]
    D --> E["Stage E: Patching"]
    E --> F["Stage F: Validation"]
    F -->|Tests Pass| G["Stage G: Evidence Report"]
    F -->|Tests Fail| R{"Retry Loop (<= 3)"}
    R -->|Diagnose Failure| D
    R -->|Max Exceeded| G

Loading

The 8 Stages of Repair

1. Stage A: Repository Ingestion
   • Validates repository access and directory layout.
   • Detects project languages, framework entry points, and test harnesses (pytest, npm test, jest, vitest).
   • Initializes a disposable, isolated task workspace with git protection.
2. Stage B: Grounded Repository Intelligence
   • Extracts AST symbols, function signatures, classes, and import graphs deterministically.
   • Grounded evidence facts are recorded with exact file:line locations before calling models.
3. Stage C: Issue Understanding & Acceptance Criteria
   • Analyzes natural-language bug reports or stack traces.
   • Generates a structured RepairPlan with target files, acceptance criteria, and blast-radius assessment.
4. Stage D: Root-Cause Investigation
   • Ranks root-cause candidate hypotheses based on static evidence and symbol relationships.
   • Cites exact line ranges and explains failure mechanics.
5. Stage E: Scoped Code Modification
   • Synthesizes the smallest scoped patch adhering strictly to the repository's existing conventions.
   • Formats a standard unified Git diff.
   • Dry-runs patch application via git apply --check before applying.
6. Stage F: Automated Validation & Isolation
   • Executes the detected test harness inside a bounded, credential-scrubbed workspace subprocess.
   • Parses individual test outcomes (PASS, FAIL, SKIPPED, ERROR) with execution times and stderr logs.
7. Intelligent Retry Loop
   • If tests fail, the engine diagnoses the failure output, rolls back using git checkout -- ., and retries with refined constraints (bounded to max 3 attempts).
8. Stage G: Evidence-Backed Report & Review
   • Compiles a structured RepairReport distinguishing verified facts, tool telemetry, and model hypotheses.
   • Developer inspects unified diff and test telemetry in the UI, with approval/rejection and branch creation controls.

---

⚡ NVIDIA and Nebius AI Cloud Integration

RepoPilot provides a dual-provider architecture supporting local models and cloud inference side-by-side:

• Local First: Existing Ollama support is 100% preserved and operates without any cloud API keys.
• Hackathon Cloud Inference: Nebius Token Factory / Nebius AI Cloud using eligible NVIDIA open-source models (e.g. nvidia/nemotron-3-super or meta-llama/llama-3.1-70b-instruct).

Environment Configuration

Configure providers in .env or .env.local:

# Select Provider: 'nebius' or 'ollama'
REPOPILOT_MODEL_PROVIDER=nebius

# Nebius Token Factory Credentials (never exposed to client browser)
NEBIUS_API_KEY=your_nebius_api_key_here
NEBIUS_BASE_URL=https://api.tokenfactory.nebius.com/v1
NEBIUS_MODEL=nvidia/nemotron-3-super

# Local Ollama Configuration (Fallback)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=nemotron-3-super

Safety & Credential Protection

• All NEBIUS_API_KEY credentials are scrubbed from server logs and subprocess environments.
• API endpoints return redacted configuration statuses (/api/provider/status and /api/nebius/health).
• Automatic exponential backoff (1s, 2s, 4s) handles provider rate limits gracefully.

---

🛡️ Safe Code Execution and Sandbox Isolation

RepoPilot treats all repository code as untrusted input. The execution engine enforces strict isolation:

• Per-Task Workspace: Every repair run operates inside an isolated directory (/tmp/repopilot_workspaces/<task_id>/).
• No Shell String Interpolation: All subprocesses execute via argument arrays (subprocess.run(["pytest", "-v"], ...)), eliminating shell injection.
• Resource Limits:
  • Hard execution timeout: 120 seconds.
  • Memory bounds and subprocess group termination on timeout.
  • Standard output and error capped at 500 KB to prevent memory exhaustion.
• Host Secret Scrubbing: Sensitive environment variables (AWS_*, SSH_*, GITHUB_*, NEBIUS_*, SECRET_*) are stripped from the test runner's environment.
• Controlled Git Operations: Autonomous changes are isolated to a disposable workspace; patches are applied to the user's repository only upon explicit developer approval.

---

📊 Reproducible Benchmark Suite

RepoPilot includes an automated evaluation harness and 12 reproducible benchmark test cases across Python and TypeScript:

Case ID	Language	Category	Issue Description	Baseline	Actual Result
py-auth-none	Python	AttributeError	NoneType check in auth_service login	FAIL	PASS
py-zero-div	Python	ZeroDivisionError	Safe average calculation on empty list	FAIL	PASS
py-dict-key	Python	KeyError	Missing optional key in config loader	FAIL	PASS
py-index-oob	Python	IndexError	Safe array slice on out-of-bounds index	FAIL	PASS
py-type-err	Python	TypeError	String concatenation with None parameter	FAIL	PASS
py-file-not	Python	FileNotFoundError	Fallback default when cache file absent	FAIL	PASS
ts-undefined	TypeScript	TypeError	Optional chaining on undefined user profile	FAIL	PASS
ts-null-prop	TypeScript	NullPointer	Safe navigation on nullable database result	FAIL	PASS
ts-array-pop	TypeScript	BoundsError	Pop from empty queue handler	FAIL	PASS
ts-num-nan	TypeScript	ArithmeticError	NaN guard on price calculation	FAIL	PASS
ts-json-err	TypeScript	SyntaxError	Defensive JSON.parse in webhook handler	FAIL	PASS
ts-async-rej	TypeScript	UnhandledRejection	Try/catch wrapper around network fetch	FAIL	PASS

Running the Benchmark Suite

# Run evaluation harness tests
backend/.venv/bin/pytest backend/tests/test_benchmark_harness.py -v

# Run full benchmark evaluation
python3 -m backend.benchmark.runner --output benchmark_results.json

---

🎬 Deterministic Seeded Demonstration

RepoPilot ships with a seeded demonstration repository and deterministic regression test for live presentations and judge evaluations.

Demonstration Steps

1. Reset the Seed Fixture to Known Buggy State:

   ./bin/repopilot demo --reset

2. Execute the End-to-End Autonomous Repair Walkthrough:

   ./bin/repopilot demo

   Or launch via the repair engine CLI:

   ./bin/repopilot repair \
     --repo=backend/demo/seed_repo \
     --issue="Fix NoneType AttributeError in auth_service.py login() when authenticate_user returns None for invalid credentials, and make test_auth_service.py pass." \
     --test-cmd="pytest"

3. Observe the Complete Pipeline:
   • Detects auth_service.py and test_auth_service.py via AST inspection.
   • Captures the initial failing regression test (pytest test_auth_service.py -> FAIL).
   • Generates minimal defensive patch in auth_service.py.
   • Validates the patch via git apply --check and re-runs pytest -> 1 passed in 0.04s (PASS).
   • Generates evidence report and unified diff.

---

✨ The 18 Analysis Modules

RepoPilot organizes repository intelligence into 18 modules.

#	Module	What it analyzes
1	Project Overview	Project purpose, target audience, maturity, and overall quality
2	Architecture	Frontend, backend, database layers, communication flow, and Mermaid architecture
3	Directory Structure	Directory hierarchy and the responsibilities of key folders
4	Technology Stack	Languages, lines of code, percentages, frameworks, databases, libraries, tools, and deployment
5	Features	Features supported by evidence found in repository files
6	API Analysis	Routes, HTTP methods, controllers, parameters, responses, and middleware
7	Database Analysis	Database engines, ORMs, models, schemas, relationships, and migrations
8	Dependency Analysis	Production dependencies, development dependencies, and suspicious dependency indicators
9	Security Analysis	Static security checks with strict secret redaction
10	Code Quality	Complexity, large functions, maintainability concerns, and pattern detection
11	Testing	Test frameworks, test directories, test counts, coverage configuration, and potential gaps
12	CI/CD	Workflows, Docker, containerization, and pipeline stages
13	Documentation	README quality, documentation coverage, and API documentation status
14	Environment Configuration	Names of variables detected in .env.example files, without displaying values
15	Project Health Score	Multidimensional scores from 0–100 with supporting rationales
16	Top Problems	Prioritized findings categorized as CRITICAL, HIGH, MEDIUM, or LOW
17	Recommendations	Actionable improvements with estimated effort
18	Onboarding Guide	Step-by-step guidance for developers joining the project

Evidence-first reporting

RepoPilot is designed to combine information from:

• README and documentation files
• Package and dependency manifests
• Source code and AST structure
• API routes and entry points
• Database schemas and migrations
• CI/CD configuration
• Tests and coverage configuration
• Environment variable templates
• Static scanner findings

A detected file or configuration does not automatically prove that the corresponding functionality works correctly at runtime. Analysis reports should communicate limitations when repository evidence is incomplete.

---

🧠 Platform Features

1. Deep Repository Analysis

Analyze supported public Git repositories or supported local repository paths.

• Repository validation
• Shallow Git cloning for URL-based analysis
• Smart file filtering and ignore handling
• Language and framework detection
• Dependency inspection
• Static code auditing
• Structured engineering reports

2. Interactive Architecture Explorer

Generate an interactive, mind-map-style architecture view from discovered repository components and relationships.

Supported platform capabilities described by this project include:

• Dynamic architecture node generation
• Repository, frontend, backend, database, API, service, model, authentication, and external-service categories
• Pan and zoom
• Fit-to-view and reset controls
• Minimap navigation
• Node dragging
• Layer visibility toggles
• Fullscreen exploration
• Node inspection for constituent files, dependencies, connected nodes, and responsibilities

The architecture graph is intended to reflect the analyzed repository rather than a single hardcoded application template.

3. Static Code Findings

RepoPilot can surface supported static findings across several severity levels:

• CRITICAL
• HIGH
• MEDIUM
• LOW
• INFO

Examples of targeted checks include:

• Syntax errors
• Undefined identifiers, where supported by the analyzer
• Swallowed exceptions
• Empty catch blocks
• Dangerous eval usage
• Unsafe innerHTML patterns
• Potentially unhandled error states

Each finding should be interpreted in context. Static pattern matches can produce false positives and do not replace runtime testing or a comprehensive security audit.

4. Context-Aware Code Inspection

The analysis interface can present a syntax-highlighted code view focused on the relevant finding and target line, helping developers navigate from an issue to the corresponding source location.

5. AI-Powered Developer Onboarding

Generate an onboarding guide that explains the discovered repository structure, technology stack, important entry points, application layers, and suggested exploration order.

6. Repository Rebuild Prompt Generator

Generate a structured specification that can be used to plan a rebuild of the analyzed repository.

Supported prompt styles:

• terse
• standard
• exhaustive

The output can include project structure, architecture, features, technology choices, and implementation requirements derived from the analysis.

7. CLI Workflows

Use RepoPilot's command-line interface for repository analysis, scanning, rebuild-prompt generation, and issue-fixing workflows.

8. Local AI with Ollama

Run inference using a local Ollama service and a compatible model, avoiding mandatory cloud LLM API keys when using the local backend.

9. Configurable Inference Provider

The documented configuration supports selecting an inference backend through MODEL_BACKEND.

MODEL_BACKEND=ollama

The alternative backend can be configured as:

MODEL_BACKEND=nebius

Availability depends on the implementation and provider configuration. Selecting a cloud provider may require credentials and network access.

---

🗺️ Interactive Architecture Explorer

RepoPilot uses @xyflow/react for interactive architecture visualization.

flowchart LR
    R["Repository"] --> F["Frontend"]
    R --> B["Backend"]
    B --> API["API Routes"]
    B --> S["Services"]
    B --> DB["Database Layer"]
    S --> M["Models"]
    S --> AI["AI / Ollama"]
    API --> S

Loading

The diagram above is an illustrative example of the types of relationships RepoPilot can represent; actual nodes and edges should be generated from the repository being analyzed.

Explorer interaction model

Interaction	Purpose
Pan and zoom	Navigate large architecture graphs
Fit to view	Display the graph within the current viewport
Minimap	Navigate distant parts of the graph
Drag nodes	Rearrange the visible layout
Layer toggles	Show or hide selected component categories
Node inspection	Review files, dependencies, relationships, and responsibilities
Fullscreen mode	Explore the architecture on a larger canvas

---

🛠️ Live AI Issue Solver

RepoPilot includes an issue-resolution workflow that combines static findings, relevant code context, AI-generated suggestions, and verification instructions.

flowchart TD
    A["Static Finding"] --> B["Collect Relevant Code Context"]
    B --> C["Determine Probable Root Cause"]
    C --> D["Generate Proposed Patch"]
    D --> E["Validate Patch Format"]
    E --> F{"Patch Accepted?"}
    F -->|Yes| G["Review and Apply Patch"]
    F -->|No| H["Report Failure or Fallback"]
    G --> I["Run Relevant Tests and Checks"]
    I --> J["Report Verification Results"]

Loading

Issue solver capabilities

• Explain the probable root cause of a finding.
• Generate a proposed code replacement or unified diff.
• Provide instructions for locating and reviewing the affected code.
• Recommend validation commands based on detected project tooling.
• Identify potential side effects involving callers and dependencies.
• Use deterministic fallback behavior for supported cases when Ollama is unavailable.

Verification examples

Depending on the repository's technology stack, suggested checks may include:

npm test
npm run build

pytest -v

cargo test

Not every repository supports every command. RepoPilot should select checks based on detected manifests and tooling.

Safety principle: Treat generated patches as proposals until reviewed and verified. A successful patch application does not guarantee that the underlying issue is fixed or that no regressions were introduced.

---

🛠️ Technology Stack

The following technologies are described by the project.

Layer	Technology
Backend API	Python, FastAPI, Uvicorn
Frontend	React
Architecture visualization	@xyflow/react
Local AI inference	Ollama
Static analysis	AST-based inspection and custom static checks
Repository acquisition	Git
Backend testing	Pytest
Frontend validation	TypeScript compiler and production build
CLI	repopilot command-line interface
Optional inference provider	Nebius, when configured

Exact framework versions, language support, model names, and optional integrations should be verified against the repository's dependency manifests and configuration files.

---

📁 Repository Structure

RepoPilot/
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   └── ...
│   ├── tests/
│   ├── requirements.txt
│   └── ...
│
├── frontend/
│   ├── src/
│   ├── package.json
│   └── ...
│
├── repopilot-prompt.md
└── README.md

This is a representative overview based on the documented commands, not a guarantee of every file in the repository. Preserve the existing repository's actual directory structure when updating this section.

---

🚀 Getting Started

Prerequisites

Install the following tools:

• Python with a version compatible with backend/requirements.txt
• Node.js and npm
• Git
• Ollama
• A compatible local model
• Optional provider credentials if using a nonlocal inference backend

Verify the installed tools:

python --version
git --version
node --version
npm --version
ollama --version

1. Install and prepare Ollama

Install Ollama from:

https://ollama.com/

Pull the model configured for your RepoPilot installation.

ollama pull 3.5:3b

Model note: The documented model identifier is 3.5:3b. Confirm that this exact identifier exists in your Ollama environment and matches the model expected by the current code. If it is not a valid model identifier, use the model name supported by the implementation.

Ollama's default local API address is:

http://localhost:11434

RepoPilot is described as attempting to activate the local Ollama daemon during backend startup. Ensure Ollama is installed and available to the process running the backend.

2. Set up the backend

cd backend

python -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
pip install -r requirements.txt

Start the backend:

uvicorn app.main:app --reload --port 8000

Expected local API address:

http://localhost:8000

3. Set up the frontend

Open another terminal:

cd frontend
npm install
npm run dev

The frontend is documented as running at:

http://localhost:3000

If port 3000 is already occupied, use the URL shown by the frontend development server.

4. Open RepoPilot

Visit:

http://localhost:3000

Submit a supported repository URL and review the generated analysis.

5. Verify backend health

curl http://localhost:8000/api/health

Check Ollama availability:

curl http://localhost:8000/api/ollama/health

The exact JSON response depends on the current endpoint implementation.

---

⚙️ Configuration

RepoPilot documents support for switching inference backends using MODEL_BACKEND.

Variable	Purpose
MODEL_BACKEND	Selects the inference backend, such as ollama or nebius
Ollama base URL	Identifies the local Ollama API endpoint, if configurable
Model identifier	Selects the model expected by the inference implementation
Provider credentials	Used only when required by the selected nonlocal backend

Use the environment variable names and formats actually recognized by your installed version. The repository's environment template, if available, is the authoritative reference.

For local-only operation, select the Ollama backend and verify that analysis and issue-solving paths do not silently route data to a cloud provider.

---

📡 API Reference

Base URL for local development:

http://localhost:8000

Core endpoints

Method	Endpoint	Description
GET	/api/health	Service health status
GET	/api/ollama/health	Checks local Ollama availability
POST	/api/analyze	Starts repository analysis
GET	/api/analyze/{id}	Retrieves status, progress, and analysis results
GET	/api/analyze/{id}/stream	Streams live progress using Server-Sent Events
GET	/api/analyze/{id}/architecture	Retrieves architecture analysis and Mermaid diagram
GET	/api/analyze/{id}/architecture/graph	Retrieves structured graph nodes and edges
GET	/api/analyze/{id}/features	Retrieves detected repository features
GET	/api/analyze/{id}/security	Retrieves security findings with secrets redacted
GET	/api/analyze/{id}/quality	Retrieves code quality and maintainability findings
GET	/api/analyze/{id}/issues	Retrieves issues, syntax errors, and AST findings
POST	/api/analyze/solve-issue	Requests local AI-assisted issue resolution
GET	/api/analyze/{id}/recommendations	Retrieves actionable recommendations
POST	/api/repair/start	Starts autonomous 8-stage repair task
GET	/api/repair	Lists active and historical repair tasks
GET	/api/repair/{id}	Retrieves full task details, plan, validation report, and diff
GET	/api/repair/{id}/events	Real-time SSE stream of execution events
POST	/api/repair/{id}/approve	Approves patch and creates target git branch
POST	/api/repair/{id}/reject	Rejects patch and rolls back workspace
GET	/api/repair/{id}/export	Exports unified diff (format=diff or format=json)
GET	/api/provider/status	Reports active provider configuration (ollama or nebius)
GET	/api/nebius/health	Verifies Nebius Token Factory connection and model availability

Example: Start repository analysis

curl -X POST http://localhost:8000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/tiangolo/fastapi"
  }'

This example demonstrates the documented request shape. Use a repository you are authorized to analyze and follow the actual response schema of your installed version.

Example: Check Ollama health

curl http://localhost:8000/api/ollama/health

Live progress streaming

The analysis stream endpoint is:

GET /api/analyze/{id}/stream

It is documented as a Server-Sent Events (SSE) stream. The precise event names and payload structure should be taken from the current backend implementation.

API behavior

• Repository analysis may take time depending on repository size and model performance.
• Analysis endpoints may expose queued, running, completed, or failed states.
• Issue resolution depends on the available finding context, inference backend, and validation logic.
• Always validate endpoint inputs and protect sensitive output in production deployments.

---

💻 CLI Reference

RepoPilot v2 documents four principal CLI workflows.

The following commands assume that the repopilot CLI has been installed or registered in your environment.

1. Architecture Analyzer

Analyze a repository using one of three depth settings.

repopilot analyze <repo-url-or-path> --depth=summary

Available depths:

summary
standard
deep

Example:

repopilot analyze https://github.com/tiangolo/fastapi --depth=deep

The analyzer is intended to use repository documentation, manifests, entry points, AST structure, and dependency relationships to explain the codebase.

2. Prompt Generator

Generate a structured prompt for rebuilding the repository.

repopilot prompt <repo-url-or-path> --flavor=standard

Available flavors:

terse
standard
exhaustive

The documented workflow writes the prompt to standard output and ./repopilot-prompt.md.

Example:

repopilot prompt . --flavor=exhaustive

3. Live Code Fixer

Run the issue remediation workflow.

repopilot fix <repo-url-or-path>

Target a particular finding:

repopilot fix <repo-url-or-path> --finding=<id>

The described workflow collects findings, builds a minimal context bundle, generates a proposed unified diff, applies it using Git tooling, and verifies the result against scanner rules and available test runners.

Run this only in a disposable clone or a clean working tree. Review all changes before accepting them.

4. Repository Scanner

Scan a repository for structural and security findings.

repopilot scan <repo-url-or-path>

Example:

repopilot scan .

CLI summary

Command	Purpose
repopilot analyze	Explain the repository and its architecture
repopilot prompt	Generate a rebuild specification
repopilot fix	Propose, apply, and verify issue fixes
repopilot scan	Inspect files for supported findings
repopilot repair	Run autonomous 8-stage repair on a target repository bug
repopilot demo	Run deterministic seeded demo walkthrough with fixture reset

If a command is not recognized, check the repository's CLI installation instructions and available entry points. The commands above describe the project's documented interface; they should not be treated as proof that a CLI executable is already installed.

---

🧠 Inference Backends

RepoPilot documents two inference backend choices.

Local — Ollama

MODEL_BACKEND=ollama

Intended characteristics:

• Runs models through a local Ollama service.
• Avoids mandatory cloud LLM API keys for local inference.
• Supports analysis and code-generation workflows when the configured model is compatible.
• Depends on local model availability and hardware resources.

Local inference is not automatically equivalent to complete offline operation: Git cloning public repositories and installing dependencies may still require network access.

Optional — Nebius

MODEL_BACKEND=nebius

The documented provider configuration references nemotron-3-super. Verify the exact model identifier and supported provider configuration against the current implementation.

Using a hosted inference provider can require credentials, network connectivity, and transmission of submitted context to that provider.

---

🔐 Security and Execution Safety

RepoPilot inspects code from repositories, including code that may be untrusted. Security boundaries are therefore a core part of its design.

Documented security goals

• Validate repository inputs.
• Use shallow cloning for URL-based repository acquisition.
• Perform repository work in isolated temporary directories.
• Apply smart file filtering.
• Redact secrets from security findings.
• Report environment variable names without exposing .env.example values.
• Avoid requiring login or OAuth for the described local workflow.
• Use static analysis to identify selected risky code patterns.

Recommended operational safeguards

• Analyze untrusted repositories inside disposable, restricted workspaces.
• Avoid running repository scripts or build hooks unless explicitly required and reviewed.
• Use subprocess timeouts and resource limits.
• Restrict filesystem access and process privileges.
• Prevent repository input from controlling arbitrary shell commands.
• Never expose local secrets, private files, or environment values to model context.
• Review generated patches before applying them.
• Keep credentials out of logs and analysis responses.
• Avoid enabling automatic fixes on important working trees without backups.

Local-first does not mean risk-free. Cloning a repository, parsing malicious source, installing dependencies, or applying an AI-generated patch can introduce risks if execution boundaries are weak.

The security properties of the current implementation should be verified through code review and tests rather than inferred solely from the intended architecture.

---

🧪 Testing and Verification

Backend tests

From the backend directory:

cd backend
.venv/bin/pytest -v

Alternatively, after activating the virtual environment:

pytest -v

Frontend type checking

cd frontend
npx tsc --noEmit

Frontend production build

npm run build

Manual verification checklist

• Backend health endpoint responds.
• Ollama health endpoint reports availability correctly.
• Repository URLs are validated.
• Repository analysis produces structured results.
• Analysis progress updates are delivered through SSE.
• Architecture graphs contain repository-derived nodes and edges.
• Secret values are not exposed in reports.
• Static findings include useful file and line references when available.
• AI issue suggestions include validation instructions.
• Generated patches are checked before application.
• CLI commands handle invalid repositories and unavailable models gracefully.
• Backend tests pass.
• Frontend type checking and production build pass.

---

🗺️ Roadmap

Potential future improvements include:

• Broader multi-language AST support
• More precise cross-file dependency mapping
• Improved security rule coverage
• More robust secret scanning and redaction tests
• Better confidence indicators for AI-generated conclusions
• Architecture graph export and customization
• Expanded repository onboarding templates
• Patch review and approval workflows
• More comprehensive regression testing for autonomous fixes
• Improved analysis caching for repeated repository scans

This roadmap represents potential improvements, not a claim that these capabilities are already implemented.

---

🤝 Contributing

Contributions are welcome when they improve repository understanding, analysis quality, execution safety, or developer workflows.

1. Fork or clone the repository according to its access and licensing rules.
2. Create a focused feature branch.
3. Make a small, clearly scoped change.
4. Add or update tests.
5. Run backend tests and frontend checks where applicable.
6. Document changes to API endpoints, CLI commands, configuration, or analysis output.
7. Review security implications, especially for subprocess execution and automated patch application.
8. Submit a pull request for review.

Suggested contribution areas

• Language and framework detection
• AST analyzers and static checks
• Architecture extraction
• Dependency analysis
• RAG/context construction
• Local inference reliability
• CLI usability
• UI accessibility
• Security and regression tests

---

📄 License

Refer to the repository's actual LICENSE file for usage and redistribution terms.

Do not assume the project is open source or permissively licensed unless its published license explicitly grants those rights.

---

RepoPilot — Understand the Code. Map the Architecture. Fix the Issues.
_{Local-first repository intelligence for developers.}