repoxai 0.1.0a1

The repo index that makes coding agents smart

Repox

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.

What It Extracts

#	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

---

How to Use

1. Install

pip install repoxai

Requires Python 3.12+. Uses tree-sitter for language-independent AST parsing and LiteLLM for LLM features.

2. Configure LLM

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_KEY

3. Commands

repox scan

Scan 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 directory

This creates a .repox/ directory in the repo root with:

• profile.json - full structured profile (all 13 dimensions)
• profile.md - human-readable summary
• hashes.json - SHA-256 file hashes for incremental scanning

repox show

Display the full codebase profile. No LLM needed.

repox show                # current directory
repox show /path/to/repo  # specific repo

Returns everything extracted - all 13 dimensions at full detail. When used with a coding agent, the agent's own LLM decides what's relevant.

repox context

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.py

Returns 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.

repox learn

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_pattern

repox learned

Show 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 category

Learned rules are stored in profile.json and included in context briefs.

4. Agent Integration

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.

5. MCP Server (optional)

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 as repox show)
• get_context(task="...", target_files=["..."]) - returns an LLM advisory brief (same as repox context)

6. Python API

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")

---

Development

git clone https://github.com/kmandana/RepoX.git
cd RepoX
uv sync
uv run pytest
uv run repox scan .

License

MIT