# Repotoire 🎼
**Graph-Powered Code Intelligence — Local-First, Blazing Fast**
Repotoire builds a knowledge graph of your codebase to detect architectural issues, code smells, and security vulnerabilities that traditional linters miss.
[](https://pypi.org/project/repotoire/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## Why Repotoire?
Most linters analyze files in isolation. Repotoire sees the **whole picture**:
```
Traditional Linters Repotoire
───────────────────── ─────────────────────
file1.py ✓ file1.py ──┐
file2.py ✓ file2.py ──┼── Knowledge Graph
file3.py ✓ file3.py ──┘
│
Circular deps?
God classes?
Dead code?
Coupling hotspots?
```
## Quick Start
### Option 1: Download Binary (Easiest)
```bash
# Linux
curl -L https://github.com/Zach-hammad/repotoire/releases/latest/download/repotoire-linux-x86_64.tar.gz | tar xz
sudo mv repotoire /usr/local/bin/
# macOS (Apple Silicon)
# macOS (Intel)
curl -L https://github.com/Zach-hammad/repotoire/releases/latest/download/repotoire-macos-x86_64.tar.gz | tar xz
sudo mv repotoire /usr/local/bin/
```
### Option 2: Cargo Binstall (No cmake needed)
```bash
cargo binstall repotoire
```
### Option 3: Cargo Install
```bash
# Requires cmake (see Build Dependencies below)
cargo install repotoire
```
### Option 3: pip
```bash
pip install repotoire
```
That's it. No API keys required. No Docker. No cloud account.
> **Upgrading from Python version?** Delete the old database first: `rm -rf .repotoire`
### Build Dependencies (for cargo install)
Building from source requires **cmake**:
```bash
# macOS
brew install cmake
# Ubuntu/Debian
sudo apt install cmake build-essential
# Fedora
sudo dnf install cmake gcc-c++
# Windows
winget install cmake
```
## ⚡ Performance
Rust-accelerated parsing. 3,000 files in under a minute.
| Django | 3,000 | 55s | 54 files/sec |
| Express.js | 141 | 0.02s | 7,500 files/sec |
| Medium project | 500 | ~10s | 50 files/sec |
Progress bars show you what's happening:
```
Processing files... ████████████░░░░ 75% (375/500) 0:00:08
```
## What It Finds
**47 detectors** across 4 categories:
### 🏗️ Architecture
- Circular dependencies (Tarjan's SCC algorithm)
- Architectural bottlenecks (betweenness centrality)
- Hub dependencies (fragile central nodes)
- Module cohesion problems
### 🔍 Code Smells
- God classes (too many responsibilities)
- Dead code (unreachable functions/classes)
- Feature envy (methods using wrong class data)
- Shotgun surgery (changes ripple everywhere)
- AI-generated code patterns (complexity spikes, churn, naming)
### 🔒 Security
- SQL injection patterns
- Hardcoded secrets (API keys, passwords)
- Unsafe deserialization (pickle, yaml.load)
- Eval/exec with user input
- GitHub Actions injection
### 📊 Quality
- Complexity hotspots
- Type hint coverage gaps
- Duplicate code blocks
- Missing tests for new functions
## Sample Output
```
╔════════════════════ 🎼 Repotoire Health Report ════════════════════╗
║ Grade: B ║
║ Score: 82.5/100 ║
║ Good - Minor improvements recommended ║
╚════════════════════════════════════════════════════════════════════╝
┌─────────────────────┬────────┬───────────┐
│ Category │ Weight │ Score │
├─────────────────────┼────────┼───────────┤
│ Graph Structure │ 40% │ 85.0/100 │
│ Code Quality │ 30% │ 78.3/100 │
│ Architecture Health │ 30% │ 84.2/100 │
└─────────────────────┴────────┴───────────┘
🔍 Findings (23 total)
┌─────────────┬───────┐
│ 🔴 Critical │ 2 │
│ 🟠 High │ 5 │
│ 🟡 Medium │ 12 │
│ 🔵 Low │ 4 │
└─────────────┴───────┘
```
## Supported Languages
| Python | ✅ | ✅ | ✅ | ✅ |
| TypeScript | ✅ | ✅ | ✅ | ✅ |
| JavaScript | ✅ | ✅ | ✅ | ✅ |
| Go | ✅ | ✅ | ✅ | ✅ |
| Java | ✅ | ✅ | ✅ | ✅ |
| Rust | ✅ | ✅ | ✅ | ✅ |
| C/C++ | ✅ | ✅ | ✅ | ✅ |
| C# | ✅ | ✅ | ✅ | ✅ |
| Kotlin | ✅ | ✅ | ✅ | ✅ |
All languages use tree-sitter for parsing, compiled to native code via Rust.
## CLI Reference
```bash
# Analysis
repotoire analyze . # Full analysis
repotoire analyze . --offline # Skip cloud sync
repotoire analyze . --output report.json
repotoire analyze . --format html
# Graph operations
repotoire ingest . # Build graph only
repotoire ask "what calls UserService" # Natural language queries
# Utilities
repotoire doctor # Check your setup
repotoire version # Show version info
```
### Doctor Output
```
$ repotoire doctor
Repotoire Doctor
✓ Python version: 3.12.0
✓ Rust extension: Loaded
✓ Disk space (home): 150.2GB free (35% used)
```
## AI-Powered Fixes (Optional)
Bring your own API key for AI-assisted fixes:
```bash
# Pick any provider (in order of recommendation):
export ANTHROPIC_API_KEY=sk-ant-... # Claude (best quality)
export OPENAI_API_KEY=sk-... # GPT-4
export DEEPINFRA_API_KEY=... # Llama 3.3 (cheapest!)
export OPENROUTER_API_KEY=... # Any model
repotoire fix 1 # Fix finding #1
```
**Get your key:**
- Anthropic: https://console.anthropic.com/settings/keys
- OpenAI: https://platform.openai.com/api-keys
- Deepinfra: https://deepinfra.com/dash/api_keys (💰 cheapest)
- OpenRouter: https://openrouter.ai/keys
No API key? No problem. All analysis works offline.
## Configuration
Create `.repotoirerc` or `repotoire.toml`:
```toml
[analysis]
patterns = ["**/*.py", "**/*.ts", "**/*.go", "**/*.java", "**/*.rs", "**/*.c", "**/*.cpp", "**/*.cs", "**/*.kt"]
exclude = ["**/node_modules/**", "**/venv/**", "**/target/**", "**/bin/**", "**/obj/**"]
[detectors.god_class]
threshold_methods = 20
threshold_lines = 500
[detectors.circular_dependency]
enabled = true
```
## How It Works
```
┌──────────┐ ┌───────────────┐ ┌──────────────┐ ┌──────────┐
│ Source │───▶│ Rust Parser │───▶│ Kuzu Graph │───▶│ Detectors│
│ Files │ │ (tree-sitter) │ │ (embedded) │ │ (47) │
└──────────┘ └───────────────┘ └──────────────┘ └──────────┘
│ │
│ 6 languages │ Graph algorithms:
│ Parallel parsing │ • Tarjan's SCC
│ ~7,500 files/sec │ • Betweenness centrality
│ │ • Community detection
│ ▼
│ ┌──────────────┐
└──────────────────────────────▶│ Reports │
│ CLI/HTML/JSON│
└──────────────┘
```
**Key components:**
- **Tree-sitter** — Fast, accurate parsing for all languages
- **Kuzu** — Embedded graph database (no external deps)
- **Rust extension** — Native speed for parsing + graph algorithms
## CI/CD Integration
### GitHub Actions
```yaml
- name: Code Health Check
run: |
pip install repotoire
repotoire analyze . --output report.json
- name: Fail on critical issues
run: |
CRITICAL=$(jq '.findings | map(select(.severity == "critical")) | length' report.json)
if [ "$CRITICAL" -gt 0 ]; then exit 1; fi
```
### Pre-commit Hook
```yaml
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: repotoire
name: repotoire
entry: repotoire analyze . --offline
language: system
pass_filenames: false
```
## Comparison
| Local-first | ✅ | ❌ | ❌ |
| No Docker | ✅ | ❌ | ✅ |
| Graph analysis | ✅ | Partial | ❌ |
| Multi-language | 6 | Many | Many |
| Circular deps | ✅ | ✅ | ❌ |
| Dead code | ✅ | ✅ | ✅ |
| AI code smell detection | ✅ | ❌ | ❌ |
| BYOK AI fixes | ✅ | ❌ | ❌ |
| Free | ✅ | Limited | Limited |
## Troubleshooting
### "Cannot open file .repotoire/kuzu_db/.lock: Not a directory"
You have a stale database from a previous version. Delete it:
```bash
rm -rf .repotoire
repotoire analyze .
```
### "cmake not installed" during cargo install
Install cmake first:
```bash
# macOS
brew install cmake
# Ubuntu/Debian
sudo apt install cmake build-essential
# Or use cargo binstall (no cmake needed)
cargo binstall repotoire
```
### Analysis is slow
Use `--relaxed` for faster runs (only high-severity findings):
```bash
repotoire analyze . --relaxed
```
## Documentation
- **[Schema Reference](docs/SCHEMA.md)** — Graph node/edge types and Cypher examples
- **[Detectors](docs/DETECTORS.md)** — Full list of 47 detectors with configuration
## Contributing
```bash
git clone https://github.com/Zach-hammad/repotoire
cd repotoire
pip install -e ".[dev]"
pytest
```
The Rust extension builds automatically on first install.
## License
MIT — see [LICENSE](LICENSE)
---
**[Get started →](https://pypi.org/project/repotoire/)**
```bash
pip install repotoire && repotoire analyze .
```