codeindex

Repo dependency analyzer with blast-radius impact scoring and symbol indexing for AI-assisted development.

Point it at any project — Python, JavaScript/TypeScript, Go, Ruby, Rust, Java, PHP, and more — and get:

• A codeindex.json dependency index written directly into your repo
• Per-file blast-radius scores (how many files break if this one changes)
• A symbolindex.json symbol map so AI can find any function/class without scanning every file
• Five ways to consume the data: CLI, markdown report, MCP server, pre-commit hook, CLAUDE.md injection
• An interactive visualization UI (2D/3D graphs, dependency matrix, treemap)

No build step. No npm. Pure Python stdlib — zero required dependencies.

Install

pip install codeindex

Or from source:

git clone https://github.com/scheidydude/codeindex
cd codeindex
pip install -e .

Quickstart

# Build the dependency index
codeindex analyze ./myapp

# Build the symbol index (where every function and class lives)
codeindex symbols ./myapp

# See blast radius for a file before touching it
codeindex impact src/auth.py

# Launch the visualization UI
codeindex serve --viz --repo ./myapp
open http://localhost:8080

Commands

codeindex analyze

codeindex analyze [REPO_PATH] [--output PATH] [--watch]

Analyzes the repo and writes codeindex.json to the repo root. Detects 12+ languages automatically.

| Flag | Default | Description | |------|---------|-------------| | REPO_PATH | . | Path to repo root | | --output | <repo>/codeindex.json | Override output path | | --watch | off | Re-index on file changes (requires watchdog) |

codeindex symbols

codeindex symbols [REPO_PATH] [--output PATH] [--inline] [--index PATH]
                  [--claude-md] [--claude-md-path PATH] [--all-symbols]

Builds a symbol index — a map of every function, class, struct, and type to its exact file and line number. Lets AI tools (and humans) find any symbol in one lookup instead of scanning the entire repo.

Modes:

| Flag | Description | |------|-------------| | (none) | Write a standalone symbolindex.json | | --inline | Embed symbols into each node in codeindex.json instead | | --claude-md | Append a compressed symbol summary to CLAUDE.md |

Both --inline and --claude-md can be combined in a single run.

Options:

| Flag | Default | Description | |------|---------|-------------| | REPO_PATH | . | Path to repo root | | --output | <repo>/symbolindex.json | Output path (standalone mode) | | --index | auto-discovered | Path to codeindex.json (for --inline) | | --claude-md-path | <repo>/CLAUDE.md | Override CLAUDE.md path | | --all-symbols | off | Include non-exported symbols in CLAUDE.md (default: exported only) |

Examples:

# Standalone symbol index
codeindex symbols ./myapp

# Embed into codeindex.json (one file for blast radius + symbols)
codeindex symbols ./myapp --inline

# Write CLAUDE.md summary so Claude Code loads symbols automatically
codeindex symbols ./myapp --claude-md

# All three at once
codeindex symbols ./myapp --inline --claude-md

# Re-generate when code changes
codeindex symbols ./myapp --inline --claude-md

Why it matters: Claude Code and other AI tools normally scan every file to find a function definition. With a symbol index, Claude can load one file, do an O(1) lookup, and open only the relevant file — cutting token usage 60–90% on symbol-location tasks.

CLAUDE.md injection is opt-in because it increases base context size on every prompt. Use it when symbol lookups are frequent in your workflow; skip it for simple tasks where the overhead outweighs the benefit.

codeindex impact

codeindex impact FILE [--index PATH] [--out FILE] [--json]

Shows the blast-radius impact for a specific file: direct dependents, transitive dependents, blast score, and risk level.

Impact: src/auth.py
Blast Score: 8.5  (2 direct · 7 transitive)  [HIGH]

Direct dependents (2)
  src/api.py
  src/middleware.py

Transitive dependents (5 additional)
  src/main.py  ← src/api.py
  src/app.py   ← src/middleware.py
  ...

Risk: HIGH — affects 7/42 files (16.7% of codebase)

Blast score formula: direct + (0.5 × transitive)

| Flag | Description | |------|-------------| | --index PATH | Path to codeindex.json (auto-discovered if omitted) | | --out FILE | Write a markdown report to this file | | --json | Output raw JSON |

codeindex serve

codeindex serve --viz [--repo PATH] [--port PORT] [--watch]
codeindex serve --mcp

--viz launches an interactive visualization UI in your browser (5 modes: 2D force graph, 3D network, dependency matrix, treemap, infrastructure graph).

--mcp starts a stdio MCP server that exposes codeindex tools directly to Claude and other MCP clients.

MCP tools:

| Tool | Description | |------|-------------| | analyze_repo | Build or refresh the dependency index | | get_impact | Blast-radius report for a file | | get_dependencies | imports + imported-by for a file | | get_high_blast_files | All files above a blast score threshold | | build_symbol_index | Build or refresh the symbol index | | lookup_symbol | Find where any function/class/type is defined (file + line) |

Claude Code MCP config (.claude/settings.json):

{
  "mcpServers": {
    "codeindex": {
      "command": "codeindex",
      "args": ["serve", "--mcp"]
    }
  }
}

codeindex lookup

codeindex lookup SYMBOL [--index PATH] [--json]

Finds where a function, class, struct, or other symbol is defined. O(1) lookup against symbolindex.json — no file scanning.

$ codeindex lookup compute_blast_radius
codeindex/impact.py:6  (function)

$ codeindex lookup AuthService
src/auth.py:44  (class)  methods: login, logout, refresh

| Flag | Description | |------|-------------| | --index PATH | Path to symbolindex.json (auto-discovered if omitted) | | --json | Output raw JSON |

codeindex dependencies

codeindex dependencies FILE [--index PATH] [--json]

Shows what a file imports and what imports it, plus its blast score.

$ codeindex dependencies src/auth.py
File: src/auth.py  (blast score: 8.5)

Imports (3):
  src/db.py
  src/config.py
  src/utils.py

Imported by (2):
  src/api.py
  src/middleware.py

| Flag | Description | |------|-------------| | --index PATH | Path to codeindex.json (auto-discovered if omitted) | | --json | Output raw JSON |

codeindex high-blast

codeindex high-blast [--threshold N] [--index PATH] [--json]

Lists all files whose blast score exceeds the threshold, sorted by score descending. Useful for identifying the riskiest files before a refactor.

$ codeindex high-blast --threshold 5
Files with blast score ≥ 5.0  (3 found)

  13.0  src/db.py          (12d / 2t)
   8.5  src/auth.py        (3d / 7t)
   5.5  src/config.py      (5d / 1t)

d = direct dependents · t = transitive dependents

| Flag | Default | Description | |------|---------|-------------| | --threshold N | 5 | Minimum blast score to include | | --index PATH | auto-discovered | Path to codeindex.json | | --json | off | Output raw JSON |

codeindex install-hook

codeindex install-hook [--repo PATH] [--threshold N] [--strict] [--remove]

Installs a git pre-commit hook that warns when staged files exceed the blast score threshold.

| Flag | Default | Description | |------|---------|-------------| | --threshold N | 10 | Blast score above which to warn | | --strict | off | Block the commit instead of just warning | | --remove | — | Uninstall the hook |

Using codeindex in another repo with Claude

Three workflows, ordered by automation level.

Workflow 1 — MCP server (recommended for active coding)

Claude gets symbol lookup, dependency, and impact tools it calls automatically. No extra prompting needed.

One-time setup:

cd /your/other/repo
codeindex analyze .
codeindex symbols .

Register the MCP server with Claude Code using claude mcp add. Use --scope project to limit it to this repo, or --scope global to use it everywhere:

# Project-scoped (recommended — stored in .claude/settings.json)
claude mcp add --scope project codeindex -- /path/to/codeindex serve --mcp

# Global (available in all repos)
claude mcp add --scope global codeindex -- /path/to/codeindex serve --mcp

Find the full path to your codeindex binary with which codeindex, then substitute it above.

# Example with conda install
claude mcp add --scope project codeindex -- /opt/homebrew/Caskroom/miniforge/base/bin/codeindex serve --mcp

Verify it registered:

claude mcp list

Note: Do not use "command": "codeindex" with a bare name — Claude Code does not inherit your shell PATH, so the binary won't be found unless you use the absolute path.

Claude now has all 6 MCP tools available in every session. When it needs to find processPayment, it calls lookup_symbol("processPayment") and gets src/billing.py:142 back in one shot — no file scanning.

Keep the index fresh:

# Auto-rebuild on file changes (leave running in a terminal)
codeindex symbols . --watch

Workflow 2 — CLAUDE.md injection (best for repos you revisit often)

Symbol table is embedded in CLAUDE.md so it loads into every session automatically — no tool call needed at all.

cd /your/other/repo
codeindex symbols . --claude-md

This upserts a symbolindex code fence into CLAUDE.md. Every Claude Code session in that repo loads it at startup. Claude can answer "where is X defined?" from context alone with zero tool calls.

Tradeoff: adds ~500–2000 tokens to every prompt depending on repo size. Worth it for repos where symbol lookups are frequent; skip it for