AiDex

Prerequisites

• Node.js ≥ 18 (check with node --version)
• macOS: brew install node or nvm install 18 && nvm use 18
• Linux: use your package manager or nvm
• Windows: nodejs.org
• If you use nvm, the repo ships a .nvmrc — nvm use picks the right version automatically.

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

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

Setup

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

Or use the Settings tab in the Viewer (aidex_settings({ path: ".", open: true })) — toggles for embeddings, LLM provider, model, and the privacy switch.

1. Install

npm install -g aidex-mcp

That's it. Setup runs automatically after install — it detects your installed AI clients (Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot) and registers AiDex as an MCP server. It also adds usage instructions to your AI's config (~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md).

To re-run setup manually: aidex setup | To unregister: aidex unsetup | To skip auto-setup: AIDEX_NO_SETUP=1 npm install -g aidex-mcp

Setup

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

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

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

Quick Start

AI Guidelines

Store persistent coding conventions, review checklists, and AI instructions in a single place — shared across all projects.

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

Use cases: - Code review checklist: Tell your AI exactly what to look for every time - Coding conventions: Store team style rules once, reference them in any project - Release checklist: Step-by-step process for shipping - Project-agnostic instructions: No more pasting the same context into every session

Guidelines are stored in ~/.aidex/global.db — available across all your projects without aidex_init. Ask your AI: "Load the review guideline and apply it to this file."

Quick start

1. AI starts the Log Hub: aidex_log({ action: "init" })
2. AI opens the Viewer: aidex_viewer({ path: "." }) — Logs tab shows live stream
3. Add one line to your program:

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

```python

Usage

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

CLI Usage

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

aidex-mcp works as an alias for aidex.

Screenshots

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

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. ```

Try it — the built-in demo

A ready-to-run showcase animates all widget types (audio waveform, GPU gauges drifting through their zones, a signal generator cycling sine → sawtooth → triangle → square, latency spikes):

```bash

2. Run the demo (from the AiDex repo root):

node scripts/demo-dashboard.mjs # endless loop, Ctrl+C to stop (clears on exit) ```

Or use the ▷ Demo button on the Debug tab — it copies the run command to your clipboard; paste it into a terminal. (The browser can't spawn a process itself.) scripts/demo-dashboard.ps1 is a one-command launcher that checks the Log Hub first.

Running it twice starts two instances that fight over the same widgets (visible flicker) — stop the old one (Ctrl+C) before starting another.

Screenshots — LLM-Optimized

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

Optional LLM layer

When an Anthropic / OpenAI / OpenRouter / Ollama / HuggingFace API key is configured, AiDex can:

• Translate non-English queries → "wie speichere ich Logs lokal" finds the right code
• Expand vague queries into 2-4 concrete subqueries (RRF-merged)
• Rerank top-N retrieval candidates

Privacy switch llm_send_code defaults to off — only your literal query and metadata (paths, names, anchors) are sent. Code bodies stay local. Per-project, easy to verify in Settings.

Local-first: works fully offline with pure embeddings. The LLM layer is opt-in, never required.

HTTP API

Fields: level (debug/info/warn/error), source (app name), message (text, required), data (optional JSON), timestamp (optional, ms)

Three modes — pick the right tool for the question

Question → Right Tool