codeindex

Temporal code knowledge graph with blast-radius impact scoring, semantic symbol search, and git-history-aware dependency analysis — for AI-assisted development.

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

• A persistent SQLite graph store at <repo>/.codeindex/index.db — incremental, queryable, temporal
• A codeindex.json dependency index written directly into your repo (preserved for backward compatibility)
• Per-file blast-radius scores (how many files break if this one changes), including historical as-of queries
• A symbolindex.json symbol map so AI can find any function/class without scanning every file
• Hybrid semantic search over symbols: natural-language queries fused with keyword + graph expansion
• Git history backfill — temporal graph from commit history without touching the working tree
• Ten ways to consume the data: CLI, markdown report, MCP server (10 tools), pre-commit hook, CLAUDE.md injection
• An interactive visualization UI (2D/3D graphs, dependency matrix, treemap)

No build step. No npm. Zero required runtime dependencies — SQLite is stdlib.

Install

pip install codeindex

Or from source:

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

Quickstart

# Build the dependency index (also writes to .codeindex/index.db)
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

# Search symbols with natural language (no embedding endpoint needed — FTS fallback)
codeindex search "validate auth token"

# See what changed since a release tag
codeindex changed-since v1.2.0

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

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:

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

Options:

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] [--as-of REF]

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)

codeindex search

codeindex search QUERY [--k N] [--as-of REF] [--db PATH] [--json]

Hybrid semantic + keyword + graph symbol search. Finds relevant functions and classes without knowing their exact names.

Retrieval signals fused with Reciprocal Rank Fusion (RRF):

1. Semantic KNN — embedding similarity (requires codeindex[semantic] + a configured endpoint)
2. FTS5 keyword — full-text search over symbol names, signatures, and docstrings
3. Graph expansion — structurally adjacent symbols from dependent/dependency files

Degrades gracefully: if no embedding endpoint is configured, falls back to FTS + graph (no crash, no config needed).

# Keyword + graph search (no embedding setup required)
codeindex search "validate auth token"

# Full semantic search (requires CODEINDEX_EMBEDDING_* env vars)
CODEINDEX_EMBEDDING_ENDPOINT=http://localhost:11434 \
CODEINDEX_EMBEDDING_MODEL=nomic-embed-text \
CODEINDEX_EMBEDDING_DIMS=768 \
codeindex search "validate auth token"

# Historical search — symbols visible at a release tag
codeindex search "token validation" --as-of v1.2.0

codeindex history

codeindex history [REPO_PATH] [--since REF] [--max-commits N] [--json]

Backfills temporal graph data from git history — without any working-tree checkouts. Reads blobs via git cat-file --batch and stamps first_seen_commit / last_seen_commit on every file, edge, and symbol.

Run this once after initial setup to enable --as-of queries across the full history.

# Backfill up to 1000 commits (default)
codeindex history .

# Backfill only recent history
codeindex history . --since v1.0.0 --max-commits 200

codeindex changed-since

codeindex changed-since REF [--repo PATH] [--db PATH] [--json]

Lists files and dependency edges added or removed since a commit, branch, or tag.

$ codeindex changed-since v1.2.0
Changes since v1.2.0:

  Added files (2):
    + src/payments/stripe.py
    + src/payments/webhook.py

  Removed edges (1):
    - src/api.py → src/auth_v1.py  [imports]

codeindex db

codeindex db status [--db PATH] [--json]
codeindex db migrate [--db PATH]

Manages the SQLite store at <repo>/.codeindex/index.db.

$ codeindex db status
schema_version      : 2
repo_root           : /Users/alice/myapp
last_indexed_commit : a3f2e1c8
active_files        : 142
active_edges        : 387
active_symbols      : 1204
embedding_model     : nomic-embed-text
embedding_dims      : 768
vec_symbols         : enabled

db migrate applies any pending schema migrations automatically (also runs on every codeindex analyze).

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: