<p align="center">
  <h1 align="center">AiIndexer</h1>
  <p align="center">
    Local-first Graph-RAG context engine for AI coding agents
  </p>
</p>

<p align="center">
  <a href="#"><img alt="Version" src="https://img.shields.io/badge/version-0.1.0-blue.svg" /></a>
  <a href="COMMERCIAL-LICENSE.md"><img alt="License: Commercial" src="https://img.shields.io/badge/License-Commercial-black.svg" /></a>
  <a href="#"><img alt="Rust" src="https://img.shields.io/badge/rust-2021_edition-orange.svg" /></a>
  <a href="#"><img alt="MCP" src="https://img.shields.io/badge/MCP-2024--11--05-purple.svg" /></a>
</p>

---

## What is AiIndexer?

AiIndexer is a **local-first code intelligence engine** that gives AI coding agents (Codex, Claude Code, Cursor, Windsurf, VS Code, and Zed) precise, token-efficient context about your codebase. It parses your source code into an AST-based dependency graph, then uses **Graph-RAG** (Retrieval-Augmented Generation backed by a code graph) to deliver exactly the right context for any task.

Instead of dumping entire files into the LLM context window, AiIndexer delivers **context capsules** -- structured bundles containing full source for the most relevant symbols, compressed skeletons for adjacent code, and minimal signatures for supporting context.

### Token Reduction

| Tier | Content | Reduction |
|------|---------|-----------|
| Pivot | Full source of the most relevant symbols | 0% (full fidelity) |
| Adjacent | Standard skeleton (signatures + docstrings) | ~65% fewer tokens |
| Supporting | Minimal skeleton (signatures only) | ~74% fewer tokens |

A typical `context` call returns 4,000-8,000 tokens of precisely targeted context instead of 20,000-50,000 tokens of raw file contents.

## Quick Start

### Install

```bash
# macOS/Linux: install the signed public release
curl -fsSL https://aindex.floriansola.fr/install.sh | sh

# Windows PowerShell
irm https://aindex.floriansola.fr/install.ps1 | iex

# One-command project setup: config, index, native agents
cd /path/to/your/project
ai-indexer-mcp setup

# Activate a paid entitlement
ai-indexer-mcp license install YOUR_LICENSE_TOKEN
ai-indexer-mcp license status

# Preview or run the signed update flow
ai-indexer-mcp update --dry-run
ai-indexer-mcp update

# Build from source
git clone https://github.com/your-org/AiIndexer.git
cd AiIndexer
cargo build --release

# The MCP server binary is at:
# target/release/ai-indexer-mcp
```

The public installer and `ai-indexer-mcp update` both download a release archive, verify SHA-256 and Ed25519 signatures, and install the local binary without uploading repository source code. Windows installs use signed `.zip` archives; macOS and Linux use signed `.tar.gz` archives.

### Configure Projects and Agents Natively

Run one command from the project. It creates `.ai-indexer.toml`, indexes the repo, and writes native MCP config for Codex, Claude Code, Cursor, VS Code/Copilot, Windsurf, Zed, Continue, and OpenCode:

```bash
ai-indexer-mcp setup
```

From anywhere, pass the project path. Use `--no-agents` only when you want to index without touching editor or agent config:

```bash
ai-indexer-mcp setup --repo /path/to/your/project
ai-indexer-mcp setup --repo /path/to/your/project --no-agents
```

### Integrate Existing Documents Projects

From the AiIndexer source directory:

```bash
make install
make integrate-documents
```

This configures common projects under `~/Documents` (`monsite`, `matchr`, `SaleCast`, `poisson`, `MyRoadTrip`, etc.) with native agent MCP settings. To configure every first-level directory under `~/Documents` and pre-index them:

```bash
make integrate-documents-index
```

### First Run

The MCP server indexes your repository automatically on startup. Once connected, use `context` as your primary tool:

```
Task: "fix the login bug in the auth module"

Result:
  Intent: debug (auto-detected from "fix" + "bug")
  Pivots: auth::login(), auth::validate_token() (full source)
  Adjacent: user::UserService (skeleton)
  Supporting: db::query() (minimal)
  Impact: 12 affected symbols
```

## MCP Tools -- Router Pattern

AiIndexer exposes **5 consolidated tools** through the Model Context Protocol. Each tool is a smart router that dispatches internally to 30+ specialized handlers. This Router Pattern reduces schema overhead by 72% (from 3,597 tokens to ~1,011 tokens) while keeping all functionality accessible.

