@estebanforge/pi-codegraph-enhanced

Pi-native CodeGraph tools with automatic index management on every session start. Fork of @vndv/pi-codegraph: same eight structural-code tools, plus a startup gate that creates, syncs, or rebuilds the index so it's always fresh without you ever running codegraph init / sync by hand.

Ask pi structural questions about your codebase without falling back to slow grep/read loops.

Install

pi install npm:@estebanforge/pi-codegraph-enhanced

CodeGraph itself must be installed and on PATH:

npm install -g @colbymchenry/codegraph

Then /reload in pi (or restart), and ask:

Use CodeGraph. Explain how authentication reaches the request handler.
Use CodeGraph. What would break if I change UserRepository?
Use CodeGraph. Show files under internal/services and important symbols.

What it does

Two halves: the tools (unchanged from upstream) and the auto-managed index (the fork's reason for existing).

Tools

Extension tools only, no MCP config to maintain. Each tool proxies one request to codegraph serve --mcp:

Tool	Description
codegraph_search	Symbol search by name
codegraph_node	One symbol's signature, location, source, callers, and callees
codegraph_files	Indexed file tree
codegraph_callers	Functions or methods that call a symbol
codegraph_callees	Functions or methods called by a symbol
codegraph_impact	Impact radius for changing a symbol
codegraph_explore	Source for several related symbols grouped by file
codegraph_status	Index health and pending sync status

Auto-managed index

On every session start and /reload, the extension probes the codegraph CLI and, when available, runs a status gate that performs the cheapest action leaving the index fresh:

State at startup	Action	Why
codegraph not on PATH	nothing (unavailable)	Fail-safe: bail before any spawn, avoid a false "initialized" and wasted timeouts
.codegraph/ missing	codegraph init -i	Create the index and build the graph in one step
.codegraph/ present, status reports pending changes	codegraph sync	Incremental update for drift made outside the watcher (terminal git pull, another editor)
.codegraph/ present, status unreadable / initialized: false / non-zero exit	codegraph index -f	Treat the DB as corrupt or half-initialized and rebuild it
status times out, or any command reports a live file-lock conflict	nothing (busy)	Another process owns the index (a /reload racing a long index). Skip rather than start a second writer or a wasteful full reindex
.codegraph/ present, status clean	nothing (skipped)	Already fresh

The maintenance runs fire-and-forget and never blocks the agent from starting. Outcome surfaces in the footer (CodeGraph: initialized / synced / rebuilt / busy / unavailable); a one-time warning fires if the CLI is missing. This replaces the daily codegraph index && codegraph sync habit, index -f only runs when status genuinely cannot read the DB.

How it works

pi agent
  -> pi-codegraph extension tool
  -> local CodeGraph MCP process (codegraph serve --mcp --path <project>)
  -> .codegraph/codegraph.db
  -> structured result back to pi

On resources_discover (once per session start and /reload), the extension additionally runs the auto-managed index gate against the current project before any tool call.

/codegraph command

Inspect and toggle the CodeGraph settings flag without leaving Pi.

Invocation	Effect
/codegraph (TUI)	Opens an interactive settings menu (the same SettingsList component /settings uses). Flip the flag, then a single reload fires on close to apply it.
/codegraph (non-TUI / RPC)	Falls back to a read-only status panel: the flag's on/off state and the last startup action.
/codegraph init	Index the current folder now, regardless of the flag. Creates/syncs/rebuilds the .codegraph index on demand.
/codegraph sync	Refresh the existing .codegraph index from the current source tree now. Sync-only: never creates or rebuilds. If no index exists, it points you at /codegraph init.
/codegraph toggle <flag>	One-shot flip: persists, then reloads.
/codegraph <flag>	Shorthand one-shot toggle (flag name without the toggle keyword).

Tab-completion is offered for init, sync, toggle, and the flag name.

The one flag today:

Flag	Default	What it does
codegraph-auto-index	false	Create the .codegraph index automatically in folders that don't have one, on every session start. Off by default so opening Pi in a folder never triggers indexing unless you ask. Existing indexes are always kept fresh (sync/rebuild) regardless of this flag. Use /codegraph init to index a specific folder on demand.

Two-tier behavior. Creation is opt-in (flag, default off); maintenance is always-on. If a project already has a .codegraph/ index (created via /codegraph init, a previous enabled session, or codegraph init -i), the extension keeps it fresh every startup, syncing drift and rebuilding on corruption, even with the flag off. The flag only controls whether to create new indexes in folders that have none.

Why a reload per apply. Pi's extension API exposes getFlag but no live setFlag, and flag values are read into memory at load time. Changes persist via pi config set and a /reload picks them up. You can also set flags directly: pi config set codegraph-auto-index false.

Notes on concurrency and recovery

• Cancellable runner. Every CLI invocation is wrapped in an AbortSignal with a 5-minute cap (10 seconds for the --version probe). A hung command is aborted and its child process killed, so it can never orphan a writer holding the codegraph lock.
• Lock conflicts. codegraph index -f reclaims stale locks (verified against @colbymchenry/codegraph), so a crash-leftover lock never blocks recovery of a corrupt DB. A live lock (another active process) surfaces in stderr and is detected as busy, never escalated into a racing second writer.
• In-flight dedup. Concurrent calls against the same project within a session collapse into one operation. Cross-/reload overlap is backstopped by codegraph's own .lock file.
• Windows parity. The startup runner resolves the codegraph shim via the same PowerShell Get-Command discovery the MCP launcher uses, so global npm/Scoop installs are found. Shared spawnCodeGraphProcess helper used by both paths.

Requirements

• Node.js 22.19.0 or newer (provided by pi).
• CodeGraph CLI on PATH: npm install -g @colbymchenry/codegraph.

Credit

Fork of @vndv/pi-codegraph by the CodeGraph contributors, which itself wraps @colbymchenry/codegraph. The tools, JSON-RPC MCP session, and Windows path handling are theirs; this fork adds the auto-managed index, the cancellable CLI runner, concurrency handling, and status feedback.

License

MIT