AiDex

AiDex

O cérebro persistente para agentes de codificação com IA.

AiDex é um servidor MCP que dá aos assistentes de codificação com IA memória, busca semântica e telemetria ao vivo — local-first, agnóstico de modelo. Funciona com qualquer assistente de IA compatível com MCP: Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot e outros.

Três Pilares

🧠 Memória — Tarefas, notas e notas de sessão sobrevivem a cada chat. Histórico registrado automaticamente, tarefas agendadas, continuidade entre sessões. Sua IA sabe amanhã o que importou hoje.

🔍 Busca — Três modos: exact (identificador), semantic (conceito), hybrid (fusão RRF de ambos). Incorpora código, documentação e itens do workspace em um único ranking. Entre projetos — cada repositório em uma única consulta. Camada LLM opcional traduz consultas em outros idiomas e reordena resultados.

🌐 Telemetria — LogHub recebe logs ao vivo de qualquer aplicativo via HTTP (sem SDK). A IA observa o que seu código realmente faz, não apenas o que ele diz. Transmitido ao vivo no Viewer.

O Que Há Dentro — 33 Ferramentas em Um Servidor

14 linguagens — C#, TypeScript, JavaScript, Rust, Python, C, C++, Java, Go, PHP, Ruby, HCL/Terraform, Kotlin, Swift — além de frontmatter 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" })

Sumário

• O Que Há Dentro
• Busca Semântica e Camada LLM 🆕
• O Problema
• A Solução
• Por Que Não Apenas Grep?
• Como Funciona
• Recursos
• Linguagens Suportadas
• Início Rápido
• Ferramentas Disponíveis
• Filtragem Baseada em Tempo
• Estrutura do Projeto
• Notas de Sessão
• Backlog de Tarefas
• Busca Global
• Diretrizes de IA
• Log Hub
• Painel de Depuração
• Capturas de Tela — Otimizadas para LLM
• Viewer Interativo
• Uso via CLI
• Desempenho
• Tecnologia
• Contribuindo
• Licença

Busca Semântica e Camada LLM

v2.0 adicionou busca semântica via embeddings executados localmente — sua IA pode encontrar uma função mesmo sem saber o identificador exato.

Três modos — escolha a ferramenta certa para a pergunta

O que é incorporado

• Código — cada método e tipo, fragmentação em três níveis (assinatura + comentário de documentação + saco de identificadores ponderado)
• Documentação — seções Markdown (README, CHANGELOG, docs/, arquivos de plano), divididas nos limites de cabeçalho
• Workspace — tarefas, logs de tarefas, notas de sessão, histórico de notas arquivadas

Um ranking, todos os tipos. Uma consulta como "como escrever logs a partir de programas externos" traz a seção ## Log Hub do README primeiro, depois o método log em commands/log.ts, e então qualquer tarefa relacionada.

Configuração

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

Ou use a aba Configurações no Viewer (aidex_settings({ path: ".", open: true })) — alternâncias para embeddings, provedor de LLM, modelo e o interruptor de privacidade.

Camada LLM opcional

Quando uma chave de API Anthropic / OpenAI / OpenRouter / Ollama / HuggingFace está configurada, o AiDex pode:

• Traduzir consultas em outros idiomas → "wie speichere ich Logs lokal" encontra o código certo
• Expandir consultas vagas em 2-4 subconsultas concretas (mescladas via RRF)
• Reordenar os candidatos de recuperação top-N

O interruptor de privacidade llm_send_code tem como padrão desligado — apenas sua consulta literal e metadados (caminhos, nomes, âncoras) são enviados. Os corpos de código permanecem locais. Por projeto, fácil de verificar nas Configurações.

Local-first: funciona totalmente offline com embeddings puros. A camada LLM é opcional, nunca obrigatória.

O Problema

Toda vez que seu assistente de IA busca por código, ele:

