AiDex

AiDex

El cerebro persistente para agentes de codificación con IA.

AiDex es un servidor MCP que brinda a los asistentes de codificación con IA una memoria, búsqueda semántica y telemetría en vivo — local-first, independiente del modelo. Funciona con cualquier asistente de IA compatible con MCP: Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot y más.

Tres Pilares

🧠 Memoria — Las tareas, notas y notas de sesión sobreviven a cada chat. Historial registrado automáticamente, tareas programadas, continuidad entre sesiones. Tu IA sabe mañana lo que importó hoy.

🔍 Búsqueda — Tres modos: exact (identificador), semantic (concepto), hybrid (fusión RRF de ambos). Incrusta código, documentación y elementos del espacio de trabajo en una sola clasificación. Entre proyectos — cada repositorio en una sola consulta. Capa LLM opcional que traduce consultas no inglesas y reordena los resultados.

🌐 Telemetría — LogHub recibe registros en vivo de cualquier aplicación vía HTTP (sin SDK). La IA observa lo que tu código realmente hace, no solo lo que dice. Transmisión en vivo en el Viewer.

Qué Incluye — 33 Herramientas en un Solo Servidor

14 lenguajes — C#, TypeScript, JavaScript, Rust, Python, C, C++, Java, Go, PHP, Ruby, HCL/Terraform, Kotlin, Swift — además de frontmatter de Astro

# 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
• Búsqueda Semántica y Capa LLM 🆕
• El Problema
• La Solución
• ¿Por Qué No 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
• Backlog de Tareas
• Búsqueda Global
• Directrices de IA
• Log Hub
• Panel de Depuración
• Capturas de Pantalla — Optimizadas para LLM
• Viewer Interactivo
• Uso de CLI
• Rendimiento
• Tecnología
• Contribuciones
• Licencia

Búsqueda Semántica y Capa LLM

v2.0 añadió búsqueda semántica mediante incrustaciones ejecutadas localmente — tu IA puede encontrar una función incluso cuando no conoce el identificador exacto.

Tres modos — elige la herramienta adecuada para la pregunta

Qué se incrusta

• Código — cada método y tipo, fragmentación de tres niveles (firma + comentario de documentación + bolsa de identificadores ponderada)
• Documentación — secciones de Markdown (README, CHANGELOG, docs/, archivos de plan), divididas en los límites de encabezados
• Espacio de trabajo — tareas, registros de tareas, notas de sesión, historial de notas archivadas

Una clasificación, todo tipo. Una consulta como "cómo escribir registros desde programas externos" muestra la sección ## Log Hub del README primero, luego el método log en commands/log.ts, y luego cualquier tarea relacionada.

Configuración

// Enable embeddings on a project (one-time, ~30s for AiDex itself, cached afterwards)
aidex_init({ path: ".", embeddings: true })

// Search
aidex_search({ query: "how do we batch requests to the LLM", path: "." })
aidex_search({ query: "retry with backoff", scope: "all" })  // across every embedded project

O usa la pestaña Configuración en el Viewer (aidex_settings({ path: ".", open: true })) — interruptores para incrustaciones, proveedor de LLM, modelo y el interruptor de privacidad.

Capa LLM opcional

Cuando se configura una clave de API de Anthropic / OpenAI / OpenRouter / Ollama / HuggingFace, AiDex puede:

• Traducir consultas no inglesas → "wie speichere ich Logs lokal" encuentra el código correcto
• Expandir consultas vagas en 2-4 subconsultas concretas (fusionadas con RRF)
• Reordenar los candidatos de recuperación top-N

El interruptor de privacidad llm_send_code está desactivado por defecto — solo se envían tu consulta literal y metadatos (rutas, nombres, anclas). Los cuerpos de código permanecen locales. Por proyecto, fácil de verificar en Configuración.

Local-first: funciona completamente sin conexión con incrustaciones puras. La capa LLM es opcional, nunca requerida.

El Problema

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

