geto-graph

SQLite + BM25 codebase symbol graph for pi. Agents query the graph instead of guessing how the codebase is connected — then read only what's necessary.

Part of the geto monorepo.

Install

Via pi (npm package)

pi install npm:geto-graph@0.2.1

From source (this monorepo)

npm install                            # from repo root (links workspaces)
node packages/geto-graph/scripts/download-grammars.mjs   # fetch tree-sitter .wasm grammars
ln -s "$PWD/packages/geto-graph" ~/.pi/agent/extensions/geto-graph   # global
# or: ln -s "$PWD/packages/geto-graph" .pi/extensions/geto-graph      # project-local

Then /reload in pi. The index auto-builds (lazily) on first geto_graph_* tool call for the current project, stored in <project>/.geto-graph/index.db (add .geto-graph/ to your project's .gitignore).

Requires pi >= 0.84 (declared as a peer dependency).

Commands

• /geto-graph status — index size/freshness
• /geto-graph reindex [--force] [path] — incremental (mtime/size) or forced full reindex

Tools

Tool	Purpose
geto_graph_search	BM25 symbol search (name/signature/doc)
geto_graph_symbol	Exact lookup, all definitions across files
geto_graph_refs	Direct edges in/out: calls, imports, extends, implements, uses
geto_graph_file	All symbols + imports + config keys of one file
geto_graph_overview	Per-file symbol counts — the map
geto_graph_blastradius	BFS impact analysis (reverse/forward, depth, scope)
geto_graph_index	Incrementally refresh changed files and report additions plus persisted totals
geto_graph_reindex	Force a full index rebuild
geto_graph_status	Index freshness

Supported files

• .ts/.tsx/.js/.jsx/.mts/.cts — tree-sitter (WASM) full symbol + call/type/import graph
• .yaml/.yml — structural key-path scanner (services.web.image)
• Dockerfile/Containerfile — instruction scanner

Dev

npm test                                           # isolated regression checks
npm run test:e2e -- <project-root>                 # index a real project + run all queries

Releases

Versions, changelogs, tags, and npm publication are managed by Release Please from Conventional Commits. Do not edit the package version manually.

Notes

• Parse-extract-free per file: memory stays flat regardless of repo size (~1MB for 4000 files). Per-file ceiling is ~35MB (wasm32); files over 20MB are skipped.
• .geto-graph/ should be gitignored.
• Requires pi >= 0.84 (declared as a peer dependency).