codeindex

Structural code intelligence over MCP: find where a symbol is defined, read one function, see what calls it, trace imports and judge what a change breaks, across 40+ languages, without reading whole files.

GitHub

Try this MCPSponsored

Documentation

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  │
 │ (Claude,    │   16 tools, JSON-RPC    │  (Zig binary) │
 │  Cursor…)   │                         │              │
 └─────────────┘                         └──────┬───────┘
                                                │
                                   tree-sitter parse (40+ langs)
                                         trigram + word index
                                         dependency graph
                                         snapshot persistence

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

# 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

# Claude Code — the plugin is the one-step path. It ships the skill, the hook
# 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 %
`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 16 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
`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

codeindex --mcp                          # Run as MCP server (stdio)
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

codeindex auto-detects the project root by walking up from the working directory looking for .git, package.json, Cargo.toml, go.mod, build.zig, pyproject.toml, etc.

It refuses to index your entire home directory or the filesystem root — pass --workspace to be explicit.

Architecture

Parser: tree-sitter with 40+ grammars, compiled into a single binary
Index: trigram index for fuzzy text search + inverted word index for exact identifier lookup
Dependency graph: file-level import resolution with forward and reverse edges
Version store: tracks file changes with sequence numbers for incremental updates
Live watcher: re-indexes on file create/modify/delete (background thread in MCP mode). inotify on Linux; a polling walk on macOS and Windows, which compares mtime and size every couple of seconds. status reports which backend is live as watcher_backend.
Snapshot: persists the full index to .codeindex.json, so a restart loads the snapshot instead of re-indexing
MCP server: JSON-RPC over stdio, implements the MCP 2024-11-05 protocol

Platform support

Every row is built by CI and its tests are run on that platform, except where noted. status reports the live watcher backend so it is never a guess.

	binary	tests run in CI	watcher	install.sh	plugin
Linux x86_64	Yes	Yes	inotify	Yes	Yes
Linux aarch64	Yes	cross-compiled	inotify	Yes	Yes
macOS aarch64	Yes	Yes	polling	Yes	Yes
macOS x86_64	Yes	cross-compiled	polling	Yes	Yes
Windows x86_64	Yes	Yes	polling	needs a shell	see below
Windows aarch64	Yes	cross-compiled	polling	needs a shell	see below

On Windows, install.sh and the plugin's launcher are shell scripts, so they need Git Bash, MSYS2 or Cygwin — they detect it and resolve the right .exe asset. The plugin registers its server through that launcher, so a native Windows Claude Code without a shell should register the binary directly:

claude mcp add -s user codeindex -- C:\path\to\codeindex.exe --mcp

Nothing here is signed or notarized. On macOS a binary fetched with curl runs without a Gatekeeper prompt; one downloaded through a browser is quarantined, and xattr -d com.apple.quarantine codeindex clears it.

Building from source

Requires Zig 0.16.0.

cd zig
./fetch-vendor.sh    # Clone tree-sitter + 40 grammar repos
zig build -Doptimize=ReleaseFast
# Binary: zig/zig-out/bin/codeindex

Run tests:

cd zig && zig build test-bin && ./zig-out/bin/test

zig build test routes results through the build runner's IPC protocol on stdout, which the linked tree-sitter C sources corrupt via their debug printf paths. Building the test binary and running it directly is the same tests without that protocol in the way.

How it compares

	codeindex	ast-grep	ctags	LSIF	Sourcegraph
MCP-native	Yes	No	No	No	No
Token-efficient	Yes (outlines, not full files)	No	Partial	Yes	Yes
Single binary	Yes	Yes	Yes	No	No (server)
Live watcher	Yes (inotify / polling)	No	No	No	No
Dependency graph	Yes	No	No	Yes	Yes
Blast radius	Yes (transitive)	No	No	No	Partial
Refactor planner	Yes (`plan_change`)	No	No	No	No
Languages	40+	20+	50+	Varies	Varies

Pairs with chat-recall

codeindex answers questions about the code in front of you. chat-recall answers questions about the work you already did — it indexes your Claude Code, Gemini CLI, Codex, OpenCode and Antigravity sessions into one searchable history and exposes that over MCP too.

Together they cover both halves of what an agent forgets: codeindex stops it re-reading files it could have outlined, and chat-recall stops it redoing work it already finished. chat-recall detects a codeindex binary on your PATH and registers four extra code-intelligence tools when it finds one — neither requires the other.

License

MIT. See LICENSE.