CodeGraph — Motor de indexación AST
MCP server externo @colbymchenry/codegraph (MIT,
github.com/colbymchenry/codegraph)
que indexa código con tree-sitter en SQLite y expone 8 tools MCP. Savia lo
usa como motor de dos skills, no como reemplazo:
agent-code-map(.acm): proyecta el índice a Markdown estructurado.ast-comprehension: sustituye grep por llamadas MCP semánticas.
.hcm, codebase-map y Savia Shield siguen siendo nuestros — ortogonales.
Por qué
Las queries grep tienen tres límites: falsos positivos en callers por
matches en comentarios/strings, no son incrementales, y no entienden
routes de framework (Django, Express, FastAPI, Spring). CodeGraph resuelve
los tres con un índice persistente.
Activación opt-in por proyecto
CodeGraph no se instala con Savia. Se activa cuando aporta valor (>500 ficheros, lenguaje con buen tree-sitter, scope no N4b).
# 1. Instalar
npm i -g @colbymchenry/codegraph
# o: curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# 2. Indexar
cd <proyecto>
codegraph init -i # crea .codegraph/codegraph.db
codegraph status
# 3. Habilitar MCP en opencode.json (enabled:true)
Por defecto el repo Savia trae enabled: false — Rule #19.
Herramientas MCP
| Tool | Uso desde Savia |
|---|---|
codegraph_search |
query #1 symbol-search de ast-comprehension |
codegraph_node |
query #2 impl |
codegraph_callers |
query #3 callers (resuelto, no grep) |
codegraph_callees |
inverso de callers |
codegraph_impact |
análisis pre-edit (sin equivalente nativo) |
codegraph_context |
construye contexto — SOLO desde sub-agentes Explore |
codegraph_explore |
source de varios símbolos — SOLO desde sub-agentes Explore |
codegraph_files |
estructura indexada |
codegraph_status |
health del índice |
Regla operativa (importada del upstream): codegraph_context y
codegraph_explore devuelven mucha source y no se llaman desde la
sesión principal — se delegan a sub-agentes Explore.
Uso desde agent-code-map
/codemap:generate y /codemap:refresh invocan codegraph index --quiet
y codegraph status --json. El generador .acm consulta codegraph_files
y codegraph_search para construir secciones por capa. El hash sha256
del .acm incluye versión del índice.
Fallback: si CodeGraph no responde, agent-code-map cae a grep +
tree-sitter ad-hoc. La integración nunca bloquea.
Uso desde ast-comprehension
Las 6 queries tienen ahora dos backends:
| Query | Backend MCP | Backend grep (fallback) |
|---|---|---|
symbol-search |
codegraph_search |
grep -rn |
impl |
codegraph_node --source |
awk |
callers |
codegraph_callers |
grep + filtro |
callees |
codegraph_callees |
n/a (era debilidad) |
tests |
codegraph_search --kind test |
grep en __tests__/ |
impact |
codegraph_impact (nuevo) |
n/a |
El agente elige backend en runtime según codegraph_status.
Confidencialidad
.codegraph/codegraph.db debe estar en .gitignore del proyecto —
contiene copia parseable del código y en N4 no puede viajar al repo
público. Ver docs/rules/domain/codegraph-confidentiality.md.
agent-code-map verifica esto antes de invocar codegraph index en
scope N4/N4b. Si .gitignore no excluye .codegraph/, aborta.
CLI directo (sin agente)
codegraph query <symbol> --json
codegraph callers <symbol> --json
codegraph impact <symbol> --depth 2 --json
codegraph affected --stdin # tests afectados por git diff — útil en CI
Cuándo NO usar
- Proyectos < 500 ficheros (overhead > beneficio).
- Confidencialidad N4b/PM-Only — el índice mezcla todo lo no-gitignored.
- Lenguajes sin tree-sitter relevante (COBOL, JCL, mainframe).
- Sesiones one-shot donde
codegraph initno se amortiza.
Referencias
- Repo: https://github.com/colbymchenry/codegraph (MIT, activo)
- Skills relacionadas:
agent-code-map,ast-comprehension,human-code-map(ortogonal),codebase-map(ortogonal). - Regla:
docs/rules/domain/codegraph-confidentiality.md.