code-index

code-index

A code indexing and knowledge graph tool for Python and TypeScript/JavaScript. It parses repositories with tree-sitter, builds a graph of symbols and relationships, runs community and flow detection, and exposes semantic + full-text search over that graph.

You can use it from the CLI or through an MCP (Model Context Protocol) server so coding agents can search, trace dependencies, analyze diffs, and plan renames.

Requirements

• Python 3.11+
• uv

Install

./install.sh

This builds the package and installs the code-index binary via uv tool install. Make sure ~/.local/bin is on your PATH.

Quick Setup

After installing, run this inside any git repo:

code-index setup

This does everything in one command:

1. Indexes the repository (builds the knowledge graph)
2. Configures the MCP server (.claude/mcp.json)
3. Enables all MCP tools (.claude/settings.local.json)
4. Installs skills (.claude/skills/)
5. Creates CLAUDE.md with guidelines that enforce MCP usage
6. Updates .gitignore

Options:

code-index setup --force        # re-index even if already indexed
code-index setup --skip-index   # configure Claude Code without re-indexing
code-index setup /path/to/repo  # set up a different repo

Start a new Claude Code session afterward and the knowledge graph is ready to use.

CLI quick reference

Command	Purpose
code-index analyze [path]	Index a repo (writes .code-index/ under the repo root)
code-index analyze --force	Rebuild the index
code-index analyze --no-embeddings	Faster index without FAISS vectors
code-index status	Show index metadata for the current repo
code-index list	List all indexed repositories (registry)
code-index search "query"	Search from the terminal
code-index clean	Remove index data for the current repo
code-index clean --all	Remove all registered indexes
code-index mcp	Start the MCP server on stdio

Indexed data lives in .code-index/ inside each repository. A global registry at ~/.code-index/registry.json tracks which repos have been indexed.

MCP server

The MCP server speaks stdio and registers tools plus code-index:// resources. When a tool runs, the server resolves the repository root by walking up from the host process current working directory until it finds a .code-index/ directory. If none exists, it auto-indexes the repo (same as code-index analyze with embeddings).

Claude Code

The easiest way is code-index setup — it handles everything. For manual setup:

# Option 1: claude mcp add (global)
claude mcp add code-index -- "$(uv tool dir)/code-index/bin/python" -m code_index.server

# Option 2: project .claude/mcp.json
cat > .claude/mcp.json <<EOF
{
  "mcpServers": {
    "code-index": {
      "type": "stdio",
      "command": "$(uv tool dir)/code-index/bin/python",
      "args": ["-m", "code_index.server"]
    }
  }
}
EOF

Tip: If the repo isn't indexed yet, the first tool call will auto-index it. This takes a minute or two for large repos — after that, all queries are instant.

Cursor

Add a server entry to your project .cursor/mcp.json or user MCP settings:

{
  "mcpServers": {
    "code-index": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "<PATH_TO_THIS_REPO>",
        "python",
        "-m",
        "code_index.server"
      ]
    }
  }
}

Replace <PATH_TO_THIS_REPO> with the absolute path to your clone.

Ensure the workspace folder you open in Cursor is inside the codebase you want indexed (or already contains .code-index/), so the server's working directory allows correct repo discovery.

MCP tools

Tool	Role
search	Unified search: known symbol → full context; otherwise hybrid semantic + full-text over the graph
trace_dependencies	Impact / dependency tracing (dependents and/or dependencies, depth, confidence)
diff_analysis	Map a git diff range to affected symbols and processes
rename	Coordinated rename plan (supports dry_run)
list_repos	List repositories present in the index registry
explore_structure	Community clusters plus folder hierarchy
health_check	Staleness, coverage, and health signals

MCP resources (code-index://)

URI pattern	Content
code-index://overview	All indexed repositories
code-index://repo/{name}	Repo context and stats
code-index://repo/{name}/modules	Community modules
code-index://repo/{name}/flows	Execution flows
code-index://repo/{name}/flows/{flow_name}	Single flow detail
code-index://repo/{name}/symbol/{qualified}	Symbol detail (qualified name)
code-index://repo/{name}/metrics	Index health metrics