The repo index that makes coding agents smart.
Repox scans any codebase and builds a persistent intelligence profile - 13 extraction dimensions covering everything from tech stack and architecture to auth flows, state machines, and security posture. Instead of starting from zero, your coding agent gets institutional knowledge so generated code fits the project like a senior wrote it.
| # | Dimension | What it captures |
|---|---|---|
| 1 | Tech Stack | Language, framework, package manager, test runner, dependencies |
| 2 | Architecture | Pattern detection (layered, DDD, MVC, hexagonal, flat, etc.) |
| 3 | Symbols | Full AST symbol graph - functions, classes, methods, constants |
| 4 | Dependencies | Import graph, call graph, PageRank-based file importance |
| 5 | API Surface | HTTP endpoints, MCP tools, Celery tasks, WebSocket events |
| 6 | Data Models | ORM entities, Pydantic models, Prisma schemas, field definitions |
| 7 | Design Patterns | Factory, Builder, Observer, Repository, Middleware, Strategy |
| 8 | Infrastructure | Docker services, env vars, deployment targets, external integrations |
| 9 | Conventions | Naming, error handling, async patterns, import style, type hints |
| 10 | Test Patterns | Framework, file naming, fixtures, mocking, assertion style |
| 11 | Hotspots | Churn-complexity analysis, temporal coupling, knowledge islands |
| 12 | Custom Rules | Team conventions from CLAUDE.md, .cursorrules, AGENTS.md, etc. |
| 13 | Behavioral | Auth flows, state machines, middleware chains, background jobs, API contracts |
Plus two cross-cutting layers:
- LLM Interpretation - architecture insights, convention synthesis, and pattern enrichment beyond what static analysis finds
- Security Posture - auth defaults, input validation, SQL safety, CORS, secret management, rate limiting
Requires Python 3.12+. Uses tree-sitter for language-independent AST parsing and LiteLLM for LLM features.
With uv (recommended):
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install repox as a global tool
uv tool install repoxai
# Update to latest version
uv tool upgrade repoxaiWith pip:
pip install repoxaiFor pip-based installation details, see https://pypi.org/project/repoxai/.
An LLM is needed for repox scan (interpretation layer) and repox context (advisory briefs). repox show works without one, but only provides static analysis results.
export ANTHROPIC_API_KEY=sk-... # or OPENAI_API_KEY or GEMINI_API_KEYScan a repository and build the intelligence profile.
repox scan /path/to/repo # incremental (skips unchanged files)
repox scan /path/to/repo --force # full rescan
repox scan # scan current directoryThis creates a .repox/ directory in the repo root with:
profile.json- full structured profile (all 13 dimensions)profile.md- human-readable summaryhashes.json- SHA-256 file hashes for incremental scanning
Display the full codebase profile. No LLM needed.
repox show # current directory
repox show /path/to/repo # specific repoReturns everything extracted - all 13 dimensions at full detail. When used with a coding agent, the agent's own LLM decides what's relevant.
Generate an LLM advisory brief for a specific task. Requires an LLM.
repox context "Fix the login bug in auth.py"
repox context "Add rate limiting" --target-files src/server.py
repox context "Refactor payments" --task-type refactor --target-files src/payments.py,src/billing.pyReturns a structured advisory with confidence-tagged sections (high/medium/low):
- Recommendation - what to do and the approach
- Files to Change - which files and why
- Dependencies Affected - what might break
- Risks & Side Effects - hotspots, knowledge islands, gotchas
- Testing Strategy - how to test, matching existing patterns
- Conventions to Follow - project-specific rules
The brief is advisory, not prescriptive - the host agent's LLM may be more capable and can override low-confidence recommendations.
Teach Repox project-specific conventions that get reinforced over time.
repox learn "Use tenacity for retries" --category error_handling
repox learn "Use tenacity for retries" --category error_handling # reinforces (confidence goes up)
repox learn "Always add type hints to public functions" --category typing --source review_patternShow active learned rules.
repox learned # all rules above 40% confidence
repox learned --min-confidence 0.6 # only high-confidence rules
repox learned --category error_handling # filter by categoryLearned rules are stored in profile.json and included in context briefs.
The simplest way to give any coding agent codebase intelligence. Add one of these to your agent's rules file (CLAUDE.md, .cursorrules, AGENTS.md):
Without LLM - agent gets the full profile and interprets it:
Before starting any task, run `repox show` to understand the codebase structure, conventions, and patterns. Use this context to write code that fits the project.
With LLM - agent gets a task-specific advisory brief:
Before starting any task, run `repox context "<description of what you're about to do>"` with relevant --target-files to get an advisory brief. Use the recommendations to guide your approach, but apply your own judgment - especially for low-confidence suggestions.
For MCP-compatible agents (Claude Code, Cursor, Windsurf), Repox exposes a single get_context tool:
{
"mcpServers": {
"repox": {
"command": "repox",
"args": ["serve"]
}
}
}get_context()- returns the full codebase profile (same asrepox show)get_context(task="...", target_files=["..."])- returns an LLM advisory brief (same asrepox context)
from repox import scan, generate_context, get_profile, serve
profile = scan("/path/to/repo")
context = generate_context(
"/path/to/repo",
task="Fix the login bug in auth.py",
task_type="bug_fix",
target_files=["src/auth.py"],
)
profile = get_profile("/path/to/repo")
serve("/path/to/repo")git clone https://github.com/kmandana/RepoX.git
cd RepoX
uv sync
uv run pytest
uv run repox scan .MIT