codeindex

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:

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

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

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

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

Register with your AI agent:

# 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

Analyses (analyze tool)

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

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: an identifier search that is the whole command line, in a project that has been indexed before. It never refuses a file read — the bytes are required before an Edit — never refuses a line that also builds or tests, and stops refusing after three times in a session, so it can never be the reason a session cannot proceed.

That is on by default, and it is one switch to turn off — no file to edit by hand. It is a plugin option, so /plugin shows it as "Refuse a scan the index answers better" and Claude Code passes your answer to the hook. Outside the plugin, or for a single session, CODEINDEX_ENFORCE=0 in the environment overrides the option and CODEINDEX_ENFORCE=1 restores it.

Measure the effect rather than assuming it: python3 plugin/measure_routing.py counts, per session, how many code questions went to a scan and how many went to the index, across every Claude Code home on the machine.

Which tree gets indexed

In --mcp mode the working directory belongs to the client, not to you, and it is regularly not your project: Claude Code launches a plugin's MCP server from the plugin's own directory and a user-scope server from its config directory. So the workspace is resolved in this order, and the first usable answer wins:

1. --workspace or CODEINDEX_WORKSPACE. An explicit answer is never overridden.
2. CLAUDE_PROJECT_DIR, which Claude Code sets in every MCP server it spawns.
3. The launch directory, walking up for a .git, `package.jso