AiDex

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

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

{
  "mcpServers": {
    "aidex": {
      "type": "stdio",
      "command": "aidex",
      "env": {}
    }
  }
}

For Claude Desktop (%APPDATA%/Claude/claude_desktop_config.json on Windows):

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

{
  "mcpServers": {
    "aidex": {
      "command": "aidex"
    }
  }
}

For VS Code Copilot (run MCP: Open User Configuration in Command Palette):

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

## 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

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 - Real parsing, not regex
• Database: SQLite with WAL mode - Fast, single file, zero config
• Protocol: MCP - 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

Authors

Uwe Chalas & Claude