Aidex

AiDex - Persistent Code Index (MCP Server)

AiDex provides fast, precise code search through a pre-built index. Always prefer AiDex over Grep/Glob for code searches.

REQUIRED: Before using Grep/Glob/Read for code searches

Do I want to search code?
├── .aidex/ exists    → STOP! Use AiDex instead
├── .aidex/ missing   → run aidex_init (don't ask), THEN use AiDex
└── Config/Logs/Text  → Grep/Read is fine

NEVER do this when .aidex/ exists:

• ❌ Grep pattern="functionName" → ✅ aidex_query term="functionName"
• ❌ Grep pattern="class.*Name" → ✅ aidex_query term="Name" mode="contains"
• ❌ Read file.cs to see methods → ✅ aidex_signature file="file.cs"
• ❌ Glob pattern="**/*.cs" + Read → ✅ aidex_signatures pattern="**/*.cs"

Session-Start Rule (REQUIRED — every session, no exceptions)

1. Call aidex_session({ path: "<project>" }) — detects external changes, auto-reindexes
2. If .aidex/ does NOT exist → run aidex_init automatically (don't ask)
3. If a session note exists → show it to the user before continuing
4. Before ending a session: always leave a note about what to do next

Question → Right Tool

Search Modes

• exact (default): Finds only the exact identifier — log won't match catalog
• contains: Finds identifiers containing the term — render matches preRenderSetup
• starts_with: Finds identifiers starting with the term — Update matches UpdatePlayer, UpdateUI

All Tools (28)

11 languages: C#, TypeScript, JavaScript, Rust, Python, C, C++, Java, Go, PHP, Ruby

Session Notes

Leave notes for the next session — they persist in the database:

aidex_note({ path: ".", note: "Test the fix after restart" })        # Write
aidex_note({ path: ".", note: "Also check edge cases", append: true }) # Append
aidex_note({ path: "." })                                              # Read
aidex_note({ path: ".", search: "parser" })                            # Search history
aidex_note({ path: ".", clear: true })                                 # Clear

• Before ending a session: automatically leave a note about next steps
• User says "remember for next session: ..." → write it immediately

Task Backlog

Track TODOs, bugs, and features right next to your code index:

aidex_task({ path: ".", action: "create", title: "Fix bug", priority: 1, tags: "bug" })
aidex_task({ path: ".", action: "update", id: 1, status: "done" })
aidex_task({ path: ".", action: "log", id: 1, note: "Root cause found" })
aidex_tasks({ path: ".", status: "active" })

Priority: 1=high, 2=medium, 3=low | Status: backlog → active → done | cancelled

Global Search (across all projects)

aidex_global_init({ path: "/path/to/all/repos" })                     # Scan & register
aidex_global_init({ path: "...", index_unindexed: true })              # + auto-index small projects
aidex_global_query({ term: "TransparentWindow", mode: "contains" })   # Search everywhere
aidex_global_signatures({ term: "Render", kind: "method" })           # Find methods everywhere
aidex_global_status({ sort: "recent" })                                # List all projects

Screenshots

aidex_screenshot()                                             # Full screen
aidex_screenshot({ mode: "active_window" })                    # Active window
aidex_screenshot({ mode: "window", window_title: "VS Code" }) # Specific window
aidex_screenshot({ scale: 0.5, colors: 2 })                   # B&W, half size (ideal for LLM)
aidex_screenshot({ colors: 16 })                               # 16 colors (UI readable)
aidex_windows({ filter: "chrome" })                            # Find window titles

No index needed. Returns file path → use Read to view immediately.

LLM optimization strategy: Always start with aggressive settings, then retry if unreadable:

1. First try: scale: 0.5, colors: 2 (B&W, half size — smallest possible)
2. If unreadable: retry with colors: 16 (adds shading for UI elements)
3. If still unclear: scale: 0.75 or omit colors for full quality
4. Remember what works for each window/app during the session — don't retry every time.

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" })

✨ Features

• Tree-sitter Parsing: Real code parsing, not regex — indexes identifiers, ignores keywords and noise
• ~50 Tokens per Search: vs 2000+ with grep — your AI keeps its context for actual work
• Persistent Index: Survives between sessions — no re-scanning, no re-reading
• Incremental Updates: Re-index single files after changes, not the whole project
• Time-based Filtering: Find what changed in the last hour, day, or week
• Auto-Cleanup: Excluded files (e.g., build outputs) are automatically removed from index
• Zero Dependencies: SQLite with WAL mode — single file, fast, portable

📦 Installation

npm install -g aidex-mcp

💻 Usage Examples

Basic Usage

# Find where "PlayerHealth" is defined — 1 call, ~50 tokens
aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156

# All methods in a file — without reading the whole file
aidex_signature({ file: "src/Engine.cs" })
→ class GameEngine { Update(), Render(), LoadScene(), ... }

# What changed in the last 2 hours?
aidex_query({ term: "render", modified_since: "2h" })

# Search across ALL your projects at once
aidex_global_query({ term: "TransparentWindow", mode: "contains" })
→ Found in: LibWebAppGpu (3 hits), DebugViewer (1 hit)

# Leave a note for your next session
aidex_note({ path: ".", note: "Test the parser fix after restart" })

# Create a task while working
aidex_task({ path: ".", action: "create", title: "Fix edge case in parser", priority: 1, tags: "bug" })

📚 Documentation

What's Inside — 28 Tools in One Server

11 languages — C#, TypeScript, JavaScript, Rust, Python, C, C++, Java, Go, PHP, Ruby

Available Tools

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

Note History (v1.10): Old notes are automatically archived when overwritten or cleared. Browse and search past notes:

aidex_note({ path: ".", history: true })                    # Browse archived notes
aidex_note({ path: ".", search: "parser" })                 # Search note history
aidex_note({ path: ".", history: true, limit: 5 })          # Last 5 archived notes

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
• Search past sessions: "What did we do about the parser?"

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.

Global Search

Search across ALL your indexed projects at once. Perfect for "Have I ever written a transparent window?" or "Where did I use that algorithm?"

Setup

aidex_global_init({ path: "Q:/develop" })                              # Scan & register
aidex_global_init({ path: "Q:/develop", exclude: ["llama.cpp"] })      # Skip external repos
aidex_global_init({ path: "Q:/develop", index_unindexed: true })       # Auto-index all found projects
aidex_global_init({ path: "Q:/develop", index_unindexed: true, show_progress: true })  # With browser progress UI

This scans your project directory, registers all AiDex-indexed projects in a global database (~/.aidex/global.db), and reports any unindexed projects it finds by detecting project markers (.csproj, package.json, Cargo.toml, etc.).

With index_unindexed: true, it also auto-indexes all discovered projects with ≤500 code files. Larger projects are listed separately for user decision. Add show_progress: true to open a live progress UI in your browser (http://localhost:3334).

Search

aidex_global_query({ term: "TransparentWindow" })                      # Exact match
aidex_global_query({ term: "transparent", mode: "contains" })          # Fuzzy search
aidex_global_signatures({ name: "Render", kind: "method" })            # Find methods
aidex_global_signatures({ name: "Player", kind: "class" })             # Find classes

How it works

• Uses SQLite ATTACH DATABASE to query project databases directly — no data copying
• Results are cached in memory (5-minute TTL) for fast repeated queries
• Projects are batched (8 at a time) to respect SQLite's attachment limit
• Each project keeps its own .aidex/index.db as the single source of truth
• Auto-deduplication: Parent projects that contain sub-projects are automatically skipped (e.g., MyApp/ is removed when MyApp/Frontend/ and MyApp/Backend/ exist as separate indexed projects)

Management

aidex_global_status()                                                  # List all projects
aidex_global_status({ sort: "recent" })                                # Most recently indexed first
aidex_global_refresh()                                                 # Update stats, remove stale

Screenshots — LLM-Optimized

Take screenshots and reduce them up to 95% for LLM context. A typical screenshot goes from ~100 KB to ~5 KB — that's thousands of tokens saved per image.

Why this matters

Most screenshots in AI context are for reading text — error messages, logs, UI labels. You don't need 16 million colors for that.

Usage

aidex_screenshot()                                             # Full screen (full quality)
aidex_screenshot({ mode: "active_window" })                    # Active window
aidex_screenshot({ mode: "window", window_title: "VS Code" }) # Specific window
aidex_screenshot({ scale: 0.5, colors: 2 })                   # B&W, half size (best for text)
aidex_screenshot({ scale: 0.5, colors: 16 })                  # 16 colors (UI readable)
aidex_screenshot({ colors: 256 })                              # 256 colors (good quality)
aidex_screenshot({ mode: "region" })                           # Interactive selection
aidex_screenshot({ mode: "rect", x: 100, y: 200, width: 800, height: 600 })  # Coordinates
aidex_windows({ filter: "chrome" })                            # Find window titles

Optimization parameters

Recommended strategy for AI assistants

The tool description tells LLMs to optimize automatically:

1. Start aggressive: scale: 0.5, colors: 2 (smallest possible)
2. If unreadable: retry with colors: 16 (adds shading for UI elements)
3. If still unclear: try scale: 0.75 or full color
4. Remember: cache what works per window/app for the rest of the session

This way the AI learns the right settings per app without wasting tokens on oversized images.

Features

• 5 capture modes: Fullscreen, active window, specific window (by title), interactive region selection, coordinate-based rectangle
• Cross-platform: Windows (PowerShell + System.Drawing), macOS (sips + ImageMagick), Linux (ImageMagick)
• Multi-monitor: Select which monitor to capture
• Delay: Wait N seconds before capturing (e.g., to open a menu first)
• Size reporting: Shows original → optimized size and percentage saved
• Auto-path: Default saves to temp directory with fixed filename
• No index required: Works standalone, no .aidex/ needed

Interactive Viewer

Explore your indexed project visually in the browser:

aidex_viewer({ path: "." })