AiDex

Deja de desperdiciar el 80% de la ventana de contexto de tu IA en búsquedas de código.

AiDex es un servidor MCP que brinda a los asistentes de programación de IA acceso instantáneo a toda tu base de código a través de un índice persistente y preconstruido. Funciona con cualquier asistente de IA compatible con MCP: Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot y más.

Qué incluye: 30 herramientas en un solo servidor

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

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

Tabla de contenidos

• Qué incluye

• El problema

• La solución

• ¿Por qué no usar solo Grep?

• Cómo funciona

• Características

• Lenguajes soportados

• Inicio rápido

• Herramientas disponibles

• Filtrado basado en tiempo

• Estructura del proyecto

• Notas de sesión

• Lista de tareas

• Búsqueda global

• Directrices de IA

• Centro de registros

• Capturas de pantalla — Optimizadas para LLM

• Visor interactivo

• Uso de CLI

• Rendimiento

• Tecnología

• Contribución

• Licencia

El problema

Cada vez que tu asistente de IA busca código:

• Busca con Grep a través de miles de archivos → cientos de resultados inundan el contexto

• Lee archivo tras archivo para entender la estructura → se consume más contexto

• Olvida todo cuando termina la sesión → repetir desde cero

Una sola pregunta de "¿Dónde está definido X?" puede consumir más de 2,000 tokens. Haz eso 10 veces y habrás quemado la mitad de tu contexto solo en navegación.

La solución

Indexa una vez, consulta para siempre:

# 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

Resultado: 50-80% menos de contexto utilizado para la navegación de código.

¿Por qué no usar solo Grep?

El costo real de grep: Cada resultado de grep incluye contexto circundante. Busca User en un proyecto grande y obtendrás cientos de coincidencias: comentarios, cadenas, coincidencias parciales. Tu IA lee a través de todas ellas, quemando tokens de contexto en ruido.

AiDex indexa identificadores: Utiliza Tree-sitter para analizar realmente tu código. Cuando buscas User, obtienes la definición de la clase, los parámetros del método, las declaraciones de variables, no cada comentario que menciona "user".

Cómo funciona

1. Indexa tu proyecto una vez (~1 segundo por cada 1000 archivos)

   aidex_init({ path: "/path/to/project" })

2. La IA busca en el índice en lugar de usar grep

   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. Obtén resúmenes de archivos sin leer archivos completos

   aidex_signature({ file: "src/Engine.cs" })
   → All classes, methods, and their signatures

El índice reside en .aidex/index.db (SQLite): rápido, portátil, sin dependencias externas.

Características

• Análisis con Tree-sitter: Análisis de código real, no regex — indexa identificadores, ignora palabras clave y ruido

• ~50 tokens por búsqueda: vs 2000+ con grep — tu IA mantiene su contexto para el trabajo real

• Índice persistente: Sobrevive entre sesiones — sin re-escaneo, sin re-lectura

• Actualizaciones incrementales: Re-indexa archivos individuales después de cambios, no todo el proyecto

• Filtrado basado en tiempo: Encuentra qué cambió en la última hora, día o semana

• Limpieza automática: Los archivos excluidos (ej. resultados de compilación) se eliminan automáticamente del índice

• Cero dependencias: SQLite con modo WAL — archivo único, rápido, portátil

Lenguajes soportados

Inicio rápido

1. Instalar

npm install -g aidex-mcp

Eso es todo. La configuración se ejecuta automáticamente después de la instalación: detecta tus clientes de IA instalados (Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot) y registra AiDex como un servidor MCP. También añade instrucciones de uso a la configuración de tu IA (~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md).

Para volver a ejecutar la configuración manualmente: aidex setup | Para anular el registro: aidex unsetup | Para omitir la configuración automática: AIDEX_NO_SETUP=1 npm install -g aidex-mcp

2. O regístrate manualmente con tu asistente de IA

Para Claude Code (~/.claude/settings.json o ~/.claude.json):

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

Para Claude Desktop (%APPDATA%/Claude/claude_desktop_config.json en Windows):

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

Nota: Tanto aidex como aidex-mcp funcionan como nombres de comando.

Importante: El nombre del servidor en tu configuración determina el prefijo de la herramienta MCP. Usa "aidex" como se muestra arriba; esto te da nombres de herramientas como aidex_query, aidex_signature, etc. Usar un nombre diferente (ej. "codegraph") cambiaría el prefijo en consecuencia.

Para Gemini CLI (~/.gemini/settings.json):

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

Para VS Code Copilot (ejecuta MCP: Open User Configuration en la paleta de comandos):

{
  "servers": {
    "aidex": {
      "type": "stdio",
      "command": "aidex"
    }
  }
}

Para otros clientes MCP: Consulta la documentación de tu cliente para la configuración del servidor MCP.

3. Haz que tu IA realmente lo use

