{ "markdown": "\"codeindex\"\n\n[![npm](https://img.shields.io/npm/v/%40munhq%2Fcodeindex?label=npm&color=cb3837)](https://www.npmjs.com/package/@munhq/codeindex)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.munhq%2Fcodeindex-000)](https://registry.modelcontextprotocol.io/v0/servers?search=codeindex)\n[![Smithery](https://img.shields.io/badge/Smithery-munhq%2Fcodeindex-7c3aed)](https://smithery.ai/servers/munhq/codeindex)\n[![Glama](https://img.shields.io/badge/Glama-munhq%2Fcodeindex-4f46e5)](https://glama.ai/mcp/servers/munhq/codeindex)\n[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n\n[![Install in Cursor](https://img.shields.io/badge/Install-Cursor-000?logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=codeindex&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtdW5ocS9jb2RlaW5kZXgiXX0=)\n[![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)\n\nA structural code intelligence engine that runs as an **MCP server** for AI coding agents.\n\nIt 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**.\n\n```\n ┌─────────────┐ MCP (stdio) ┌───────────┐ ┌──────────────────┐\n │ AI Agent │ ◄─────────────► │ codeindex │ socket │ codeindex daemon │\n │ (Claude, │ 16 tools, │ (relay) │ ◄────────► │ one per │\n │ Cursor…) │ JSON-RPC └───────────┘ │ workspace │\n └─────────────┘ └────────┬─────────┘\n ┌─────────────┐ MCP (stdio) ┌───────────┐ │\n │ AI Agent │ ◄─────────────► │ codeindex │ ◄───────────────────┘\n │ (session 2)│ │ (relay) │ tree-sitter parse (40+ langs)\n └─────────────┘ └───────────┘ trigram + word index\n dependency graph\n one file watcher\n snapshot persistence\n```\n\nEvery session on a repository speaks plain stdio MCP, as before. Behind that,\nthey share one index: the tree is parsed once, watched once and written once,\nhowever many agents are attached. Eight sessions on one repository used to be\neight copies of the same index, eight file watchers and eight writers of the\nsame snapshot; measured on a 720-file project, each session went from 87 MB to\n7 MB, against one shared 77 MB daemon.\n\n## Why\n\nAI 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.\n\nOne `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.\n\n## Quickstart\n\nThe shortest path, if you have Node 18+. Nothing else to install, no key, no\nconfig — the package is a 4 KB wrapper that fetches the binary for your platform\nand verifies it against the published checksums:\n\n```bash\nclaude mcp add codeindex -- npx -y @munhq/codeindex\n```\n\nNo Node, or you want the skill and the hook as well:\n\n```bash\n# Prebuilt binary + skill + MCP registration, in one command\ncurl -fsSL https://raw.githubusercontent.com/munhq/codeindex/main/install.sh | sh\n\n# Or build from source:\ncd zig && ./fetch-vendor.sh && zig build -Doptimize=ReleaseFast\n```\n\nDocker, for hosts that install MCP servers as images. The workspace is\nbind-mounted read-only; codeindex never writes to it:\n\n```bash\ndocker run -i --rm -v \"$PWD:/workspace:ro\" munhq/codeindex\n```\n\nRegister with your AI agent:\n\n```bash\n# Claude Code — the plugin is the one-step path. It ships the skill, both\n# routing hooks and the MCP server together, and its launcher finds or fetches\n# the binary.\nclaude plugin marketplace add munhq/codeindex\nclaude plugin install codeindex@codeindex\n\n# Without the plugin (or for a different MCP client), register the binary\n# directly. Do not do both: two registrations mean two servers, two copies of\n# every tool schema, and two writers on one snapshot. install.sh detects the\n# plugin and skips this step when it is present.\nclaude mcp add -s user codeindex -- ~/.local/bin/codeindex --mcp\n\n# Cursor / Claude Desktop / other MCP clients: add to your config\n{\n \"mcpServers\": {\n \"codeindex\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@munhq/codeindex\"]\n }\n }\n}\n```\n\nEvery listing points at the same server: npm `@munhq/codeindex`, the official MCP\nregistry as `io.github.munhq/codeindex`, and Smithery as `munhq/codeindex`.\n\nThe next time your agent starts, codeindex indexes your project in the background and serves structural queries.\n\n## MCP Tools\n\n| Tool | What it does |\n|------|-------------|\n| `status` | Index stats: file count, symbol count, indexing state, token savings %, the indexed `workspace` and whether a `watcher` is live |\n| `search` | Trigram-accelerated full-text search across all indexed files |\n| `find_symbol` | Find symbol definitions (functions, structs, classes…) by name |\n| `find_word` | Exact word/identifier lookup in the inverted word index |\n| `find_callers` | Approximate callers of a symbol (heuristic, no full name resolution) |\n| `get_outline` | Structural outline of a file (symbols, line counts) |\n| `get_tree` | Directory tree with file metadata |\n| `get_imports` | What files does a given file import/depend on |\n| `get_imported_by` | Reverse dependencies — who imports this file |\n| `get_change_impact` | Transitive blast radius: what breaks if a file changes |\n| `plan_change` | Full refactor plan for a symbol or file — definitions, callers, file role, literals, blast radius |\n| `get_hot_files` | Recently changed files sorted by recency |\n| `read_file` | Read file contents with optional line range |\n| `read_symbol` | Read just a symbol's source code (with optional context lines) |\n| `index_workspace` | Index or re-index a workspace directory |\n| `analyze` | Run one of 16 code analyses (see below) |\n\n### Analyses (`analyze` tool)\n\n| Analysis | What it finds |\n|----------|--------------|\n| `security` | Hardcoded secrets, SQL injection patterns, unsafe blocks, eval usage |\n| `dead_code` | Unreferenced files and symbols |\n| `unwrap_audit` | `.unwrap()` / panic-prone error handling (Rust) |\n| `test_coverage` | Files without test coverage |\n| `architecture` | Architectural smells — god modules, circular deps, islands |\n| `crossref` | Cross-file symbol references |\n| `type_drift` | Type signature mismatches across modules |\n| `db_schema` | Database schema drift between migrations and code |\n| `migration_parity` | Missing migrations for schema changes |\n| `manifest_compliance` | package.json / Cargo.toml / go.mod compliance issues |\n| `literal_scan` | Hardcoded URLs, IPs, ports, absolute paths, TODOs |\n| `coupling` | Module coupling metrics |\n| `cycles` | Circular dependency detection |\n| `duplication` | Reinvented free functions — the same job written twice |\n| `clones` | Copy-pasted function bodies, ignoring names and whitespace |\n| `health` | Roll-up of the analyses above into one index-health report |\n\n## Supported Languages\n\n**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.\n\n## Configuration\n\n```bash\ncodeindex --mcp # Run as MCP server (stdio)\ncodeindex --mcp --no-daemon # ...without sharing the workspace daemon\ncodeindex --daemon-idle-secs 0 # Keep the daemon resident indefinitely\ncodeindex --workspace ./my-project # Index a specific directory\ncodeindex --project-id my-project # Project identifier\ncodeindex -v # Print version\ncodeindex -h # Print help\n\n# Environment variables\nCODEINDEX_WORKSPACE=/path/to/project # Same as --workspace\nCODEINDEX_PROJECT_ID=my-project # Same as --project-id\n```\n\n### Getting it used\n\nA server that registers without telling an agent when to reach for it stays\nidle, and an idle index saves nothing however cheap its calls are. The plugin\nships three things for that, in the order they act:\n\n1. **A SessionStart brief.** About 240 tokens, once per session, in a repository\n that holds source files: codeindex is live, and here is the tool for each\n kind of code question. It lands before the agent has chosen a tool, which is\n the only moment that can change the first choice.\n2. **A PreToolUse hint.** Fires on the 1st, 8th and 25th code question of a\n session, when a scan is about to answer something the index answers better,\n and names the tool for that exact question. It matches `Bash` as well as\n `Read`/`Grep`/`Glob`, because a permission mode that routes file work through\n the shell is where most scans actually happen.\n3. **The skill**, which the model loads when it decides the task calls for it.\n\nAdvice loses to habit, so the narrow case where the index is strictly better is\nrefused rather than argued with: an identifier search that is the whole command\nline, in a project that has been indexed before. It never refuses a file read —\nthe bytes are required before an `Edit` — never refuses a line that also builds\nor tests, and stops refusing after three times in a session, so it can never be\nthe reason a session cannot proceed.\n\nThat is **on by default**, and it is one switch to turn off — no file to edit by\nhand. It is a plugin option, so `/plugin` shows it as \"Refuse a scan the index\nanswers better\" and Claude Code passes your answer to the hook. Outside the\nplugin, or for a single session, `CODEINDEX_ENFORCE=0` in the environment\noverrides the option and `CODEINDEX_ENFORCE=1` restores it.\n\nMeasure the effect rather than assuming it: `python3 plugin/measure_routing.py`\ncounts, per session, how many code questions went to a scan and how many went to\nthe index, across every Claude Code home on the machine.\n\n### Which tree gets indexed\n\nIn `--mcp` mode the working directory belongs to the client, not to you, and it\nis regularly not your project: Claude Code launches a plugin's MCP server from\nthe plugin's own directory and a user-scope server from its config directory. So\nthe workspace is resolved in this order, and the first usable answer wins:\n\n1. `--workspace` or `CODEINDEX_WORKSPACE`. An explicit answer is never overridden.\n2. `CLAUDE_PROJECT_DIR`, which Claude Code sets in every MCP server it spawns.\n3. The launch directory, walking up for a `.git`, `package.json`, `Cargo.toml`,\n `go.mod`, `build.zig` or `pyproject.toml` marker.\n4. The client's MCP `roots`. The server asks for them at the handshake whenever\n the root above was a guess, and adopts one when the guess was refused or lands\n outside every root the client reports. `notifications/roots/list_changed` is\n honoured too, so a directory added with `--add-dir` can still rescue a session.\n\n`status` reports the effective root as `workspace`, and whether a file watcher is\nrunning as `watcher`. Check them when a result looks empty: an index of the wrong\ntree answers every question just as confidently as the right one.\n\nIt refuses to index your entire home directory, the filesystem root, or a folder\nthat merely holds several independent repositories. A refused workspace answers\nevery query with the reason and the one call that fixes it — `index_workspace`\nwith the project path — rather than with \"no results\".\n\n## Architecture\n\n- **Parser**: tree-sitter with 40+ grammars, compiled into a single binary\n- **Index**: trigram index for fuzzy text search + inverted word index for exact identifier lookup\n- **Dependency graph**: file-level import resolution with forward and reverse edges\n- **Version store**: tracks file changes with sequence numbers for incremental updates\n- **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`.\n- **Snapshot**: persists the full index to `.codeindex.json`, so a restart loads the snapshot instead of re-indexing\n- **MCP server**: JSON-RPC over stdio, implements the MCP 2024-11-05 protocol\n- **Workspace daemon**: the first session on a repository starts a background\n daemon and becomes a relay onto it; later sessions just connect. A Unix-domain\n socket on Linux, macOS and Windows 10 1803+, in `$XDG_RUNTIME_DIR/codeindex`\n (or a per-user directory under `TMPDIR`), named by a hash of the workspace\n **and the binary version** — so a rebuilt binary never inherits the previous\n version's daemon. It exits after 15 minutes with no session attached. Anything\n that goes wrong falls back to indexing in-process, which is what happened\n before the daemon existed. Turn it off with `--no-daemon`.\n\n## Platform support\n\nEvery row is built by CI and its tests are run on that platform, except where\nnoted. `status` reports the live watcher backend so it is never a guess.\n\n| | binary | tests run in CI | watcher | install.sh | plugin |\n|---|---|---|---|---|---|\n| Linux x86_64 | Yes | Yes | inotify | Yes | Yes |\n| Linux aarch64 | Yes | cross-compiled | inotify | Yes | Yes |\n| macOS aarch64 | Yes | Yes | polling | Yes | Yes |\n| macOS x86_64 | Yes | cross-compiled | polling | Yes | Yes |\n| Windows x86_64 | Yes | Yes | polling | needs a shell | see below |\n| Windows aarch64 | Yes | cross-compiled | polling | needs a shell | see below |\n\nOn Windows, `install.sh` and the plugin's launcher are shell scripts, so they\nneed Git Bash, MSYS2 or Cygwin — they detect it and resolve the right `.exe`\nasset. The plugin registers its server through that launcher, so a native\nWindows Claude Code without a shell should register the binary directly:\n\n```\nclaude mcp add -s user codeindex -- C:\\path\\to\\codeindex.exe --mcp\n```\n\nNothing here is signed or notarized. On macOS a binary fetched with `curl` runs\nwithout a Gatekeeper prompt; one downloaded through a browser is quarantined,\nand `xattr -d com.apple.quarantine codeindex` clears it.\n\n## Building from source\n\nRequires [Zig 0.16.0](https://ziglang.org/download/).\n\n```bash\ncd zig\n./fetch-vendor.sh # Clone tree-sitter + 40 grammar repos\nzig build -Doptimize=ReleaseFast\n# Binary: zig/zig-out/bin/codeindex\n```\n\nRun tests:\n\n```bash\ncd zig && zig build test-bin && ./zig-out/bin/test\n```\n\n`zig build test` routes results through the build runner's IPC protocol on\nstdout, which the linked tree-sitter C sources corrupt via their debug printf\npaths. Building the test binary and running it directly is the same tests\nwithout that protocol in the way.\n\n## How it compares\n\n| | codeindex | ast-grep | ctags | LSIF | Sourcegraph |\n|---|-----------|---------|------|------|-------------|\n| **MCP-native** | Yes | No | No | No | No |\n| **Token-efficient** | Yes (outlines, not full files) | No | Partial | Yes | Yes |\n| **Single binary** | Yes | Yes | Yes | No | No (server) |\n| **Live watcher** | Yes (inotify / polling) | No | No | No | No |\n| **Dependency graph** | Yes | No | No | Yes | Yes |\n| **Blast radius** | Yes (transitive) | No | No | No | Partial |\n| **Refactor planner** | Yes (`plan_change`) | No | No | No | No |\n| **Languages** | 40+ | 20+ | 50+ | Varies | Varies |\n\n## Pairs with chat-recall\n\ncodeindex answers questions about the code in front of you. **[chat-recall](https://github.com/munhq/chat-recall)** answers questions about the work you already did — it indexes your Claude Code, Gemini CLI, Codex, OpenCode, Antigravity and Cursor sessions into one searchable history and exposes that over MCP too.\n\nTogether 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.\n\n## License\n\nMIT. See [LICENSE](LICENSE).", "bytes": 16514, "sha": "0ad61d512a79b40ab4b2a3b8617f0ad4678244600ed21e0075b25af5b79012af", "repo_slug": "munhq/codeindex", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_munhq_codeindex_7af4cbdd/readme" }