| Tool | Use When | Example |
|------|----------|---------|
| `context` | Starting any coding task | `context task="fix login bug"` |
| `search` | Finding code symbols or patterns | `search query="User" kind="class"` |
| `navigate` | Understanding structure and dependencies | `navigate action="deps" symbol="Auth"` |
| `remember` | Saving or recalling insights | `remember action="save" content="Auth uses JWT"` |
| `status` | Checking index health | `status detail="full"` |

### `context` -- The Primary Tool

`context` is the main entry point. It auto-detects intent from your task description and returns the right code context:

```
context task="fix the email validation"        # auto-detects relevant files
context task="fix login" files=["src/auth.ts"] # you specify the file
context task="fix login" mode="skeleton"       # exploration only (compressed)
context task="fix login" strategy="tokens"     # Pro+: compact delta context
context task="Error at src/auth.ts:42"         # auto-switches to debug mode
```

The `mode` parameter controls detail level:
- **smart** (default): full source for small files, skeleton + key functions for large files
- **full**: complete source, no compression -- use when editing
- **skeleton**: signatures only -- use when exploring

The default retrieval strategy is **impact**: maximize useful agent context with evidence, graph signals, related tests, and blast-radius hints. Pro+ users can explicitly request `strategy="tokens"` for compact delta context or `strategy="speed"` for faster exploration.

### `search` -- Find Code Fast

```
search query="User"                            # by name
search query="User" kind="class"               # by name + type
search query="exported functions returning Promise"  # pattern query (auto-detected)
```

### `navigate` -- Understand Structure

```
navigate action="deps" symbol="createUser"     # what depends on it / what it uses
navigate action="trace" from="handleRequest" to="dbQuery"  # call chain A->B
navigate action="architecture"                 # module overview, cycles, hot spots
navigate action="dead-code"                    # unused functions
navigate action="impact" symbol="User"         # blast radius of changes
navigate action="duplicates"                   # duplicate/similar functions
navigate action="rules"                        # improve .ai-indexer.toml
```

### `remember` -- Cross-Session Memory

```
remember action="save" content="Auth module uses JWT tokens"
remember action="search" content="auth"
remember action="history"
```

### `status` -- Index Health

```
status                   # quick status
status detail="full"     # detailed stats with PageRank, dead code count, language breakdown
```

See [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) for complete documentation with examples.

## Architecture

```
                        AI Agent (Codex / Claude Code / Cursor / Windsurf)
                                        |
                                   MCP Protocol
                                   (JSON-RPC/stdio)
                                        |
                              +-------------------+
                              |  ai-indexer-mcp   |
                              |  (5 Router Tools) |
                              +--------+----------+
                                       |
                          Smart Routing Layer
                    (intent detection, action dispatch)
                                       |
            +-----------+-----------+--+--+-----------+-----------+
            |           |           |     |           |           |
     +------+--+  +-----+---+  +---+---+ +---+----+ +---+----+ +--+------+
     | parser  |  |  store   |  | graph | | index  | | search | | memory  |
     | (AST)   |  | (SQLite) |  |(petgr)| |(crawl) | | (RAG)  | |(session)|
     +---------+  +----------+  +-------+ +--------+ +--------+ +---------+
```

### Router Pattern

Instead of exposing 30+ individual MCP tools (which causes agent confusion and wastes schema tokens), AiIndexer uses 5 consolidated router tools. Each tool acts as a smart dispatcher:

- **`context`** routes to: pipeline, capsule, skeleton, debug context, review context
- **`search`** routes to: FTS5 search, TF-IDF search, pattern search, symbol lookup
- **`navigate`** routes to: dependency graph, call trace, architecture overview, dead-code detection, impact analysis, duplicate detection, rules improvement
- **`remember`** routes to: save observation, search memory, session history
- **`status`** routes to: brief status, full statistics

This keeps the agent's tool selection simple (5 clear choices) while preserving all 30+ specialized capabilities internally.

### Crate Overview

| Crate | Purpose |
|-------|---------|
| `ai-indexer-core` | Shared types, config, language definitions |
| `ai-indexer-parser` | Tree-sitter AST parsing, skeletonization |
| `ai-indexer-store` | SQLite database (WAL mode), FTS5 search |
| `ai-indexer-graph` | In-memory petgraph, PageRank, impact analysis |
| `ai-indexer-index` | File crawling, incremental indexing, BLAKE3 hashing |
| `ai-indexer-search` | Hybrid search pipeline, intent detection, capsule assembly |
| `ai-indexer-memory` | Session management, observations, memory recall |
| `ai-indexer-mcp` | MCP server binary, 5 router tools, JSON-RPC transport |

