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.

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