# AiDex

> Persistent code indexing for AI assistants. 50x less context than grep. 11 languages.

- **Type:** MCP server
- **Install:** `agentstack add mcp-cscsoftware-aidex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [CSCSoftware](https://agentstack.voostack.com/s/cscsoftware)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 1.7.3
- **License:** MIT
- **Upstream author:** [CSCSoftware](https://github.com/CSCSoftware)
- **Source:** https://github.com/CSCSoftware/AiDex
- **Website:** https://www.npmjs.com/package/aidex-mcp

## Install

```sh
agentstack add mcp-cscsoftware-aidex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AiDex

[](https://www.npmjs.com/package/aidex-mcp)
[](LICENSE)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](https://github.com/CSCSoftware/AiDex/discussions)

**The persistent brain for AI coding agents.**

AiDex is an MCP server that gives AI coding assistants a memory, semantic search, and live telemetry — local-first, model-agnostic. Works with any MCP-compatible AI assistant: Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot, and more.

### Three Pillars

🧠 **Memory** — Tasks, notes, and session-notes survive every chat. Auto-logged history, scheduled tasks, cross-session continuity. Your AI knows tomorrow what mattered today.

🔍 **Search** — Three modes: `exact` (identifier), `semantic` (concept), `hybrid` (RRF fusion of both). Embeds code, docs, and workspace items into one ranking. Cross-project — every repo in one query. Optional LLM layer translates non-English queries and reranks results.

🌐 **Telemetry** — LogHub receives live logs from any app via HTTP (no SDK). The AI watches what your code actually does, not just what it says. Live-streamed in the Viewer.

And yes — it's still 50× more token-efficient than grep.

| | Without AiDex | With AiDex |
|---|---|---|
| Find `PlayerHealth` | Grep → 200 hits in 40 files → reads 5 files → **2,000+ tokens** | 1 query → 3 exact locations → **~50 tokens** |
| Get file structure | Reads entire 500-line file → **1,500 tokens** | Signatures → classes + methods → **~80 tokens** |
| What changed today? | `git diff` + grep + context → **3,000+ tokens** | Time-filtered query → **~50 tokens** |

### What's Inside — 33 Tools in One Server

| Category | Tools | What it does |
|----------|-------|--------------|
| **Semantic Search** 🆕 | `search`, `settings` | Hybrid / semantic / exact retrieval over code, docs & workspace. Settings tab to configure embeddings + LLM layer |
| **Index & Identifier Search** | `init`, `query`, `update`, `remove`, `status` | Index your project, search identifiers by name (exact/contains/starts_with), time-based filtering |
| **Signatures** | `signature`, `signatures` | Get classes + methods of any file without reading it — single file or glob pattern |
| **Project Overview** | `summary`, `tree`, `describe`, `files` | Entry points, language breakdown, file tree with stats, file listing by type |
| **Cross-Project** | `link`, `unlink`, `links`, `scan` | Link dependencies, discover indexed projects |
| **Global Search** | `global_init`, `global_query`, `global_signatures`, `global_status`, `global_refresh` | Search identifiers across ALL your projects — "Have I ever written X?" |
| **Guidelines** | `global_guideline` | Persistent AI instructions & coding conventions — shared across all projects |
| **Sessions** | `session`, `note` | Track sessions, detect external changes, leave notes for next session (with searchable history) |
| **Task Backlog** | `task`, `tasks` | Built-in task management with priorities, tags, auto-logged history, and **scheduled/recurring tasks** |
| **Log Hub** | `log` | Universal log receiver — any program sends logs via HTTP, queryable by the AI, live in Viewer |
| **Screenshots** | `screenshot`, `windows` | Cross-platform screen capture with LLM optimization — scale + color reduction saves up to 95% tokens |
| **Viewer** | `viewer` | Interactive browser UI with file tree, signatures, tasks, logs, search, and live reload |

**12 languages** — C#, TypeScript, JavaScript, Rust, Python, C, C++, Java, Go, PHP, Ruby, HCL/Terraform

Quick Examples — see it in action

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

## Table of Contents

- [What's Inside](#whats-inside--33-tools-in-one-server)
- [Semantic Search & LLM Layer](#semantic-search--llm-layer) 🆕
- [The Problem](#the-problem)
- [The Solution](#the-solution)
- [Why Not Just Grep?](#why-not-just-grep)
- [How It Works](#how-it-works)
- [Features](#features)
- [Supported Languages](#supported-languages)
- [Quick Start](#quick-start)
- [Available Tools](#available-tools)
- [Time-based Filtering](#time-based-filtering)
- [Project Structure](#project-structure)
- [Session Notes](#session-notes)
- [Task Backlog](#task-backlog)
- [Global Search](#global-search)
- [AI Guidelines](#ai-guidelines)
- [Log Hub](#log-hub--universal-logging)
- [Debug Dashboard](#debug-dashboard)
- [Screenshots — LLM-Optimized](#screenshots--llm-optimized)
- [Interactive Viewer](#interactive-viewer)
- [CLI Usage](#cli-usage)
- [Performance](#performance)
- [Technology](#technology)
- [Contributing](#contributing)
- [License](#license)

## Semantic Search & LLM Layer

**v2.0** added semantic search via locally-run embeddings — your AI can find a function even when it doesn't know the exact identifier.

### Three modes — pick the right tool for the question

| Mode | What it does | When to use |
|------|--------------|-------------|
| `exact` | Identifier match (same as `aidex_query`) | You know the name. `PlayerHealth` → 3 hits |
| `semantic` | Vector KNN over embedded code+docs+workspace | You know the *concept*. "how do we cache the model" → finds `getQueryEmbedder` |
| `hybrid` (default) | RRF fusion of both | Mixed queries. Robust by default |

### What gets embedded

- **Code** — every method and type, three-tier chunking (signature + doc-comment + weighted identifier bag)
- **Docs** — Markdown sections (README, CHANGELOG, docs/, plan files), split at heading boundaries
- **Workspace** — tasks, task logs, session notes, archived note history

One ranking, all kinds. A query like *"how to write logs from external programs"* surfaces the README's `## Log Hub` section first, then the `log` method in `commands/log.ts`, then any related task.

### Setup

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

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

## The Problem

Every time your AI assistant searches for code, it:
- **Greps** through thousands of files → hundreds of results flood the context
- **Reads** file after file to understand the structure → more context consumed
- **Forgets** everything when the session ends → repeat from scratch

A single "Where is X defined?" question can eat 2,000+ tokens. Do that 10 times and you've burned half your context on navigation alone.

## The Solution

Index once, query forever:

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

**Result: 50-80% less context used for code navigation.**

## Why Not Just Grep?

| | Grep/Ripgrep | AiDex |
|---|---|---|
| **Context usage** | 2000+ tokens per search | ~50 tokens |
| **Results** | All text matches | Only identifiers |
| **Precision** | `log` matches `catalog`, `logarithm` | `log` finds only `log` |
| **Persistence** | Starts fresh every time | Index survives sessions |
| **Structure** | Flat text search | Knows methods, classes, types |

**The real cost of grep**: Every grep result includes surrounding context. Search for `User` in a large project and you'll get hundreds of hits - comments, strings, partial matches. Your AI reads through all of them, burning context tokens on noise.

**AiDex indexes identifiers**: It uses Tree-sitter to actually parse your code. When you search for `User`, you get the class definition, the method parameters, the variable declarations - not every comment that mentions "user".

## How It Works

1. **Index your project once** (~1 second per 1000 files)
   ```
   aidex_init({ path: "/path/to/project" })
   ```

2. **AI searches the index instead of grepping**
   ```
   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. **Get file overviews without reading entire files**
   ```
   aidex_signature({ file: "src/Engine.cs" })
   → All classes, methods, and their signatures
   ```

The index lives in `.aidex/index.db` (SQLite) - fast, portable, no external dependencies.

## Features

- **Tree-sitter Parsing**: Real code parsing, not regex — indexes identifiers, ignores keywords and noise
- **~50 Tokens per Search**: vs 2000+ with grep — your AI keeps its context for actual work
- **Persistent Index**: Survives between sessions — no re-scanning, no re-reading
- **Incremental Updates**: Re-index single files after changes, not the whole project
- **Time-based Filtering**: Find what changed in the last hour, day, or week
- **Auto-Cleanup**: Excluded files (e.g., build outputs) are automatically removed from index
- **Zero Dependencies**: SQLite with WAL mode — single file, fast, portable

## Supported Languages

| Language | Extensions |
|----------|------------|
| C# | `.cs` |
| TypeScript | `.ts`, `.tsx` |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |
| Rust | `.rs` |
| Python | `.py`, `.pyw` |
| C | `.c`, `.h` |
| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx` |
| Java | `.java` |
| Go | `.go` |
| PHP | `.php` |
| Ruby | `.rb`, `.rake` |
| HCL/Terraform | `.tf`, `.tfvars`, `.hcl` |

## Quick Start

### 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](https://github.com/nvm-sh/nvm)
  - Windows: [nodejs.org](https://nodejs.org/)
  - If you use `nvm`, the repo ships a `.nvmrc` — `nvm use` picks the right version automatically.

### 1. Install

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

### 2. Or register manually with your AI assistant

**For Claude Code** (`~/.claude/settings.json` or `~/.claude.json`):
```json
{
  "mcpServers": {
    "aidex": {
      "type": "stdio",
      "command": "aidex",
      "env": {}
    }
  }
}
```

**For Claude Desktop** (`%APPDATA%/Claude/claude_desktop_config.json` on Windows):
```json
{
  "mcpServers": {
    "aidex": {
      "command": "aidex"
    }
  }
}
```

> **Note:** Both `aidex` and `aidex-mcp` work as command names.

> **Important:** The server name in your config determines the MCP tool prefix. Use `"aidex"` as shown above — this gives you tool names like `aidex_query`, `aidex_signature`, etc. Using a different name (e.g., `"codegraph"`) would change the prefix accordingly.

**For Gemini CLI** (`~/.gemini/settings.json`):
```json
{
  "mcpServers": {
    "aidex": {
      "command": "aidex"
    }
  }
}
```

**For VS Code Copilot** (run `MCP: Open User Configuration` in Command Palette):
```json
{
  "servers": {
    "aidex": {
      "type": "stdio",
      "command": "aidex"
    }
  }
}
```

**For other MCP clients**: See your client's documentation for MCP server configuration.

### 3. Make your AI actually use it

Add to your AI's instructions (e.g., `~/.claude/CLAUDE.md` for Claude Code, or the equivalent for your AI client). This tells the AI **when and how** to use AiDex instead of grepping:

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

```
Do I want to search code?
├── .aidex/ exists    → STOP! Use AiDex instead
├── .aidex/ missing   → run aidex_init (don't ask), THEN use AiDex
└── Config/Logs/Text  → Grep/Read is fine
```

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

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [CSCSoftware](https://github.com/CSCSoftware)
- **Source:** [CSCSoftware/AiDex](https://github.com/CSCSoftware/AiDex)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/aidex-mcp

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Versions

- **1.7.3** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cscsoftware-aidex
- Seller: https://agentstack.voostack.com/s/cscsoftware
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.