## Supported Languages

16 languages, each with full symbol **and** call-graph extraction (definitions, references, callers/callees), verified by a per-language regression test.

| Language | Extensions | AST Parser |
|----------|-----------|------------|
| TypeScript | `.ts`, `.tsx` | tree-sitter-typescript |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | tree-sitter-typescript |
| Python | `.py`, `.pyi` | tree-sitter-python |
| Rust | `.rs` | tree-sitter-rust |
| Go | `.go` | tree-sitter-go |
| Java | `.java` | tree-sitter-java |
| C | `.c`, `.h` | tree-sitter-c |
| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx` | tree-sitter-cpp |
| C# | `.cs` | tree-sitter-c-sharp |
| Ruby | `.rb` | tree-sitter-ruby |
| Bash | `.sh`, `.bash` | tree-sitter-bash |
| PHP | `.php` | tree-sitter-php |
| Lua | `.lua` | tree-sitter-lua |
| Scala | `.scala`, `.sc` | tree-sitter-scala |
| Kotlin | `.kt`, `.kts` | tree-sitter-kotlin-ng |
| Swift | `.swift` | tree-sitter-swift |

## Configuration

AiIndexer works with zero configuration. For customization, see [docs/CONFIGURATION.md](docs/CONFIGURATION.md).

Key defaults:

| Option | Default | Description |
|--------|---------|-------------|
| `max_context_tokens` | 8000 | Requested local default before plan caps are applied |
| `skeleton_detail` | standard | Default skeleton level |
| `data_dir` | `.ai-indexer/` | Index storage location |
| `filter_secrets` | true | Skip `.env`, private keys, PEM/key files, and credential files while allowing templates like `.env.example` |
| `priority_paths` | `[]` | Boost retrieval for important source areas |
| `depriority_paths` | `[]` | Demote generated/vendor/test-fixture areas |
| `[retrieval].strategy_default` | `impact` | Default agent strategy: impact, tokens, or speed |
| `[performance].wal_checkpoint` | `auto` | Run lightweight SQLite maintenance after bulk indexing |

AiIndexer also reads `.ai-indexerignore`, `.aiindexerignore`, `.vexpignore`, and `.vexp_ignore` alongside `.gitignore` / `.ignore` style walker rules.

## VS Code Extension

AiIndexer includes a VS Code extension that provides:

- **Sidebar panel** with index status, repository list, and quick actions
- **CodeLens annotations** showing dependency counts above functions/classes
- **Commands** for searching, skeletonizing, and visualizing dependency graphs
- **Auto-indexing** on workspace open and file save (debounced)

See [docs/VSCODE_EXTENSION.md](docs/VSCODE_EXTENSION.md) for full details.

## CLI Usage

The MCP server binary can also be used directly for debugging:

```bash
# Start MCP server for current directory
ai-indexer-mcp

