ai-codeindex

codeindex

🇬🇧 English | 🇨🇳 中文

codeindex is the parser engine that powers LoomGraph. It turns any codebase into AI-readable structural artifacts — a graph-export NDJSON call/inheritance graph (the sole seam LoomGraph consumes) and, as a standalone by-product, README_AI.md navigation indexes. Stateless (ADR-007); the user-facing product is LoomGraph.

End users: pipx install loomgraph — it pulls ai-codeindex automatically. You never operate codeindex directly. See the LoomGraph integration guide. Standalone users (navigation indexes without the graph layer): see Standalone usage below.

---

Why

AI agents in an unfamiliar codebase waste tokens grepping for the right entry point. codeindex pre-computes a structural slice (tree-sitter AST → symbols, calls, inheritance) so the agent — or the graph layer that serves the agent — starts from a known map, not from raw grep. The win is navigation efficiency, not capability: a measured −28% tokens / −19% wall-time on the discovery phase, but answer quality is a wash (it does not make the agent smarter — see Benchmark).

---

Install

pipx install loomgraph          # end users: pulls ai-codeindex as a dependency

Standalone (navigation indexes only, no graph layer):

pipx install ai-codeindex

From source:

git clone https://github.com/dreamlx/codeindex.git
cd codeindex
pip install -e ".[all]"

Claude Code users — also install the companion plugin for skills (codeindex:arch / :index / :update-guide):

/plugin marketplace add dreamlx/codeindex-claude
/plugin install codeindex@codeindex-claude

Language parsers

Python and PHP grammars ship by default. Other languages need the matching tree-sitter grammar:

pipx inject ai-codeindex tree-sitter-typescript tree-sitter-java   # add to pipx env
# or pin a subset at install time:
pipx install "ai-codeindex[ios]"      # Swift + Objective-C

🇨🇳 China users: if your mirror hasn't synced the latest release, install from upstream PyPI: pipx install --index-url https://pypi.org/simple/ ai-codeindex

---

Quick start

LoomGraph users (the main path):

loomgraph index .            # codeindex graph-export → embed → inject, one pipeline
loomgraph graph "UserService.login" --depth 2
loomgraph topology           # orphans / hubs + resolved_ratio trust signal

Standalone (README_AI navigation indexes only):

codeindex init               # creates .codeindex.yaml + injects CLAUDE.md section
codeindex scan-all           # structural + optional AI descriptions (auto when ai_command set)
codeindex scan-all --no-ai   # structural only

Full command reference: codeindex --help.

---

Standalone usage (without the graph layer)

codeindex's README_AI.md is a tiered navigation index — agents browse it to find the right module, then drop to source for precise mechanism. It is not a knowledge graph and does not resolve cross-module relationships; for that, use LoomGraph.

When standalone is the right fit:

• Small / mid codebase where a graph layer is more weight than you need.
• Air-gapped intranet where you want navigation without any external service.
• Pairing with Serena MCP for precise symbol queries (codeindex = the "map", Serena = the "GPS").

When you should move to LoomGraph:

• You need cross-module call-graph walks (callers of authenticate() two hops deep).
• You need change-impact analysis, topology smells, or semantic search.
• The codebase is large enough that a flat navigation index stops paying (see benchmark: on a 250-directory legacy system the token win nearly vanished — a flat index points at files but can't synthesize cross-module semantics).

codeindex init injects a codeindex section into your project's CLAUDE.md so Claude Code reads README_AI.md first (never ~/.claude — ADR-006). codeindex scan-all refreshes indexes after structural changes; README_AI.md is a generated artifact — do not hand-edit.

---

Benchmark

Most "AI code understanding" tools assert value. We A/B-tested ours — and published the unflattering parts.

Across 15 graded navigation questions on 3 heterogeneous real projects, a coding agent with README_AI.md vs without:

• −28% tokens, −19% wall-time on average — agents reach the right file faster and cheaper.
• Answer quality is a wash. It does not make answers more correct — the win is efficiency, not capability. (An undisciplined index even hurt a few precise-mechanism questions; fixed in ADR-005.)
• Smallest win on the largest codebases. On a 250-directory legacy system the token win nearly vanished — a flat index points you to files but can't synthesize cross-module semantics. codeindex is the navigate layer, not the understand-everything layer (pair it with source-reading / Serena for precise mechanism, or move to LoomGraph for cross-module graph queries).

Full data incl. the failure cases: 2026-05 benchmark. Reproduce on your own repos: bench/ (make setup && make run && make grade).

Why publish the parts that don't flatter the tool: a navigation index that quietly degrades answer quality is worse than none. Knowing exactly where it helps — and where to drop to source — is the point.

---

Commands

Full reference: codeindex --help. Highlights:

Each command emits JSON (--output json) for CI/CD and downstream tools.

---

Language support

Framework route extraction: ThinkPHP (PHP), Spring Boot (Java); Express, Laravel, FastAPI, Django planned.

Want to add a language? The template-based test system lets you contribute by writing YAML specs — no Python knowledge required. See CONTRIBUTING.md.

---

How it works

codeindex's documentation generation is a two-phase pipeline — structure is deterministic (tree-sitter, no AI), AI enrichment is an optional overlay. The graph-export NDJSON (the LoomGraph seam) is pure AST. Full pipeline + architecture diagrams: docs/architecture/design-philosophy.md.

---

For LoomGraph developers

If you work on LoomGraph (the user-facing product), start here: FOR_LOOMGRAPH.md — the parser-engine contract, the graph-export NDJSON seam, and the codeindex commands you'll touch.

---

Documentation

User guides

Developer & architecture

Evidence & benchmarks

---

Contributing

git clone https://github.com/dreamlx/codeindex.git
cd codeindex
pip install -e ".[dev,all]"
make install-hooks
make test

See CONTRIBUTING.md for guidelines. Maintainer release: make release VERSION=0.X.0 (CI → tests → PyPI publish → GitHub Release).

---

Roadmap

Current version: v0.40.0

Next: framework routes expansion (Express, Laravel, FastAPI, Django); Go, Rust, C# language support.

Code similarity search, refactoring suggestions, team collaboration, and IDE integration live in LoomGraph, not here — codeindex stays the stateless parse layer.

See Strategic Roadmap for detailed plans.

---

License

MIT — free, and meant to stay that way.

Support

• Questions: GitHub Discussions
• Bugs / Feature requests: GitHub Issues