codeindex

<img src="docs/brand/logo.svg" alt="codeindex" width="235" height="70">

[![npm](https://img.shields.io/npm/v/%40munhq%2Fcodeindex?label=npm&color=cb3837)](https://www.npmjs.com/package/@munhq/codeindex)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.munhq%2Fcodeindex-000)](https://registry.modelcontextprotocol.io/v0/servers?search=codeindex)
[![Smithery](https://img.shields.io/badge/Smithery-munhq%2Fcodeindex-7c3aed)](https://smithery.ai/servers/munhq/codeindex)
[![Glama](https://img.shields.io/badge/Glama-munhq%2Fcodeindex-4f46e5)](https://glama.ai/mcp/servers/munhq/codeindex)
[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

[![Install in Cursor](https://img.shields.io/badge/Install-Cursor-000?logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=codeindex&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtdW5ocS9jb2RlaW5kZXgiXX0=)
[![Install in VS Code](https://img.shields.io/badge/Install-VS%20Code-007ACC?logo=visualstudiocode)](vscode:mcp/install?%7B%22name%22%3A%22codeindex%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40munhq%2Fcodeindex%22%5D%7D)

A structural code intelligence engine that runs as an **MCP server** for AI coding agents.

It indexes your codebase with tree-sitter (40+ languages), builds a trigram full-text index, an inverted word index, and a dependency graph — then exposes them through **16 MCP tools**.

```
 ┌─────────────┐   MCP (stdio)   ┌───────────┐            ┌──────────────────┐
 │  AI Agent   │ ◄─────────────► │ codeindex │  socket    │ codeindex daemon │
 │ (Claude,    │ 16 tools,       │  (relay)  │ ◄────────► │  one per         │
 │  Cursor…)   │ JSON-RPC        └───────────┘            │  workspace       │
 └─────────────┘                                          └────────┬─────────┘
 ┌─────────────┐   MCP (stdio)   ┌───────────┐                     │
 │  AI Agent   │ ◄─────────────► │ codeindex │ ◄───────────────────┘
 │  (session 2)│                 │  (relay)  │   tree-sitter parse (40+ langs)
 └─────────────┘                 └───────────┘   trigram + word index
                                                 dependency graph
                                                 one file watcher
                                                 snapshot persistence
```

Every session on a repository speaks plain stdio MCP, as before. Behind that,
they share one index: the tree is parsed once, watched once and written once,
however many agents are attached. Eight sessions on one repository used to be
eight copies of the same index, eight file watchers and eight writers of the
same snapshot; measured on a 720-file project, each session went from 87 MB to
7 MB, against one shared 77 MB daemon.

## Why

AI coding agents spend tokens reading entire files. codeindex answers structural questions — symbol outlines, definitions, callers, blast radius, dependency chains — in a few hundred tokens instead of thousands.

One `plan_change` call returns: where a symbol is defined, every call site, the file's architectural role (god module / stable core / island / driver), hardcoded literals to check, and the full transitive blast radius if the file changes.

## Quickstart

The shortest path, if you have Node 18+. Nothing else to install, no key, no
config — the package is a 4 KB wrapper that fetches the binary for your platform
and verifies it against the published checksums:

```bash
claude mcp add codeindex -- npx -y @munhq/codeindex
```

No Node, or you want the skill and the hook as well:

```bash
# Prebuilt binary + skill + MCP registration, in one command
curl -fsSL https://raw.githubusercontent.com/munhq/codeindex/main/install.sh | sh

# Or build from source:
cd zig && ./fetch-vendor.sh && zig build -Doptimize=ReleaseFast
```

Docker, for hosts that install MCP servers as images. The workspace is
bind-mounted read-only; codeindex never writes to it:

```bash
docker run -i --rm -v "$PWD:/workspace:ro" munhq/codeindex
```

Register with your AI agent:

```bash
# Claude Code — the plugin is the one-step path. It ships the skill, both
# routing hooks and the MCP server together, and its launcher finds or fetches
# the binary.
claude plugin marketplace add munhq/codeindex
claude plugin install codeindex@codeindex

# Without the plugin (or for a different MCP client), register the binary
# directly. Do not do both: two registrations mean two servers, two copies of
# every tool schema, and two writers on one snapshot. install.sh detects the
# plugin and skips this step when it is present.
claude mcp add -s user codeindex -- ~/.local/bin/codeindex --mcp

# Cursor / Claude Desktop / other MCP clients: add to your config
{
  "mcpServers": {
    "codeindex": {
      "command": "npx",
      "args": ["-y", "@munhq/codeindex"]
    }
  }
}
```

Every listing points at the same server: npm `@munhq/codeindex`, the official MCP
registry as `io.github.munhq/codeindex`, and Smithery as `munhq/codeindex`.

The next time your agent starts, codeindex indexes your project in the background and serves structural queries.

## MCP Tools

| Tool | What it does |
|------|-------------|
| `status` | Index stats: file count, symbol count, indexing state, token savings %, the indexed `workspace` and whether a `watcher` is live |
| `search` | Trigram-accelerated full-text search across all indexed files |
| `find_symbol` | Find symbol definitions (functions, structs, classes…) by name |
| `find_word` | Exact word/identifier lookup in the inverted word index |
| `find_callers` | Approximate callers of a symbol (heuristic, no full name resolution) |
| `get_outline` | Structural outline of a file (symbols, line counts) |
| `get_tree` | Directory tree with file metadata |
| `get_imports` | What files does a given file import/depend on |
| `get_imported_by` | Reverse dependencies — who imports this file |
| `get_change_impact` | Transitive blast radius: what breaks if a file changes |
| `plan_change` | Full refactor plan for a symbol or file — definitions, callers, file role, literals, blast radius |
| `get_hot_files` | Recently changed files sorted by recency |
| `read_file` | Read file contents with optional line range |
| `read_symbol` | Read just a symbol's source code (with optional context lines) |
| `index_workspace` | Index or re-index a workspace directory |
| `analyze` | Run one of 21 code analyses (see below) |

### Analyses (`analyze` tool)

| Analysis | What it finds |
|----------|--------------|
| `security` | Hardcoded secrets, SQL injection patterns, unsafe blocks, eval usage |
| `dead_code` | Unreferenced files and symbols |
| `unwrap_audit` | `.unwrap()` / panic-prone error handling (Rust) |
| `test_coverage` | Files without test coverage |
| `architecture` | Architectural smells — god modules, circular deps, islands |
| `crossref` | Cross-file symbol references |
| `type_drift` | Type signature mismatches across modules |
| `db_schema` | Database schema drift between migrations and code |
| `migration_parity` | Missing migrations for schema changes |
| `manifest_compliance` | package.json / Cargo.toml / go.mod compliance issues |
| `literal_scan` | Hardcoded URLs, IPs, ports, absolute paths, TODOs |
| `coupling` | Module coupling metrics |
| `cycles` | Circular dependency detection |
| `duplication` | Reinvented free functions — the same job written twice |
| `clones` | Copy-pasted function bodies, ignoring names and whitespace |
| `spawn_scan` | An interpreter started on a loop or a timer, ranked by startup cost times spawn rate |
| `deps` | Dependency inventory — duplicate versions, unreferenced crates, single-use crates |
| `leak_shapes` | Shapes a leak has, each paired with the runtime series that decides it |
| `logic_shapes` | A fixed byte constant against a declared memory limit, and a round trip per row |
| `field_contention` | One declared-state field written by two or more owners |
| `health` | Roll-up of the analyses above into one index-health report |

## Supported Languages

**40+ languages** via tree-sitter: Rust, Python, TypeScript/TSX, Go, Zig, C, C++, Java, Ruby, Bash, C#, Kotlin, Lua, Scala, Elixir, R, Swift, Dart, Haskell, TOML, JSON, YAML, HTML, CSS, SCSS, SQL, HCL, Dockerfile, Markdown, Nix, Make, and more.

## Configuration

```bash
codeindex --mcp                          # Run as MCP server (stdio)
codeindex --mcp --no-daemon              # ...without sharing the workspace daemon
codeindex --daemon-idle-secs 0           # Keep the daemon resident indefinitely
codeindex --workspace ./my-project       # Index a specific directory
codeindex --project-id my-project        # Project identifier
codeindex -v                             # Print version
codeindex -h                             # Print help

# Environment variables
CODEINDEX_WORKSPACE=/path/to/project     # Same as --workspace
CODEINDEX_PROJECT_ID=my-project          # Same as --project-id
```

### Getting it used

A server that registers without telling an agent when to reach for it stays
idle, and an idle index saves nothing however cheap its calls are. The plugin
ships three things for that, in the order they act:

1. **A SessionStart brief.** About 240 tokens, once per session, in a repository
   that holds source files: codeindex is live, and here is the tool for each
   kind of code question. It lands before the agent has chosen a tool, which is
   the only moment that can change the first choice.
2. **A PreToolUse hint.** Fires on the 1st, 8th and 25th code question of a
   session, when a scan is about to answer something the index answers better,
   and names the tool for that exact question. It matches `Bash` as well as
   `Read`/`Grep`/`Glob`, because a permission mode that routes file work through
   the shell is where most scans actually happen.
3. **The skill**, which the model loads when it decides the task calls for it.

Advice loses to habit, so the narrow case where the index is strictly better is
refused rather than argued with