# AiDex
[](https://www.npmjs.com/package/aidex-mcp)
[](LICENSE)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
**Stop wasting 80% of your AI's context window on code searches.**
AiDex is an MCP server that gives AI coding assistants instant access to your entire codebase through a persistent, pre-built index. Works with any MCP-compatible AI assistant: Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot, and more.
<details>
<summary>Animated version</summary>
</details>
## The Problem
Every time your AI assistant searches for code, it:
- **Greps** through thousands of files → hundreds of results flood the context
- **Reads** file after file to understand the structure → more context consumed
- **Forgets** everything when the session ends → repeat from scratch
A single "Where is X defined?" question can eat 2,000+ tokens. Do that 10 times and you've burned half your context on navigation alone.
## The Solution
Index once, query forever:
```
# Before: grep flooding your context
AI: grep "PlayerHealth" → 200 hits in 40 files
AI: read File1.cs, File2.cs, File3.cs...
→ 2000+ tokens consumed, 5+ tool calls
# After: precise results, minimal context
AI: aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156
→ ~50 tokens, 1 tool call
```
**Result: 50-80% less context used for code navigation.**
## Why Not Just Grep?
| | Grep/Ripgrep | AiDex |
|---|---|---|
| **Context usage** | 2000+ tokens per search | ~50 tokens |
| **Results** | All text matches | Only identifiers |
| **Precision** | `log` matches `catalog`, `logarithm` | `log` finds only `log` |
| **Persistence** | Starts fresh every time | Index survives sessions |
| **Structure** | Flat text search | Knows methods, classes, types |
**The real cost of grep**: Every grep result includes surrounding context. Search for `User` in a large project and you'll get hundreds of hits - comments, strings, partial matches. Your AI reads through all of them, burning context tokens on noise.
**AiDex indexes identifiers**: It uses Tree-sitter to actually parse your code. When you search for `User`, you get the class definition, the method parameters, the variable declarations - not every comment that mentions "user".
## How It Works
1. **Index your project once** (~1 second per 1000 files)
```
aidex_init({ path: "/path/to/project" })
```
2. **AI searches the index instead of grepping**
```
aidex_query({ term: "Calculate", mode: "starts_with" })
→ All functions starting with "Calculate" + exact line numbers
aidex_query({ term: "Player", modified_since: "2h" })
→ Only matches changed in the last 2 hours
```
3. **Get file overviews without reading entire files**
```
aidex_signature({ file: "src/Engine.cs" })
→ All classes, methods, and their signatures
```
The index lives in `.aidex/index.db` (SQLite) - fast, portable, no external dependencies.
## Features
- **Screenshots**: Cross-platform screenshot capture (fullscreen, window, region) with auto-path for instant AI viewing
- **Smart Extraction**: Uses Tree-sitter to parse code properly - indexes identifiers, not keywords
- **Method Signatures**: Get function prototypes without reading implementations
- **Project Summary**: Auto-detected entry points, main classes, language breakdown
- **Incremental Updates**: Re-index single files after changes
- **Cross-Project Links**: Query across multiple related projects
- **Time-based Filtering**: Find what changed in the last hour, day, or week
- **Project Structure**: Query all files (code, config, docs, assets) without filesystem access
- **Session Notes**: Leave reminders for the next session - persists in the database
- **Task Backlog**: Built-in task management that lives with your code index - no external tools needed
- **Auto-Cleanup**: Excluded files (e.g., build outputs) are automatically removed from index
## Supported Languages
| Language | Extensions |
|----------|------------|
| C# | `.cs` |
| TypeScript | `.ts`, `.tsx` |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |
| Rust | `.rs` |
| Python | `.py`, `.pyw` |
| C | `.c`, `.h` |
| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx` |
| Java | `.java` |
| Go | `.go` |
| PHP | `.php` |
| Ruby | `.rb`, `.rake` |
## Quick Start
### 1. Install & Register
```bash
npm install -g aidex-mcp
aidex setup
```
`aidex setup` automatically detects and registers AiDex with your installed AI clients (Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot). To unregister: `aidex unsetup`.
### 2. Or register manually with your AI assistant
**For Claude Code** (`~/.claude/settings.json` or `~/.claude.json`):
```json
{
"mcpServers": {
"aidex": {
"type": "stdio",
"command": "aidex",
"env": {}
}
}
}
```
**For Claude Desktop** (`%APPDATA%/Claude/claude_desktop_config.json` on Windows):
```json
{
"mcpServers": {
"aidex": {
"command": "aidex"
}
}
}
```
> **Note:** Both `aidex` and `aidex-mcp` work as command names.
> **Important:** The server name in your config determines the MCP tool prefix. Use `"aidex"` as shown above — this gives you tool names like `aidex_query`, `aidex_signature`, etc. Using a different name (e.g., `"codegraph"`) would change the prefix accordingly.
**For Gemini CLI** (`~/.gemini/settings.json`):
```json
{
"mcpServers": {
"aidex": {
"command": "aidex"
}
}
}
```
**For VS Code Copilot** (run `MCP: Open User Configuration` in Command Palette):
```json
{
"servers": {
"aidex": {
"type": "stdio",
"command": "aidex"
}
}
}
```
**For other MCP clients**: See your client's documentation for MCP server configuration.
### 3. Make your AI actually use it
Add to your AI's instructions (e.g., `~/.claude/CLAUDE.md` for Claude Code):
```markdown
## AiDex - Use for ALL code searches!
**Before using Grep/Glob, check if `.aidex/` exists in the project.**
If yes, use AiDex instead:
- `aidex_query` - Find functions, classes, variables by name
- `aidex_signature` - Get all methods in a file with line numbers
- `aidex_signatures` - Get methods from multiple files (glob pattern)
- `aidex_summary` - Project overview with entry points
If no `.aidex/` exists, offer to run `aidex_init` first.
```
### 4. Index your project
Ask your AI: *"Index this project with AiDex"*
Or manually in the AI chat:
```
aidex_init({ path: "/path/to/your/project" })
```
## Available Tools
| Tool | Description |
|------|-------------|
| `aidex_init` | Index a project (creates `.aidex/`) |
| `aidex_query` | Search by term (exact/contains/starts_with) |
| `aidex_signature` | Get one file's classes + methods |
| `aidex_signatures` | Get signatures for multiple files (glob) |
| `aidex_update` | Re-index a single changed file |
| `aidex_remove` | Remove a deleted file from index |
| `aidex_summary` | Project overview |
| `aidex_tree` | File tree with statistics |
| `aidex_describe` | Add documentation to summary |
| `aidex_link` | Link another indexed project |
| `aidex_unlink` | Remove linked project |
| `aidex_links` | List linked projects |
| `aidex_status` | Index statistics |
| `aidex_scan` | Find indexed projects in directory tree |
| `aidex_files` | List project files by type (code/config/doc/asset) |
| `aidex_note` | Read/write session notes (persists between sessions) |
| `aidex_session` | Start session, detect external changes, auto-reindex |
| `aidex_viewer` | Open interactive project tree in browser |
| `aidex_task` | Create, read, update, delete tasks with priority and tags |
| `aidex_tasks` | List and filter tasks by status, priority, or tag |
| `aidex_screenshot` | Take a screenshot (fullscreen, window, region) |
| `aidex_windows` | List open windows for screenshot targeting |
## Time-based Filtering
Track what changed recently with `modified_since` and `modified_before`:
```
aidex_query({ term: "render", modified_since: "2h" }) # Last 2 hours
aidex_query({ term: "User", modified_since: "1d" }) # Last day
aidex_query({ term: "API", modified_since: "1w" }) # Last week
```
Supported formats:
- **Relative**: `30m` (minutes), `2h` (hours), `1d` (days), `1w` (weeks)
- **ISO date**: `2026-01-27` or `2026-01-27T14:30:00`
Perfect for questions like *"What did I change in the last hour?"*
## Project Structure
AiDex indexes ALL files in your project (not just code), letting you query the structure:
```
aidex_files({ path: ".", type: "config" }) # All config files
aidex_files({ path: ".", type: "test" }) # All test files
aidex_files({ path: ".", pattern: "**/*.md" }) # All markdown files
aidex_files({ path: ".", modified_since: "30m" }) # Changed this session
```
File types: `code`, `config`, `doc`, `asset`, `test`, `other`, `dir`
Use `modified_since` to find files changed in this session - perfect for *"What did I edit?"*
## Session Notes
Leave reminders for the next session - no more losing context between chats:
```
aidex_note({ path: ".", note: "Test the glob fix after restart" }) # Write
aidex_note({ path: ".", note: "Also check edge cases", append: true }) # Append
aidex_note({ path: "." }) # Read
aidex_note({ path: ".", clear: true }) # Clear
```
**Use cases:**
- Before ending a session: *"Remember to test X next time"*
- AI auto-reminder: Save what to verify after a restart
- Handover notes: Context for the next session without editing config files
Notes are stored in the SQLite database (`.aidex/index.db`) and persist indefinitely.
## Task Backlog
Keep your project tasks right next to your code index - no Jira, no Trello, no context switching:
```
aidex_task({ path: ".", action: "create", title: "Fix parser bug", priority: 1, tags: "bug" })
aidex_task({ path: ".", action: "update", id: 1, status: "done" })
aidex_task({ path: ".", action: "log", id: 1, note: "Root cause: unbounded buffer" })
aidex_tasks({ path: ".", status: "active" })
```
**Features:**
- **Priorities**: 🔴 high, 🟡 medium, ⚪ low
- **Statuses**: `backlog → active → done | cancelled`
- **Tags**: Categorize tasks (`bug`, `feature`, `docs`, etc.)
- **History log**: Every status change is auto-logged, plus manual notes
- **Viewer integration**: Tasks tab in the browser viewer with live updates
- **Persistent**: Tasks survive between sessions, stored in `.aidex/index.db`
Your AI assistant can create tasks while working (*"found a bug in the parser, add it to the backlog"*), track progress, and pick up where you left off next session.
## Screenshots
Take cross-platform screenshots directly from your AI assistant - no manual file paths needed:
```
aidex_screenshot() # Full screen
aidex_screenshot({ mode: "active_window" }) # Active window
aidex_screenshot({ mode: "window", window_title: "VS Code" }) # Specific window
aidex_screenshot({ mode: "region" }) # Interactive selection
aidex_windows({ filter: "chrome" }) # Find window titles
```
**Features:**
- **4 capture modes**: Fullscreen, active window, specific window (by title), interactive region selection
- **Cross-platform**: Windows (PowerShell), macOS (screencapture), Linux (maim/scrot)
- **Multi-monitor**: Select which monitor to capture
- **Delay**: Wait N seconds before capturing (e.g., to open a menu first)
- **Auto-path**: Default saves to temp directory with fixed filename - your AI reads it immediately
- **No index required**: Works standalone, no `.aidex/` needed
Use `aidex_windows` to find the exact window title, then `aidex_screenshot` with `mode: "window"` to capture it.
**Future:** Screenshots will be storable in the AiDex database - attach them to tasks for bug documentation, capture before/after states for refactoring, or persist GUI evidence across sessions.
## Interactive Viewer
Explore your indexed project visually in the browser:
```
aidex_viewer({ path: "." })
```
Opens `http://localhost:3333` with:
- **Interactive file tree** - Click to expand directories
- **File signatures** - Click any file to see its types and methods
- **Live reload** - Changes detected automatically while you code
- **Git status icons** - See which files are modified, staged, or untracked
Close with `aidex_viewer({ path: ".", action: "close" })`
## CLI Usage
```bash
aidex scan Q:/develop # Find all indexed projects
aidex init ./myproject # Index a project from command line
```
> `aidex-mcp` works as an alias for `aidex`.
## Performance
| Project | Files | Items | Index Time | Query Time |
|---------|-------|-------|------------|------------|
| Small (AiDex) | 19 | 1,200 | <1s | 1-5ms |
| Medium (RemoteDebug) | 10 | 1,900 | <1s | 1-5ms |
| Large (LibPyramid3D) | 18 | 3,000 | <1s | 1-5ms |
| XL (MeloTTS) | 56 | 4,100 | ~2s | 1-10ms |
## Technology
- **Parser**: [Tree-sitter](https://tree-sitter.github.io/) - Real parsing, not regex
- **Database**: SQLite with WAL mode - Fast, single file, zero config
- **Protocol**: [MCP](https://modelcontextprotocol.io/) - Works with any compatible AI
## Project Structure
```
.aidex/ ← Created in YOUR project
├── index.db ← SQLite database
└── summary.md ← Optional documentation
AiDex/ ← This repository
├── src/
│ ├── commands/ ← Tool implementations
│ ├── db/ ← SQLite wrapper
│ ├── parser/ ← Tree-sitter integration
│ └── server/ ← MCP protocol handler
└── build/ ← Compiled output
```
## Contributing
PRs welcome! Especially for:
- New language support
- Performance improvements
- Documentation
## License
MIT License - see [LICENSE](LICENSE)
## Authors
Uwe Chalas & Claude