# Start MCP server for a specific repo
ai-indexer-mcp --repo /path/to/project
```

The server communicates via JSON-RPC over stdio, following the MCP 2024-11-05 protocol specification.

## Performance

Measured on a mid-range laptop (Apple M2, 16GB RAM):

| Metric | Value |
|--------|-------|
| Initial index (10k files) | ~8 seconds |
| Incremental reindex (1 changed file) | ~50ms |
| `context` query | ~15ms |
| `search` query | ~5ms |
| `navigate action="deps"` | ~3ms |
| PageRank computation (5k nodes) | ~10ms |
| Memory footprint (10k nodes) | ~25MB |

## Documentation

| Document | Description |
|----------|-------------|
| [Architecture](docs/ARCHITECTURE.md) | System design, data flow, Router Pattern |
| [MCP Tools](docs/MCP_TOOLS.md) | Complete 5-tool reference with examples |
| [Configuration](docs/CONFIGURATION.md) | All config options and tuning |
| [Skeleton Guide](docs/SKELETON_GUIDE.md) | Skeletonization explained |
| [VS Code Extension](docs/VSCODE_EXTENSION.md) | Extension features and setup |
| [Development](docs/DEVELOPMENT.md) | Building, testing, contributing |
| [Installation](docs/INSTALLATION.md) | Public install, manual install, activation, support packet |
| [Licensing](docs/LICENSING.md) | Entitlement payload, plan gates, offline enterprise path |
| [Releases](docs/RELEASES.md) | Versioning, release artifacts, checksums, rollback |
| [Benchmarks](docs/BENCHMARKS.md) | Repeatable benchmark metadata and commands |
| [Support](docs/SUPPORT.md) | Support tiers, intake template, triage |
| [Billing Model](commercial/BILLING_MODEL.md) | Recommended pricing, plans, provider choice, and entitlement roadmap |
| [Selling Checklist](commercial/SELLING_CHECKLIST.md) | Product, billing, website, and sales tasks for first customers |
| [Stripe Setup](commercial/STRIPE_SETUP.md) | Stripe products, prices, payment links, and webhook setup |
| [Production Readiness](commercial/PRODUCTION_READINESS.md) | Launch gate for site, billing, licensing, legal, and support |
| [Launch Playbook](commercial/LAUNCH_PLAYBOOK.md) | Private beta, public checkout, team sales phases |
| [Publishing Plan](commercial/PUBLISHING_PLAN.md) | Name, channels, launch assets, message |
| [Marketing Plan](commercial/MARKETING_PLAN.md) | Buyer, pain, offer, ads |

## Commercialization

AiIndexer is being prepared as a paid local-first developer tool. The recommended
launch model is:

- **Free**: 1 local repository, 8k indexed symbols, 4k-token responses, personal evaluation only
- **Advanced**: €4.99/month or €49/year for 3 local repositories, 100k symbols, 16k-token responses, and local memory
- **Pro**: €9.99/month or €99/year per developer for unlimited local repositories, 32k-token responses, commercial solo use, navigation, audits, and batch tools
- **Team**: €49/seat/month or €490/seat/year with shared rollout workflows and 64k-token responses
- **Enterprise**: starts at €6,000/year with offline licensing, security review support, and 200k-token responses
- **Launch lifetime**: limited €99 early-adopter solo license mapped to Pro entitlement

The production website lives in [web/](web): Next.js 16 + next-intl, with
marketing pages, pricing, downloads, docs, login/register, account, dashboard,
admin, sitemap, robots, and manifest.

The old static HTML project is archived under
[_archive/static-site-20260606/](./_archive/static-site-20260606). Do not edit it.

[deploy-site/](deploy-site) is not the website. It is only the public release
artifact bucket served by Caddy for `/install.sh`, `/install.ps1`, `/releases/*`,
`/homebrew/*`, `/security/*`, and `/assets/release.json`.

Deploy model:

- `aindex-billing` serves billing/license/admin API on `127.0.0.1:4310`.
- `aindex-web` serves the Next.js website on `127.0.0.1:4311`.
- Caddy serves release artifacts from `/srv/aindex/site` and proxies all other
  website routes to Next.js.

Stripe setup:

```bash
cp .env.example .env
node scripts/sync-stripe-plans.mjs --dry-run
node scripts/sync-stripe-plans.mjs
node scripts/sync-stripe-plans.mjs --verify
node scripts/generate-license-keypair.mjs
npm run billing:start
```

Launch checks:

```bash
npm run web:check
npm run web:build
node scripts/sync-stripe-plans.mjs --dry-run
node scripts/create-stripe-webhook-endpoint.mjs --dry-run
node scripts/doctor.mjs
node scripts/site-inventory.mjs --write
```

After live Stripe and Resend secrets are configured:

```bash
node scripts/prod-audit.mjs
```

Release build:

```bash
npm run release:build
node scripts/generate-checksums.mjs dist
node scripts/sign-release.mjs dist
node scripts/package-vscode-extension.mjs
```

Customers activate paid access with:

```bash
ai-indexer-mcp license install <token>
ai-indexer-mcp license status
ai-indexer-mcp license status --online
```

For Pro and Team subscriptions, `license install` verifies the signed token,
activates the current machine against `https://aindex.floriansola.fr/license/activate`,
and reserves one seat before writing the token locally. `license status --online`
checks the hosted license status and active seat usage without consuming another
seat. Offline Enterprise tokens can be installed without the hosted activation
check:

```bash
ai-indexer-mcp license install <token> --local-only
```

To release a Team seat from a machine:

```bash
ai-indexer-mcp license remove
```

The command deactivates the machine online before deleting the local token.
Use `--force` only for local removal when the hosted service is unreachable.

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feat/my-feature`
3. Make your changes with tests
4. Run the test suite: `cargo test --workspace`
5. Submit a pull request

Please follow the existing code style: Rust 2021 edition, `thiserror` for library errors, `anyhow` for application errors, `tracing` for logging.

## License

Commercial license draft. See [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md).
The draft should be reviewed by counsel before public paid launch.
