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

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

# 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

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

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

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

npm install -g aidex-mcp

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

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

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

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

## AiDex - Persistent Code Index (MCP Server)

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

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

**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: "" })` — 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:

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

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

### Global Search (across all projects)

### Screenshots

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### Why this matters

| | Raw Screenshot | Optimized (scale=0.5, colors=2) |
|---|---|---|
| **File size** | ~100-500 KB | ~5-15 KB |
| **Tokens consumed** | ~5,000-25,000 | ~250-750 |
| **Text readable?** | Yes | Yes |
| **Colors** | 16M (24-bit) | 2 (black & white) |

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

### Usage

### Optimization parameters

| Parameter | Values | Description |
|-----------|--------|-------------|
| `scale` | 0.1 - 1.0 | Scale factor (0.5 = half resolution). Most HiDPI screens are 2-3x anyway. |
| `colors` | 2, 4, 16, 256 | Color reduction. 2 = black & white, ideal for text screenshots. |

### Recommended strategy for AI assistants

The tool description tells LLMs to optimize automatically:

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

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

### Features

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

## Interactive Viewer

Explore your indexed project visually in the browser:

Opens `http://localhost:3333` with:
- **Interactive file tree** - Click to expand directories
- **File signatures** - Click any file to see its types and methods
- **Live reload** - Changes detected automatically while you code
- **Git status icons** - See which files are modified, staged, or untracked
- **Search tab** - Semantic / exact / hybrid search across code, docs, tasks & notes, with the optional LLM layer (translate + rerank)
- **Live tab** - Live Debug Dashboard: fixed-slot widgets (plots, gauges, progress) plus interactive sliders, switches and buttons that drive a running program back through the `/control` channel
- **Logs tab** - Live log stream from Log Hub with filters (level, source, text search)
- **Tasks tab** - View and manage your task backlog
- **Settings tab** - Configure embeddings & the LLM provider (privacy switch defaults to off)

### Debug Dashboard — live, two-way

The Live tab is a live dashboard with fixed slots: send the same `id` again and the value updates **in place** instead of scrolling away. Interactive `slider`/`number`/`toggle`/`button` widgets flow back to the source (HTTP `/control`, or `aidex_log control_set` so the AI can tune a running program too). A `button` carries a press **counter**, not a flag, so a source polling at its own pace never misses a click. Full guide: [docs/loghub-panel-dashboard.md](docs/loghub-panel-dashboard.md).

![The Live Dashboard — plots, gauges and the four interactive control types side by side](docs/loghub-dashboard-top.png)

The Controls group holds one of each interactive type: a slider, two toggles, and a button with its press counter beside it. Scrolled further down, several sources share the same dashboard — the hub knows nothing about what any value means, so a synth firmware and a demo script coexist without either being aware of the other:

![Further down the same dashboard — gauges, plots and controls from several sources at once](docs/loghub-dashboard.png)

The sliders react in real time — [watch the GIF](docs/loghub-dashboard.gif):

![Tuning sliders drive the live waveform plots](docs/loghub-dashboard.gif)

### The rest of the Viewer

![AiDex Viewer - Semantic & hybrid search](docs/viewer-search.png)

![AiDex Viewer - Settings (embeddings & LLM)](docs/viewer-settings.png)

![AiDex Viewer - Tasks](docs/viewer-tasks.png)

![AiDex Viewer - Code signatures](docs/viewer-code.png)

![AiDex Viewer - Signatures](docs/aidex-viewer.png)

![AiDex Viewer - Overview](docs/aidex-viewer-overview.png)

Close with `aidex_viewer({ path: ".", action: "close" })`

## CLI Usage

> `aidex-mcp` works as an alias for `aidex`.

## Performance

| Project | Files | Items | Index Time | Query Time |
|---------|-------|-------|------------|------------|
| Small (AiDex) | 19 | 1,200 | <1s | 1-5ms |
| Medium (RemoteDebug) | 10 | 1,900 | <1s | 1-5ms |
| Large (LibPyramid3D) | 18 | 3,000 | <1s | 1-5ms |
| XL (MeloTTS) | 56 | 4,100 | ~2s | 1-10ms |

## Technology

- **Parser**: [Tree-sitter](https://tree-sitter.github.io/) - Real parsing, not regex
- **Database**: SQLite with WAL mode - Fast, single file, zero config
- **Protocol**: [MCP](https://modelcontextprotocol.io/) - Works with any compatible AI

## Project Structure

## Community

**[GitHub Discussions](https://github.com/CSCSoftware/AiDex/discussions)** — Ask questions, share your setup, suggest ideas.

| Category | For |
|----------|-----|
| [Q&A](https://github.com/CSCSoftware/AiDex/discussions/new?category=q-a) | Setup help, usage questions |
| [Ideas](https://github.com/CSCSoftware/AiDex/discussions/new?category=ideas) | Feature suggestions |
| [Show & Tell](https://github.com/CSCSoftware/AiDex/discussions/new?category=show-and-tell) | Share your workflow |
| [Announcements](https://github.com/CSCSoftware/AiDex/discussions) | Release news (maintainer only) |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for full details. Quick summary:

- **Bug?** → [Open an issue](https://github.com/CSCSoftware/AiDex/issues/new?template=bug_report.yml)
- **Idea?** → [Start a Discussion](https://github.com/CSCSoftware/AiDex/discussions/new?category=ideas)
- **New language?** → Add a keyword file in `src/parser/languages/` and open a PR

## License

MIT License - see [LICENSE](LICENSE)

## Authors

Uwe Chalas & Claude