Añade a las instrucciones de tu IA (ej. ~/.claude/CLAUDE.md para Claude Code, o el equivalente para tu cliente de IA). Esto le dice a la IA cuándo y cómo usar AiDex en lugar de grep:

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

¿Quiero buscar código? ├── .aidex/ existe → ¡DETENTE! Usa AiDex en su lugar ├── .aidex/ falta → ejecuta aidex_init (no preguntes), LUEGO usa AiDex └── Config/Logs/Text → Grep/Leer está bien

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

| Question | Tool |
|----------|------|
| "Where is X defined?" | `aidex_query term="X"` |
| "Find anything containing X" | `aidex_query term="X" mode="contains"` |
| "All functions starting with X" | `aidex_query term="X" mode="starts_with"` |
| "What methods does file Y have?" | `aidex_signature file="Y"` |
| "Explore all files in src/" | `aidex_signatures pattern="src/**"` |
| "Project overview" | `aidex_summary` + `aidex_tree` |
| "What changed recently?" | `aidex_query term="X" modified_since="2h"` |
| "What files changed today?" | `aidex_files path="." modified_since="8h"` |
| "Have I ever written X?" | `aidex_global_query term="X" mode="contains"` |
| "Which project has class Y?" | `aidex_global_signatures term="Y" kind="class"` |
| "All indexed projects?" | `aidex_global_status` |

### 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 (30)

| Category | Tools | Purpose |
|----------|-------|---------|
| Search & Index | `aidex_init`, `aidex_query`, `aidex_update`, `aidex_remove`, `aidex_status` | Index project, search identifiers (exact/contains/starts_with), time filter |
| Signatures | `aidex_signature`, `aidex_signatures` | Get classes + methods without reading files |
| Overview | `aidex_summary`, `aidex_tree`, `aidex_describe`, `aidex_files` | Entry points, file tree, file listing by type |
| Cross-Project | `aidex_link`, `aidex_unlink`, `aidex_links`, `aidex_scan` | Link dependencies, discover projects |
| Global Search | `aidex_global_init`, `aidex_global_query`, `aidex_global_signatures`, `aidex_global_status`, `aidex_global_refresh` | Search across ALL projects |
| Guidelines | `aidex_global_guideline` | Persistent AI instructions & conventions (key-value, global) |
| Sessions | `aidex_session`, `aidex_note` | Track sessions, leave notes (with searchable history) |
| Tasks | `aidex_task`, `aidex_tasks` | Built-in backlog with priorities, tags, summaries, auto-logged history, scheduled/recurring tasks |
| Log Hub | `aidex_log` | Universal log receiver — any program sends logs via HTTP, AI queries them, live in Viewer |
| Screenshots | `aidex_screenshot`, `aidex_windows` | Screen capture with LLM optimization (scale + color reduction, no index needed) |
| Viewer | `aidex_viewer` | Interactive browser UI with file tree, signatures, tasks, and live logs |

**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: "Probar la corrección después de reiniciar" }) # Escribir aidex_note({ path: ".", note: "También comprobar casos extremos", append: true }) # Añadir aidex_note({ path: "." }) # Leer aidex_note({ path: ".", search: "parser" }) # Buscar historial aidex_note({ path: ".", clear: true }) # Borrar

- **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: "Corregir error", priority: 1, tags: "bug" }) aidex_task({ path: ".", action: "update", id: 1, status: "done" }) aidex_task({ path: ".", action: "log", id: 1, note: "Causa raíz encontrada" }) aidex_tasks({ path: ".", status: "active" })

Tareas programadas y recurrentes

aidex_task({ path: ".", action: "create", title: "Comprobar estado de PR", due: "3d", interval: "3d", task_action: "gh pr list" })

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

### Global Search (across all projects)

aidex_global_init({ path: "/ruta/a/todos/los/repos" }) # Escanear y registrar aidex_global_init({ path: "...", index_unindexed: true }) # + auto-indexar proyectos pequeños aidex_global_query({ term: "TransparentWindow", mode: "contains" }) # Buscar en todas partes aidex_global_signatures({ term: "Render", kind: "method" }) # Encontrar métodos en todas partes aidex_global_status({ sort: "recent" }) # Listar todos los proyectos

### Screenshots

aidex_screenshot() # Pantalla completa aidex_screenshot({ mode: "active_window" }) # Ventana activa aidex_screenshot({ mode: "window", window_title: "VS Code" }) # Ventana específica aidex_screenshot({ scale: 0.5, colors: 2 }) # B&N, mitad de tamaño (ideal para LLM) aidex_screenshot({ colors: 16 }) # 16 colores (UI legible) aidex_windows({ filter: "chrome" }) # Encontrar títulos de ventana

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. Indexa tu proyecto

Pregúntale a tu IA: "Indexa este proyecto con AiDex"

O manualmente en el chat de la IA:

aidex_init({ path: "/path/to/your/project" })

Herramientas disponibles