• Usa grep a través de miles de archivos → cientos de resultados inundan el contexto
• Lee archivo tras archivo para entender la estructura → más contexto consumido
• Olvida todo cuando la sesión termina → repetir desde cero

Una sola pregunta de "¿Dónde está definido X?" puede consumir 2,000+ tokens. Hazlo 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 contexto usado para la navegación de código.

¿Por Qué No 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 todo eso, quemando tokens de contexto en ruido.

AiDex indexa identificadores: Usa 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 "usuario".

Cómo Funciona

1. Indexa tu proyecto una vez (~1 segundo por 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 vive en .aidex/index.db (SQLite) — rápido, portátil, sin dependencias externas.

Características

• Análisis 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 lo que cambió en la última hora, día o semana
• Limpieza Automática: Los archivos excluidos (por ejemplo, salidas 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

Requisitos Previos

• Node.js ≥ 20 (verifica con node --version)
  • macOS: brew install node o nvm install 20 && nvm use 20
  • Linux: usa tu gestor de paquetes o nvm
  • Windows: nodejs.org
  • Si usas nvm, el repositorio incluye un .nvmrc — nvm use elige la versión correcta automáticamente.

1. Instalación

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 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 cancelar 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 (por ejemplo, "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 (p. ej., ~/.claude/CLAUDE.md para Claude Code, o el equivalente para tu cliente de IA). Esto le indica a la IA cuándo y cómo usar AiDex en lugar de hacer búsquedas con 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/ no existe → ejecuta aidex_init (no preguntes), LUEGO usa AiDex └── Config/Logs/Texto → grep/lectura 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 |

**14 languages:** C#, TypeScript, JavaScript, Rust, Python, C, C++, Java, Go, PHP, Ruby, HCL/Terraform, Kotlin, Swift — plus Astro frontmatter

### Session Notes

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

aidex_note({ path: ".", note: "Prueba la corrección después de reiniciar" }) # Escribir aidex_note({ path: ".", note: "También revisa casos límite", append: true }) # Añadir aidex_note({ path: "." }) # Leer aidex_note({ path: ".", search: "parser" }) # Buscar historial aidex_note({ path: ".", clear: true }) # Limpiar

- **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: "Revisar estado del 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 }) # + autoindexar 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 ventanas

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

Pídele a tu IA: "Indexa este proyecto con AiDex"

O manualmente en el chat de IA:

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

Herramientas disponibles

Filtrado por tiempo

Rastrea lo que cambió recientemente con modified_since y 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

Formatos admitidos:

• Relativo: 30m (minutos), 2h (horas), 1d (días), 1w (semanas)
• Fecha ISO: 2026-01-27 o 2026-01-27T14:30:00

Perfecto para preguntas como "¿Qué cambié en la última hora?"

Estructura del proyecto

AiDex indexa TODOS los archivos de tu proyecto (no solo código), permitiéndote consultar la estructura:

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

Tipos de archivo: code, config, doc, asset, test, other, dir

Usa modified_since para encontrar archivos modificados en esta sesión: perfecto para "¿Qué edité?"

Notas de sesión

Deja recordatorios para la próxima sesión: no más perder contexto entre 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

Historial de notas (v1.10): Las notas antiguas se archivan automáticamente cuando se sobrescriben o se limpian. Explora y busca notas pasadas:

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

Resúmenes de notas (v1.15): Proporciona un summary al escribir/limpiar una nota: la nota archivada recibe esta descripción de una frase. El historial muestra entonces resúmenes en lugar de texto truncado:

aidex_note({ path: ".", note: "New focus", summary: "Previous session: finished parser refactoring" })

Casos de uso:

• Antes de terminar una sesión: "Recuerda probar X la próxima vez"
• Recordatorio automático de IA: guarda qué verificar después de un reinicio
• Notas de traspaso: contexto para la próxima sesión sin editar archivos de configuración
• Buscar sesiones pasadas: "¿Qué hicimos con el parser?"

Las notas se almacenan en la base de datos SQLite (.aidex/index.db) y persisten indefinidamente.

Backlog de tareas

Mantén las tareas de tu proyecto junto a tu índice de código: sin Jira, sin Trello, sin cambiar de contexto:

aidex_task({ path: ".", action: "create", title: "Fix parser bug", priority: 1, tags: "bug", summary: "Parser crashes on nested generics in C#" })
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" })

Tareas programadas y recurrentes

Las tareas pueden tener fechas de vencimiento e intervalos de repetición. Las tareas vencidas se reportan al inicio de cada sesión en TODOS los proyectos:

# One-shot: remind in 3 days
aidex_task({ path: ".", action: "create", title: "Review PR", due: "3d", task_action: "Check if PR was submitted" })

# Recurring: check every week
aidex_task({ path: ".", action: "create", title: "Check dependencies", due: "1w", interval: "1w", task_action: "npm outdated" })

# Auto-execute: runs the action automatically when due
aidex_task({ path: ".", action: "create", title: "Refresh stats", due: "1d", interval: "1d", auto_go: true })

Formatos de vencimiento: Relativo ("30m", "2h", "3d", "1w") o fecha ISO ("2026-04-10")

En cada llamada a aidex_session, el Programador de tareas verifica ~/.aidex/global.db para tareas vencidas en todos los proyectos, incluso si estás trabajando en un proyecto diferente. Las tareas recurrentes avanzan automáticamente su fecha de vencimiento después de cada activación.

Características:

• Resúmenes: tabla de contenido de una frase por tarea: revisa el backlog sin leer detalles completos
• Prioridades: 🔴 alta, 🟡 media, ⚪ baja
• Estados: backlog → active → done | cancelled
• Etiquetas: categoriza tareas (bug, feature, docs, etc.)
• Registro de historial: cada cambio de estado se registra automáticamente, más notas manuales
• Programación: fechas de vencimiento, intervalos recurrentes, acciones, ejecución automática en todos los proyectos
• Integración con el Visor: pestaña de tareas en el visor del navegador con actualizaciones en vivo
• Persistente: las tareas sobreviven entre sesiones, almacenadas en .aidex/index.db

Tu asistente de IA puede crear tareas mientras trabaja ("encontré un error en el parser, agrégalo al backlog"), hacer seguimiento del progreso y retomar donde lo dejaste en la próxima sesión.

Búsqueda global

Busca en TODOS tus proyectos indexados a la vez. Perfecto para "¿alguna vez escribí una ventana transparente?" o "¿dónde usé ese algoritmo?"

Configuración

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

Esto escanea tu directorio de proyectos, registra todos los proyectos indexados con AiDex en una base de datos global (~/.aidex/global.db) y reporta cualquier proyecto no indexado que encuentre detectando marcadores de proyecto (.csproj, package.json, Cargo.toml, etc.).

Con index_unindexed: true, también autoindexa todos los proyectos descubiertos con ≤500 archivos de código. Los proyectos más grandes se listan por separado para que el usuario decida. Añade show_progress: true para abrir una interfaz de progreso en vivo en tu navegador (http://localhost:3334).

Búsqueda

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

Cómo funciona

• Usa SQLite ATTACH DATABASE para consultar bases de datos de proyectos directamente: sin copiar datos
• Los resultados se almacenan en caché en memoria (TTL de 5 minutos) para consultas repetidas rápidas
• Los proyectos se procesan por lotes (8 a la vez) para respetar el límite de adjuntos de SQLite
• Cada proyecto mantiene su propio .aidex/index.db como fuente única de verdad
• Desduplicación automática: los proyectos padre que contienen subproyectos se omiten automáticamente (p. ej., MyApp/ se elimina cuando MyApp/Frontend/ y MyApp/Backend/ existen como proyectos indexados separados)

Gestión

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

Pautas de IA

Almacena convenciones de codificación persistentes, listas de verificación de revisión e instrucciones de IA en un solo lugar, compartidas entre todos los proyectos.

aidex_global_guideline({ action: "set", key: "review", value: "Always check: error handling, null safety, no hardcoded strings" })
aidex_global_guideline({ action: "set", key: "style", value: "Use PascalCase for classes, camelCase for methods, 4-space indent" })
aidex_global_guideline({ action: "get", key: "review" })               # Retrieve a guideline
aidex_global_guideline({ action: "list" })                             # Show all guidelines
aidex_global_guideline({ action: "list", filter: "code" })             # Filter by name
aidex_global_guideline({ action: "delete", key: "old-rule" })          # Remove a guideline

Casos de uso:

• Lista de verificación de revisión de código: dile a tu IA exactamente qué buscar cada vez
• Convenciones de codificación: guarda las reglas de estilo del equipo una vez, refiérelas en cualquier proyecto
• Lista de verificación de lanzamiento: proceso paso a paso para publicar
• Instrucciones independientes del proyecto: no más pegar el mismo contexto en cada sesión

Las pautas se almacenan en ~/.aidex/global.db: disponibles en todos tus proyectos sin aidex_init. Pídele a tu IA: "Carga la pauta de revisión y aplícala a este archivo."

Centro de logs: registro universal

Convierte cualquier programa en una fuente de logs para tu asistente de IA. Tu aplicación envía logs mediante HTTP POST, la IA los consulta mediante MCP y los ves en vivo en el Visor: cero dependencias, cero configuración en tu código.

Cómo funciona

Your Program ──HTTP POST──→ AiDex Log Hub (port 3335) ──→ Ring Buffer
                                        │                      │
                                        │ WebSocket             │ MCP query
                                        ↓                      ↓
                                   Viewer (Logs tab)      AI Assistant
                                   (you see live)       (queries & analyzes)

Inicio rápido

1. La IA inicia el Centro de logs: aidex_log({ action: "init" })
2. La IA abre el Visor: aidex_viewer({ path: "." }): la pestaña Logs muestra la transmisión en vivo
3. Añade una línea a tu programa:

// C#
await new HttpClient().PostAsJsonAsync("http://localhost:3335/log",
    new { level = "info", source = "MyApp", message = "Player spawned", data = new { x = 10, y = 20 } });

# Python
requests.post("http://localhost:3335/log", json={"level": "info", "source": "MyApp", "message": "Done"})

// JavaScript
fetch("http://localhost:3335/log", {
    method: "POST", headers: {"Content-Type": "application/json"},
    body: JSON.stringify({level: "info", source: "MyApp", message: "Started"})
});

# PowerShell
Invoke-RestMethod -Uri http://localhost:3335/log -Method POST -ContentType "application/json" -Body '{"level":"info","source":"Script","message":"Done"}'

API HTTP

Campos: level (debug/info/warn/error), source (nombre de la aplicación), message (texto, obligatorio), data (JSON opcional), timestamp (opcional, ms)

Características

• Búfer circular: FIFO en memoria de tamaño fijo (10,000 entradas por defecto): las entradas más antiguas se sobrescriben
• Cero costo: sin servidor, sin búfer, sin recursos hasta que se llama a init
• Persistencia: almacenamiento SQLite opcional con limpieza automática de 7 días (persist: true)
• Patrón de consumo: query con consume: true elimina las entradas devueltas: ideal para sondeo
• Integración con el Visor: pestaña de logs con transmisión en vivo por WebSocket, filtros de nivel/fuente/texto, desplazamiento automático
• Dispara y olvida: solo haz POST y continúa: si el servidor no está en ejecución, el POST falla silenciosamente

API de control: deja que la IA conduzca tu aplicación

Los logs y los widgets del panel fluyen aplicación → IA. La API de control es el canal de retorno: IA → aplicación. Convierte el Centro de logs en un bus de comandos diminuto y sin dependencias, para que un asistente de IA pueda controlar cualquier programa en ejecución sin que escribas un servidor.

La IA establece un comando; tu aplicación lo sondea, lo ejecuta y publica el resultado:

AI ──control_set {id,cmd}──→  Hub  ←──GET /control──  Your App (polls ~1s)
AI ←──control_get──── result ─ Hub  ←──POST /control── runs it, posts result + ack

• control_set { id, value }: la IA (o un control deslizante/interruptor del Visor) establece una ranura de control.
• GET /control: tu aplicación lee todos los valores de control actuales.
• POST /control: tu aplicación escribe resultados/confirmaciones.
• POST /control/press { id }: registra una pulsación de un control button. El centro posee el contador, por lo que las pulsaciones de varios paneles abiertos se suman en lugar de sobrescribirse.
• control_get: la IA lee lo que la aplicación reportó.
• POST /control/subscribe (opcional): empuja en lugar de sondear, ver más abajo. Empuja en lugar de sondear. Si tu aplicación ejecuta su propio servidor HTTP, puede suscribirse una vez con { "port": 8080 } (el hub llama de vuelta a la dirección del remitente, la ruta por defecto es /control) o un { "url": "http://192.168.1.50:8080/control" } completo, opcionalmente limitado a { "ids": [...] }. A partir de entonces, cada cambio se envía por POST a esa URL de inmediato, como el mismo mapa plano { id: value } que devuelve GET /control. Sin solicitudes inactivas, sin latencia hasta el siguiente sondeo. El hub nunca bloquea tu aplicación (tiempo de espera de 1,5 s, una solicitud en vuelo, los cambios intermedios se fusionan para que el último valor siempre llegue al final), solo llama a direcciones IP de red privada y elimina la suscripción después de 3 entregas fallidas — volver a suscribirse es idempotente, hazlo cuando quieras. POST /control/unsubscribe { url } la elimina. Push es una adición, no un reemplazo: mantén un sondeo lento (~30 s) como red de seguridad; los contadores de botones hacen que un push perdido sea inofensivo.

Un valor button es un contador de pulsaciones, no una bandera — tu aplicación sondea a su propio ritmo, así que compara con el último contador que viste en lugar de probar si está "pulsado". Cualquier salto hacia atrás significa que el hub se reinició o que el panel se limpió: adopta el valor, no lo leas como un millón de pulsaciones.

Dos ranuras por convención te dan solicitud/respuesta completa: una ranura *_cmd que escribe la IA, una ranura *_result que escribe la aplicación, y un contador *_ack para que cada comando se ejecute exactamente una vez (incrementa el id del comando cada vez; la aplicación omite cualquier id que ya haya manejado).

Ese es todo el protocolo. Un cliente solo necesita una biblioteca HTTP que ya tienes.

Ejemplo real — una IA controlando Autodesk Fusion 360

Un complemento de Fusion 360 de ~30 líneas (solo urllib, sin SDK) sondea GET /control, ejecuta el comando en el hilo principal de Fusion y publica el resultado de vuelta. Sin nada más, un asistente de IA condujo Fusion para diseñar paramétricamente un recinto 3D completo — bocetos, extrusiones, cúpulas de tornillo con insertos de calor, recortes USB-C, orificios de reinicio/botón — verificando cada paso al leer de vuelta la geometría real de las caras.

El patrón es universal: cualquier cosa que pueda hacer POST y GET — Blender, un controlador CNC, un juego, un hub de automatización del hogar — se vuelve controlable por IA con unas pocas líneas y sin servidor personalizado. Dos reglas de seguridad se trasladan de esa construcción:

• APIs de GUI de un solo hilo: el bucle de sondeo nunca debe tocar la API de la aplicación directamente. Dispara un evento y ejecuta el comando en el hilo principal (el patrón oficial de Fusion; lo mismo aplica para cualquier API de UI/COM que no sea segura para hilos).
• Idempotencia: rastrea el último id manejado y confírmalo — el sondeo significa que verás el mismo comando repetidamente, así que omite lo que ya has hecho.

Panel de depuración

La transmisión de registros en desplazamiento es excelente para qué pasó y cuándo — pero inútil para valores rápidos y repetitivos (niveles de audio, llenado de búfer, FPS, lecturas de sensores). El Panel de depuración es lo opuesto: un panel de ranuras fijas donde cada valor tiene un lugar permanente y se sobrescribe en su lugar en lugar de desplazarse. En vivo en la pestaña En vivo del Visor, con estilo de monitor de hardware (MSI Afterburner / HWiNFO).

Se basa en el mismo servidor Log Hub — sin configuración adicional. Tu programa envía actualizaciones de widgets mediante HTTP POST; enviar el mismo id de nuevo actualiza ese widget.

Tipos de widgets

Enviar un widget

# A single widget — id is the fixed slot, type is required on first send
curl -X POST http://localhost:3335/panel -H "Content-Type: application/json" \
  -d '{"id":"mic","type":"plot","value":0.73,"group":"Audio","label":"Mic Level","unit":"dB"}'

# A gauge with threshold zones (green < warn < yellow < crit < red)
curl -X POST http://localhost:3335/panel -H "Content-Type: application/json" \
  -d '{"id":"gpu_temp","type":"gauge","value":67,"min":0,"max":100,"warn":75,"crit":90,"group":"Hardware"}'

Campos: id (obligatorio), type (label/progress/gauge/plot/slider/number/toggle/button, obligatorio en el primer envío), value (número, cadena de estado o matriz de números para un marco de gráfico completo), group, label, unit, min, max, warn, crit, color, order. Puntos finales: POST /panel (uno), POST /panels (lote), POST /panel/clear ({id} para uno, vacío para todos).

Ciclo de vida

• El servidor mantiene el último estado por id, por lo que un Visor recién abierto o recargado muestra todo el panel de inmediato.
• Las tarjetas sin actualización durante ~3 s se atenúan como "obsoletas".
• Limpiar es un reinicio completo: vacía el almacenamiento. Una fuente solo reaparece si envía widgets con su type de nuevo (las actualizaciones simples solo de valor a una identificación limpiada se ignoran).
• Protegido contra presión de retroceso — un navegador lento no puede hacer que la cola de envío del servidor crezca sin límite.

Pruébalo — la demostración integrada

Una exhibición lista para ejecutar anima todos los tipos de widgets (forma de onda de audio, medidores de GPU que se desplazan por sus zonas, un generador de señales que cicla seno → diente de sierra → triángulo → cuadrado, picos de latencia):

# 1. Start the Log Hub + Viewer from your AI assistant:
#      aidex_log({ action: "init" })
#      aidex_viewer({ path: "." })       → click the Live tab
# 2. Run the demo (from the AiDex repo root):
node scripts/demo-dashboard.mjs           # endless loop, Ctrl+C to stop (clears on exit)

O usa el botón ▷ Demo en la pestaña En vivo — copia el comando de ejecución a tu portapapeles; pégalo en una terminal. (El navegador no puede iniciar un proceso por sí mismo.) Se encuentra en la barra de herramientas incluso mientras el panel está vacío, ya que es cómo obtienes tus primeros widgets. scripts/demo-dashboard.ps1 es un lanzador de un solo comando que verifica el Log Hub primero.

Ejecutarlo dos veces inicia dos instancias que pelean por los mismos widgets (parpadeo visible) — detén el anterior (Ctrl+C) antes de iniciar otro.

Capturas de pantalla — Optimizadas para LLM

Toma capturas de pantalla y redúcelas hasta un 95% para el contexto del LLM. Una captura típica pasa de ~100 KB a ~5 KB — eso son miles de tokens ahorrados por imagen.

Por qué esto importa

La mayoría de las capturas de pantalla en contexto de IA son para leer texto — mensajes de error, registros, etiquetas de UI. No necesitas 16 millones de colores para eso.

Uso

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

Parámetros de optimización

Estrategia recomendada para asistentes de IA

La descripción de la herramienta les dice a los LLM que optimicen automáticamente:

1. Empieza agresivo: scale: 0.5, colors: 2 (lo más pequeño posible)
2. Si es ilegible: reintenta con colors: 16 (agrega sombreado para elementos de UI)
3. Si aún no está claro: prueba con scale: 0.75 o color completo
4. Recuerda: guarda en caché lo que funciona por ventana/aplicación para el resto de la sesión

De esta manera, la IA aprende la configuración correcta por aplicación sin desperdiciar tokens en imágenes sobredimensionadas.

Características

• 5 modos de captura: Pantalla completa, ventana activa, ventana específica (por título), selección interactiva de región, rectángulo basado en coordenadas
• Multiplataforma: Windows (PowerShell + System.Drawing), macOS (sips + ImageMagick), Linux (ImageMagick)
• Multi-monitor: Selecciona qué monitor capturar
• Retraso: Espera N segundos antes de capturar (por ejemplo, para abrir un menú primero)
• Informe de tamaño: Muestra tamaño original → optimizado y porcentaje ahorrado
• Ruta automática: Guarda por defecto en el directorio temporal con nombre de archivo fijo
• Sin índice requerido: Funciona de forma independiente, sin .aidex/ necesario

Visor interactivo

Explora tu proyecto indexado visualmente en el navegador:

aidex_viewer({ path: "." })

Abre http://localhost:3333 con:

• Árbol de archivos interactivo - Haz clic para expandir directorios
• Firmas de archivos - Haz clic en cualquier archivo para ver sus tipos y métodos
• Recarga en vivo - Los cambios se detectan automáticamente mientras codificas
• Iconos de estado de Git - Ve qué archivos están modificados, en etapa de preparación o sin rastrear
• Pestaña de búsqueda - Búsqueda semántica / exacta / híbrida en código, documentos, tareas y notas, con la capa LLM opcional (traducir + reclasificar)
• Pestaña En vivo - Panel de depuración en vivo: widgets de ranuras fijas (gráficos, medidores, progreso) más controles deslizantes, interruptores y botones interactivos que impulsan un programa en ejecución de vuelta a través del canal /control
• Pestaña de registros - Transmisión de registros en vivo desde Log Hub con filtros (nivel, fuente, búsqueda de texto)
• Pestaña de tareas - Ve y gestiona tu lista de tareas pendientes
• Pestaña de configuración - Configura incrustaciones y el proveedor de LLM (el interruptor de privacidad está desactivado por defecto)

Panel de depuración — en vivo, bidireccional

La pestaña En vivo es un panel en vivo con ranuras fijas: envía el mismo id de nuevo y el valor se actualiza en su lugar en lugar de desplazarse. Los widgets interactivos slider/number/toggle/button fluyen de vuelta a la fuente (HTTP /control, o aidex_log control_set para que la IA también pueda ajustar un programa en ejecución). Un button lleva un contador de pulsaciones, no una bandera, para que una fuente que sondea a su propio ritmo nunca pierda un clic. Guía completa: docs/loghub-panel-dashboard.md.

El grupo Controles contiene uno de cada tipo interactivo: un control deslizante, dos interruptores y un botón con su contador de pulsaciones al lado. Más abajo, varias fuentes comparten el mismo panel — el hub no sabe nada sobre lo que significa cada valor, por lo que un firmware de sintetizador y un script de demostración coexisten sin que ninguno sea consciente del otro:

Los controles deslizantes reaccionan en tiempo real — mira el GIF:

El resto del Visor

Cierra con aidex_viewer({ path: ".", action: "close" })

Uso de CLI

aidex scan Q:/develop       # Find all indexed projects
aidex init ./myproject      # Index a project from command line

aidex-mcp funciona como un alias para aidex.

Rendimiento

Tecnología

• Analizador: Tree-sitter - Análisis real, no regex
• Base de datos: SQLite con modo WAL - Rápido, archivo único, cero configuración
• Protocolo: MCP - Funciona con cualquier IA compatible

Estructura del proyecto

.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

Comunidad

Discusiones de GitHub — Haz preguntas, comparte tu configuración, sugiere ideas.

Contribuir

Consulta CONTRIBUTING.md para detalles completos. Resumen rápido:

• ¿Error? → Abre un problema
• ¿Idea? → Inicia una discusión
• ¿Nuevo idioma? → Agrega un archivo de palabras clave en src/parser/languages/ y abre un PR

Licencia

Licencia MIT - consulta LICENCIA

Autores

Uwe Chalas y Claude