convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
algodesigner

CodeLoom

algodesigner/codeloom

Grafo de código local-first para agentes IA compreenderem sua arquitetura

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que constrói um grafo de código queryável a partir de sua base de código, extraindo estrutura de 55+ linguagens. Expõe 16 ferramentas de busca e análise híbrida (vetorial + palavra-chave + grafo) para que agentes IA entendam dependências, impacto de mudanças e conexões semânticas sem grep cego.

Instalação

$npx convez-ai algodesigner/codeloom

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 3 semanas
Versão
v0.1.13
Issues abertas
0
Contribuidores
1

Casos de uso

  • Agentes de IA compreenderem dependências antes de editar código
  • Análise de impacto de mudanças (blast radius) em refatorações
  • Busca semântica + grafo para encontrar código relacionado

Veredito

Ferramenta sólida que resolve um problema real de agentes IA: cegueira estrutural da base de código. A abordagem híbrida (vetor + palavra-chave + grafo) é técnicamente bem pensada. Indicado para quem quer agentes IA que editem código com segurança.

README

A tradução para o português deste README ainda está na fila.


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

Before (grep)After (codeloom)
Finds exact strings, misses semantic connectionsFinds conceptually related code via vector + keyword + graph
Returns a flat list of file matchesReturns seeds plus a subgraph showing how they connect
No way to know what depends on whatcodeloom impact "validate_token", finds all 47 callers instantly
Agent operates blind, guesses at relationshipsAgent sees the full picture before making edits

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

ToolWhat it does
search5-signal HybridRAG, vector + keyword + graph + community fused into one ranking
search_keywordFTS5 keyword-only (BM25), instant results for known names
search_vectorSemantic vector-only, finds conceptually similar code

Analysis

ToolWhat it does
impactBlast radius, every caller that depends on a symbol
dependenciesUpstream deps, what a symbol needs to function
context360-degree view of a symbol, metadata, community, all edges, source snippet
detect_changesMap unstaged git changes to affected graph nodes
explain_flowTrace execution path through call chains
statsNode/edge counts, kind distribution, god nodes
communitiesBrowse functional clusters (Leiden communities)
nodeDetails on a specific symbol with fuzzy name matching

Refactoring & Admin

ToolWhat it does
renameFind every location and reference for safe multi-file rename
export_subgraphExport focused subgraph around a symbol as D3.js JSON
list_reposList available code graphs with staleness status
buildBuild or rebuild the code graph
watchWatch files for changes and rebuild automatically

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.

AdaCC#C++Common LispElixirFortranGo
GroovyHaskellJavaJavaScriptJuliaKotlinLuaNix
Objective-COCamlPerlPHPPowerShellPythonRRuby
RustScalaShellSoliditySwiftTerraformTypeScriptZig
Assembly

Document & config extraction

CMakeCSVCSSDjVuDockerfileDOCX
GraphQLHCLHTMLJSONMakeMarkdown
ODPODSODTOrgPDFRST
SQLTOMLXLSXXMLYAML

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:

AgentInstall
Claude Codecodeloom install claude
OpenCodecodeloom install opencode
Codex CLIcodeloom install codex
Gemini CLIcodeloom install gemini
Cursor IDEcodeloom install cursor
Windsurf IDEcodeloom install windsurf
Clinecodeloom install cline
Aider CLIcodeloom install aider
Any MCP clientclaude mcp add codeloom -- codeloom mcp

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)

OperationTime
Full build~14s
Incremental (changes)~4s
Incremental (no changes)~0.4s
Cold search (dual model)~2.8s
Cold search (--fast)~0.2s
Warm search~0.08s
Cached search<1ms

Synthetic stress tests (no embeddings)

DatasetFilesNodesBuild TimePeak Memory
Tiny101190.7s14 MB
Small1004,1092.3s16 MB
Medium1,000101,00953.1s393 MB
Large5,000205,009164.9s814 MB

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

CommandDescription
build <dir>Build code graph (--incremental, --git)
watch <dir>Real-time file system monitor
search <query>5-signal HybridRAG with subgraph + snippets
search-keyword <query>FTS5 keyword matching only
search-vector <query>Vector similarity only
search-graph <query>Graph expansion only (BFS from vector seeds)
search-community <query>Community cluster matching only
statsGraph statistics
node <id>Node details with fuzzy matching
communitiesList or search communities
queryInteractive search REPL
exportExport as JSON, GraphML, or D3.js
visualizeInteractive HTML visualization
install [agent]Install codeloom integration for AI agents
uninstall [agent]Remove codeloom integration for AI agents
doctorCheck installation health
cleanRemove .codeloom/ database
mcpStart MCP server
help [command]Show categorised help with usage examples

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.

Ver o original no GitHub

Bom para

Relacionados