• Usa grep em milhares de arquivos → centenas de resultados inundam o contexto
• Lê arquivo após arquivo para entender a estrutura → mais contexto consumido
• Esquece tudo quando a sessão termina → repete do zero

Uma única pergunta "Onde X está definido?" pode consumir 2.000+ tokens. Faça isso 10 vezes e você queimou metade do seu contexto apenas com navegação.

A Solução

Indexe uma vez, consulte para sempre:

# 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 navegação de código.

Por Que Não Apenas Grep?

O custo real do grep: Cada resultado de grep inclui contexto ao redor. Busque por User em um projeto grande e você terá centenas de resultados — comentários, strings, correspondências parciais. Sua IA lê todos eles, queimando tokens de contexto com ruído.

AiDex indexa identificadores: Ele usa Tree-sitter para realmente analisar seu código. Quando você busca por User, obtém a definição da classe, os parâmetros do método, as declarações de variáveis — não todos os comentários que mencionam "user".

Como Funciona

1. Indexe seu projeto uma vez (~1 segundo por 1000 arquivos)

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

2. A IA busca no índice em vez 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. Obtenha visões gerais de arquivos sem ler arquivos inteiros

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

O índice vive em .aidex/index.db (SQLite) — rápido, portátil, sem dependências externas.

Recursos

• Análise Tree-sitter: Análise real de código, não regex — indexa identificadores, ignora palavras-chave e ruído
• ~50 Tokens por Busca: vs 2000+ com grep — sua IA mantém o contexto para o trabalho real
• Índice Persistente: Sobrevive entre sessões — sem re-escaneamento, sem releitura
• Atualizações Incrementais: Re-indexe arquivos individuais após alterações, não o projeto inteiro
• Filtragem Baseada em Tempo: Encontre o que mudou na última hora, dia ou semana
• Limpeza Automática: Arquivos excluídos (ex.: saídas de build) são removidos automaticamente do índice
• Zero Dependências: SQLite com modo WAL — arquivo único, rápido, portátil

Linguagens Suportadas

Início Rápido

Pré-requisitos

• Node.js ≥ 20 (verifique com node --version)
  • macOS: brew install node ou nvm install 20 && nvm use 20
  • Linux: use seu gerenciador de pacotes ou nvm
  • Windows: nodejs.org
  • Se você usa nvm, o repositório inclui um .nvmrc — nvm use escolhe a versão certa automaticamente.

1. Instalação

npm install -g aidex-mcp

É isso. A configuração é executada automaticamente após a instalação — ela detecta seus clientes de IA instalados (Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot) e registra o AiDex como servidor MCP. Ela também adiciona instruções de uso à configuração da sua IA (~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md).

Para reexecutar a configuração manualmente: aidex setup | Para cancelar o registro: aidex unsetup | Para pular a configuração automática: AIDEX_NO_SETUP=1 npm install -g aidex-mcp

2. Ou registre manualmente com seu assistente de IA

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

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

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

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

Nota: Tanto aidex quanto aidex-mcp funcionam como nomes de comando.

Importante: O nome do servidor na sua configuração determina o prefixo da ferramenta MCP. Use "aidex" como mostrado acima — isso dá nomes de ferramentas como aidex_query, aidex_signature, etc. Usar um nome diferente (ex.: "codegraph") mudaria o prefixo de acordo.

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

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

Para VS Code Copilot (execute MCP: Open User Configuration na Paleta de Comandos):

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

Para outros clientes MCP: Consulte a documentação do seu cliente para configuração de servidor MCP.

3. Faça sua IA realmente usar

Adicione às instruções do seu IA (por exemplo, ~/.claude/CLAUDE.md para Claude Code, ou o equivalente para seu cliente de IA). Isso informa ao IA quando e como usar AiDex em vez 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

Quero pesquisar código? ├── .aidex/ existe → PARE! Use AiDex ├── .aidex/ ausente → execute aidex_init (não pergunte), DEPOIS use AiDex └── Config/Logs/Texto → Grep/Read é suficiente

**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: "Testar a correção após reiniciar" }) # Escrever aidex_note({ path: ".", note: "Verificar também casos extremos", append: true }) # Acrescentar aidex_note({ path: "." }) # Ler aidex_note({ path: ".", search: "parser" }) # Pesquisar histórico aidex_note({ path: ".", clear: true }) # Limpar

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

Tarefas agendadas e recorrentes

aidex_task({ path: ".", action: "create", title: "Verificar status do 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: "/caminho/para/todos/os/repos" }) # Escanear e registrar aidex_global_init({ path: "...", index_unindexed: true }) # + indexar automaticamente projetos pequenos aidex_global_query({ term: "TransparentWindow", mode: "contains" }) # Pesquisar em todos os lugares aidex_global_signatures({ term: "Render", kind: "method" }) # Encontrar métodos em todos os lugares aidex_global_status({ sort: "recent" }) # Listar todos os projetos

### Screenshots

aidex_screenshot() # Tela cheia aidex_screenshot({ mode: "active_window" }) # Janela ativa aidex_screenshot({ mode: "window", window_title: "VS Code" }) # Janela específica aidex_screenshot({ scale: 0.5, colors: 2 }) # P&B, metade do tamanho (ideal para LLM) aidex_screenshot({ colors: 16 }) # 16 cores (UI legível) aidex_windows({ filter: "chrome" }) # Encontrar títulos de janelas

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. Indexe seu projeto

Pergunte ao seu IA: "Indexe este projeto com AiDex"

Ou manualmente no chat do IA:

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

Ferramentas Disponíveis

Filtragem por Tempo

Acompanhe o que mudou recentemente com modified_since e 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 suportados:

• Relativo: 30m (minutos), 2h (horas), 1d (dias), 1w (semanas)
• Data ISO: 2026-01-27 ou 2026-01-27T14:30:00

Perfeito para perguntas como "O que eu mudei na última hora?"

Estrutura do Projeto

AiDex indexa TODOS os arquivos do seu projeto (não apenas código), permitindo consultar a estrutura:

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 arquivo: code, config, doc, asset, test, other, dir

Use modified_since para encontrar arquivos alterados nesta sessão — perfeito para "O que eu editei?"

Notas de Sessão

Deixe lembretes para a próxima sessão — sem perder contexto entre conversas:

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

Histórico de Notas (v1.10): Notas antigas são arquivadas automaticamente quando sobrescritas ou limpas. Navegue e pesquise notas passadas:

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

Resumos de Notas (v1.15): Forneça um summary ao escrever/limpar uma nota — a nota arquivada recebe esta descrição de uma frase. O histórico então mostra resumos em vez de texto truncado:

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

Casos de uso:

• Antes de encerrar uma sessão: "Lembre-se de testar X na próxima vez"
• Lembrete automático do IA: Salvar o que verificar após reiniciar
• Notas de transferência: Contexto para a próxima sessão sem editar arquivos de configuração
• Pesquisar sessões passadas: "O que fizemos sobre o parser?"

As notas são armazenadas no banco de dados SQLite (.aidex/index.db) e persistem indefinidamente.

Backlog de Tarefas

Mantenha as tarefas do seu projeto ao lado do índice de código — sem Jira, sem Trello, sem troca 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" })

Tarefas Agendadas e Recorrentes

Tarefas podem ter datas de vencimento e intervalos de repetição. Tarefas atrasadas são reportadas a cada início de sessão em TODOS os projetos:

# 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 vencimento: Relativo ("30m", "2h", "3d", "1w") ou data ISO ("2026-04-10")

A cada chamada de aidex_session, o Agendador de Tarefas verifica ~/.aidex/global.db para tarefas vencidas em todos os projetos — mesmo se você estiver trabalhando em um projeto diferente. Tarefas recorrentes avançam automaticamente sua data de vencimento após cada acionamento.

Recursos:

• Resumos: Sumário de uma frase por tarefa — escaneie o backlog sem ler detalhes completos
• Prioridades: 🔴 alta, 🟡 média, ⚪ baixa
• Status: backlog → active → done | cancelled
• Tags: Categorize tarefas (bug, feature, docs, etc.)
• Histórico: Cada mudança de status é registrada automaticamente, além de notas manuais
• Agendamento: Datas de vencimento, intervalos recorrentes, ações, execução automática em todos os projetos
• Integração com Viewer: Aba de tarefas no viewer do navegador com atualizações ao vivo
• Persistência: Tarefas sobrevivem entre sessões, armazenadas em .aidex/index.db

Seu assistente de IA pode criar tarefas enquanto trabalha ("encontrei um bug no parser, adicione ao backlog"), acompanhar o progresso e retomar de onde parou na próxima sessão.

Pesquisa Global

Pesquise em TODOS os seus projetos indexados de uma vez. Perfeito para "Já escrevi uma janela transparente?" ou "Onde usei aquele algoritmo?"

Configuração

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

Isso escaneia seu diretório de projetos, registra todos os projetos indexados por AiDex em um banco de dados global (~/.aidex/global.db) e reporta quaisquer projetos não indexados que encontrar, detectando marcadores de projeto (.csproj, package.json, Cargo.toml, etc.).

Com index_unindexed: true, também indexa automaticamente todos os projetos descobertos com ≤500 arquivos de código. Projetos maiores são listados separadamente para decisão do usuário. Adicione show_progress: true para abrir uma UI de progresso ao vivo no seu navegador (http://localhost:3334).

Pesquisa

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

Como funciona

• Usa SQLite ATTACH DATABASE para consultar bancos de dados de projetos diretamente — sem cópia de dados
• Resultados são armazenados em cache na memória (TTL de 5 minutos) para consultas repetidas rápidas
• Projetos são processados em lotes (8 por vez) para respeitar o limite de anexos do SQLite
• Cada projeto mantém seu próprio .aidex/index.db como fonte única de verdade
• Desduplicação automática: Projetos pai que contêm subprojetos são automaticamente ignorados (por exemplo, MyApp/ é removido quando MyApp/Frontend/ e MyApp/Backend/ existem como projetos indexados separados)

Gerenciamento

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

Diretrizes de IA

Armazene convenções de codificação persistentes, listas de verificação de revisão e instruções de IA em um único lugar — compartilhadas entre todos os projetos.

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 verificação de revisão de código: Diga ao seu IA exatamente o que procurar a cada vez
• Convenções de codificação: Armazene regras de estilo da equipe uma vez, referencie-as em qualquer projeto
• Lista de verificação de lançamento: Processo passo a passo para publicação
• Instruções independentes de projeto: Sem mais colar o mesmo contexto em toda sessão

As diretrizes são armazenadas em ~/.aidex/global.db — disponíveis em todos os seus projetos sem aidex_init. Pergunte ao seu IA: "Carregue a diretriz de revisão e aplique-a a este arquivo."

Log Hub — Registro Universal

Transforme qualquer programa em uma fonte de logs para seu assistente de IA. Seu aplicativo envia logs via HTTP POST, o IA os consulta via MCP, e você os vê ao vivo no Viewer — zero dependências, zero configuração no seu código.

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

Início rápido

1. O IA inicia o Log Hub: aidex_log({ action: "init" })
2. O IA abre o Viewer: aidex_viewer({ path: "." }) — a aba Logs mostra a transmissão ao vivo
3. Adicione uma linha ao seu 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 (nome do aplicativo), message (texto, obrigatório), data (JSON opcional), timestamp (opcional, ms)

Recursos

• Ring Buffer: FIFO em memória de tamanho fixo (padrão 10.000 entradas) — entradas mais antigas são sobrescritas
• Custo zero: Sem servidor, sem buffer, sem recursos até que init seja chamado
• Persistência: Armazenamento SQLite opcional com limpeza automática de 7 dias (persist: true)
• Padrão de consumo: query com consume: true remove as entradas retornadas — ideal para polling
• Integração com Viewer: Aba de logs com transmissão ao vivo via WebSocket, filtros de nível/fonte/texto, rolagem automática
• Fire & forget: Basta enviar POST e seguir — se o servidor não estiver rodando, o POST falha silenciosamente

API de Controle — deixe o IA dirigir seu aplicativo

Logs e widgets de dashboard fluem aplicativo → IA. A API de Controle é o canal de retorno: IA → aplicativo. Ela transforma o Log Hub em um barramento de comandos minúsculo e sem dependências — para que um assistente de IA possa dirigir qualquer programa em execução sem você escrever um servidor.

O IA define um comando; seu aplicativo faz polling, executa e envia o resultado de volta:

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 } — o IA (ou um slider/switch do Viewer) define um slot de controle.
• GET /control — seu aplicativo lê todos os valores de controle atuais.
• POST /control — seu aplicativo envia de volta resultados / confirmações.
• POST /control/press { id } — registra um pressionamento de um controle button. O hub é dono do contador, então pressionamentos de vários dashboards abertos se somam em vez de se sobrescreverem.
• control_get — o IA lê o que o aplicativo reportou.
• POST /control/subscribe (opcional) — push em vez de polling, veja abaixo. Prefira push em vez de poll. Se o seu aplicativo tiver seu próprio servidor HTTP, ele pode assinar uma vez com { "port": 8080 } (o hub chama de volta o endereço do remetente, o caminho padrão é /control) ou um { "url": "http://192.168.1.50:8080/control" } completo, opcionalmente limitado a { "ids": [...] }. A partir daí, cada alteração é enviada via POST para essa URL imediatamente, como o mesmo mapa { id: value } achatado que GET /control retorna. Sem requisições ociosas, sem latência até o próximo poll. O hub nunca bloqueia seu aplicativo (timeout de 1,5 s, uma requisição em voo, alterações intermediárias são mescladas para que o valor mais recente sempre chegue por último), só chama endereços IP de rede privada e encerra a assinatura após 3 entregas com falha — reassinar é idempotente, faça quando quiser. POST /control/unsubscribe { url } remove. Push é um acréscimo, não uma substituição: mantenha um poll lento (~30 s) como rede de segurança; contadores de botão tornam um push perdido inofensivo.

Um valor button é um contador de pressionamentos, não um sinalizador — seu aplicativo faz poll no seu próprio ritmo, então compare com a última contagem que você viu em vez de testar se foi "pressionado". Qualquer salto para trás significa que o hub reiniciou ou o painel foi limpo: adote o valor, não o leia como um milhão de pressionamentos.

Duas slots por convenção oferecem request/response completo: uma slot *_cmd que a IA escreve, uma slot *_result que o aplicativo escreve e um contador *_ack para que cada comando seja executado exatamente uma vez (incremente o id do comando toda vez; o aplicativo ignora qualquer id que já tenha tratado).

Esse é todo o protocolo. Um cliente não precisa de nada além de uma biblioteca HTTP que você já tem.

Exemplo real — uma IA controlando o Autodesk Fusion 360

Um add-in do Fusion 360 com ~30 linhas (apenas urllib, sem SDK) faz poll em GET /control, executa o comando na thread principal do Fusion e publica o resultado de volta. Sem mais nada, um assistente de IA dirigiu o Fusion para projetar parametricamente um invólucro 3D completo — sketches, extrusões, boss de rosca com insertos de heat-set, recortes USB-C, furos de reset/botão — verificando cada etapa ao reler a geometria real das faces.

O padrão é universal: qualquer coisa que possa fazer POST e GET — Blender, um controlador CNC, um jogo, um hub de automação residencial — torna-se controlável por IA com algumas linhas e sem servidor personalizado. Duas regras de segurança vêm dessa construção:

• APIs de GUI de thread única: o loop de poll nunca deve tocar na API do aplicativo diretamente. Dispare um evento e execute o comando na thread principal (o padrão oficial do Fusion; o mesmo vale para qualquer API de UI/COM não segura para threads).
• Idempotência: rastreie o último id tratado e confirme-o — fazer poll significa que você verá o mesmo comando repetidamente, então pule o que já fez.

Painel de Depuração

O fluxo de log rolante é ótimo para o que aconteceu quando — mas inútil para valores rápidos e repetitivos (níveis de áudio, preenchimento de buffer, FPS, leituras de sensores). O Painel de Depuração é o oposto: um painel de slots fixos onde cada valor tem um lugar permanente e sobrescreve no lugar em vez de rolar para fora. Ao vivo na aba Ao Vivo do Viewer, estilizado como um monitor de hardware (MSI Afterburner / HWiNFO).

Ele usa o mesmo servidor Log Hub — sem configuração extra. Seu programa envia atualizações de widgets via HTTP POST; enviar o mesmo id novamente atualiza esse widget.

Tipos de widget

Enviar um 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 (obrigatório), type (label/progress/gauge/plot/slider/number/toggle/button, obrigatório no primeiro envio), value (número, string de status ou array de números para um quadro de plotagem completo), group, label, unit, min, max, warn, crit, color, order. Endpoints: POST /panel (um), POST /panels (lote), POST /panel/clear ({id} para um, vazio para todos).

Ciclo de vida

• O servidor mantém o último estado por id, então um Viewer recém-aberto ou recarregado mostra o painel inteiro imediatamente.
• Cartões sem atualização por ~3 s ficam cinza como "obsoletos".
• Limpar é uma redefinição completa: esvazia o armazenamento. Uma fonte só reaparece se enviar widgets com seu type novamente (atualizações simples apenas de valor para um id limpo são ignoradas).
• Protegido contra backpressure — um navegador lento não pode fazer a fila de envio do servidor crescer sem limite.

Experimente — a demo integrada

Uma demonstração pronta para executar anima todos os tipos de widget (forma de onda de áudio, medidores de GPU oscilando por suas zonas, um gerador de sinal alternando seno → dente de serra → triângulo → quadrado, picos de latência):

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

Ou use o botão ▷ Demo na aba Ao Vivo — ele copia o comando de execução para sua área de transferência; cole-o em um terminal. (O navegador não pode iniciar um processo sozinho.) Ele fica na barra de ferramentas mesmo enquanto o painel ainda está vazio, pois é assim que você obtém seus primeiros widgets. scripts/demo-dashboard.ps1 é um lançador de comando único que verifica o Log Hub primeiro.

Executá-lo duas vezes inicia duas instâncias que disputam os mesmos widgets (flicker visível) — pare o antigo (Ctrl+C) antes de iniciar outro.

Capturas de Tela — Otimizadas para LLM

Tire capturas de tela e reduza-as em até 95% para contexto de LLM. Uma captura típica vai de ~100 KB para ~5 KB — isso é uma economia de milhares de tokens por imagem.

Por que isso importa

A maioria das capturas de tela em contexto de IA é para ler texto — mensagens de erro, logs, rótulos de UI. Você não precisa de 16 milhões de cores para isso.

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 otimização

Estratégia recomendada para assistentes de IA

A descrição da ferramenta diz aos LLMs para otimizar automaticamente:

1. Comece agressivo: scale: 0.5, colors: 2 (menor possível)
2. Se ilegível: tente novamente com colors: 16 (adiciona sombreamento para elementos de UI)
3. Se ainda pouco claro: tente scale: 0.75 ou cor total
4. Lembre-se: armazene em cache o que funciona por janela/aplicativo para o resto da sessão

Dessa forma, a IA aprende as configurações certas por aplicativo sem desperdiçar tokens em imagens superdimensionadas.

Recursos

• 5 modos de captura: Tela cheia, janela ativa, janela específica (por título), seleção interativa de região, retângulo baseado em coordenadas
• Multiplataforma: Windows (PowerShell + System.Drawing), macOS (sips + ImageMagick), Linux (ImageMagick)
• Multi-monitor: Selecione qual monitor capturar
• Atraso: Aguarde N segundos antes de capturar (por exemplo, para abrir um menu primeiro)
• Relatório de tamanho: Mostra tamanho original → otimizado e porcentagem economizada
• Caminho automático: Salva por padrão no diretório temporário com nome de arquivo fixo
• Sem índice necessário: Funciona de forma autônoma, sem .aidex/

Viewer Interativo

Explore seu projeto indexado visualmente no navegador:

aidex_viewer({ path: "." })

Abre http://localhost:3333 com:

• Árvore de arquivos interativa - Clique para expandir diretórios
• Assinaturas de arquivos - Clique em qualquer arquivo para ver seus tipos e métodos
• Recarga ao vivo - Alterações detectadas automaticamente enquanto você codifica
• Ícones de status Git - Veja quais arquivos estão modificados, em stage ou não rastreados
• Aba de busca - Busca semântica / exata / híbrida em código, docs, tarefas e notas, com a camada LLM opcional (tradução + rerank)
• Aba Ao Vivo - Painel de Depuração ao Vivo: widgets de slots fixos (gráficos, medidores, progresso) além de sliders, interruptores e botões interativos que controlam um programa em execução de volta pelo canal /control
• Aba Logs - Fluxo de log ao vivo do Log Hub com filtros (nível, fonte, busca de texto)
• Aba Tarefas - Veja e gerencie seu backlog de tarefas
• Aba Configurações - Configure embeddings e o provedor de LLM (interruptor de privacidade desligado por padrão)

Painel de Depuração — ao vivo, bidirecional

A aba Ao Vivo é um painel ao vivo com slots fixos: envie o mesmo id novamente e o valor atualiza no lugar em vez de rolar para fora. Widgets interativos slider/number/toggle/button fluem de volta para a fonte (HTTP /control, ou aidex_log control_set para que a IA também possa ajustar um programa em execução). Um button carrega um contador de pressionamentos, não um sinalizador, para que uma fonte que faz poll no seu próprio ritmo nunca perca um clique. Guia completo: docs/loghub-panel-dashboard.md.

O grupo Controles contém um de cada tipo interativo: um slider, dois interruptores e um botão com seu contador de pressionamentos ao lado. Rolando mais para baixo, várias fontes compartilham o mesmo painel — o hub não sabe o que cada valor significa, então um firmware de sintetizador e um script de demonstração coexistem sem que um saiba do outro:

Os sliders reagem em tempo real — veja o GIF:

O resto do Viewer

Feche com aidex_viewer({ path: ".", action: "close" })

Uso via CLI

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

aidex-mcp funciona como um alias para aidex.

Desempenho

Tecnologia

• Parser: Tree-sitter - Parsing real, não regex
• Banco de dados: SQLite com modo WAL - Rápido, arquivo único, zero configuração
• Protocolo: MCP - Funciona com qualquer IA compatível

Estrutura do Projeto

.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

Comunidade

Discussões no GitHub — Faça perguntas, compartilhe sua configuração, sugira ideias.

Contribuindo

Veja CONTRIBUTING.md para detalhes completos. Resumo rápido:

• Bug? → Abra uma issue
• Ideia? → Inicie uma Discussão
• Novo idioma? → Adicione um arquivo de palavras-chave em src/parser/languages/ e abra um PR

Licença

Licença MIT - veja LICENSE

Autores

Uwe Chalas & Claude