codeloom

"With codeloom, your coding agent knows what to read."

AI coding agents are powerful but fundamentally blind to your codebase structure. When your agent edits validate_token(), it has no idea that 47 callers depend on its return type. When it searches for "database connection", it greps blindly through every file. Without a code graph, your agent works like a surgeon operating without an X-ray, skilled but guessing at what's inside.

codeloom builds a queryable code graph from your entire codebase — extracting structure from 55 languages and formats, every function, class, import, call, and document — and exposes it to your AI agent. One install, and your agent stops grepping and starts understanding.

Quick Start

pip install codeloom

cd your-project/
codeloom install opencode    # for OpenCode
# or: codeloom install claude  # for Claude Code

Then tell your agent:

"Build a code graph for this project"

That's it. The graph auto-rebuilds when your session ends. No extra tokens, no extra commands, everything runs 100% locally.

What Changes

Every search returns results like this:

seeds:
codeloom/core/pipeline.py:71
  │ def run_pipeline(source_dir: Path, ...) -> PipelineResult:
  │     """Run the full code graph build pipeline."""
storage/store.py:20
  │ class KnowledgeStore:

edges:
codeloom/core/pipeline.py:71 -calls-> storage/store.py:20
codeloom/core/pipeline.py:0 -defines-> codeloom/core/pipeline.py:71

Seeds tell you where relevant code lives. Edges tell you how it connects. Together they give your agent the full picture, no separate Read calls needed.

16 MCP Tools at a Glance

Three categories, one MCP server.

Search

Analysis

Refactoring & Admin

All tools are available via MCP (stdin/stdout), no HTTP server, no network, no configuration.

Languages & Formats

Structural extraction (functions, classes, calls, imports)

Full tree-sitter tags.scm-based resolution for 17+ core languages. All 56 languages get module-level indexing, source snippets, and embeddings — structural detail depends on optional tree-sitter-<lang> packages.

Document & config extraction

Plus 100+ natural languages for search queries via multilingual-e5-small embeddings. Search in any language, find results in any language.

AI Agent Integrations

One command per platform:

Each install writes context rules and registers hooks where supported. For OpenCode, it also installs a plugin that automatically injects graph context before grep/glob calls, your agent gets results without having to ask. Remove with codeloom uninstall <agent>.

Features

Search Before Grepping

5-signal HybridRAG fuses code vector search, text vector search, graph expansion, FTS5 keyword, and community signals into one ranked result set with subgraph edges. --kind, --file, and --include-tests filters narrow results without re-running.

Edit With Confidence

Run impact before editing to find every caller. Run context for a full symbol overview, community, all relationships, source snippet. Run detect_changes after edits to see which nodes are affected.

Auto-Context (OpenCode)

The OpenCode plugin hooks into grep/glob calls, runs codeloom search with the query, and injects results directly into the agent's session, graph context appears automatically, no explicit invocation needed.

Auto-Rebuild

Stop/SessionEnd hooks detect changed files via git diff and trigger an incremental rebuild. Lock files prevent concurrent rebuilds. Zero manual intervention, the graph stays fresh after every session.

Incremental & Fast

SHA-256 content hashing skips unchanged files. Hot-start PageRank reuses previous importance scores. Parallel extraction (ProcessPoolExecutor) speeds up full builds by 24-64%. Typical incremental build: ~0.4s for no changes, ~4s for changes, 95%+ faster than a full rebuild. Model warmup (--warmup, default on) preloads embedding models on MCP server start so the first search is fast — disable with --no-warmup to save ~150MB RAM.

100% Local + MIT

No cloud services, no API keys, no telemetry. SQLite + FAISS for storage, sentence-transformers for embeddings. All data stays on your machine. MIT licence, no commercial restrictions, no licensing friction.

Performance

Benchmarks on a 2023 MacBook Pro (M2 Pro, 32GB RAM). All builds use parallel extraction (default: os.cpu_count() workers).

codeloom's own codebase (~3,500 lines, 90 files, 1,300 nodes)

Synthetic stress tests (no embeddings)

Parallel extraction delivers 24-64% faster builds. Compact node storage (path interning, skipped empty attrs, RAM-free source snippets after persist) reduces peak memory by 10-22%. See docs/SCALING.md for detailed analysis.

• Embedding models: ~180MB, downloaded once to ~/.codeloom/models/
• Database: ~2MB (SQLite + FTS5 + FAISS indices)

Full CLI Reference

All commands output compact text by default (designed for AI agent consumption).

CLI Commands

MCP-Only Tools

These are available via codeloom mcp — see the MCP tools section above:

impact · dependencies · context · detect_changes · rename · explain_flow · export_subgraph · list_repos

Requirements

• Python 3.10+
• ~180MB disk for embedding models (cached on first use)

# Optional: PDF, DOCX, XLSX, ODF extraction
pip install codeloom[docs]

Development

pip install -e ".[dev]"
pytest
ruff check codeloom/

License

MIT License. See LICENSE for details.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.