Metadata-Version: 2.4
Name: repoxai
Version: 0.1.0a1
Summary: The repo index that makes coding agents smart
Project-URL: Homepage, https://github.com/kmandana/RepoX
Project-URL: Documentation, https://github.com/kmandana/RepoX#readme
Project-URL: Issues, https://github.com/kmandana/RepoX/issues
Project-URL: Changelog, https://github.com/kmandana/RepoX/releases
Author: K Man
Maintainer: K Man
License: MIT
License-File: LICENSE
Keywords: ast,codebase,coding-agent,developer-tools,intelligence,mcp,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: click>=8.0
Requires-Dist: litellm>=1.0
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tree-sitter-language-pack>=0.7
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install repoxai
```

Requires Python 3.12+. Uses [tree-sitter](https://tree-sitter.github.io/) for language-independent AST parsing and [LiteLLM](https://docs.litellm.ai/) 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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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:

```json
{
  "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

```python
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

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

## License

MIT
