@hcflabs/pi-codegraph0.9.0

@hcflabs/pi-codegraph

Prepare a separate CodeGraph index for each Git worktree and keep it current while Pi runs. Agents use codegraph_explore to get relevant source and call paths.

Install

npm install -g @colbymchenry/codegraph
pi install npm:@hcflabs/pi-codegraph

Put the codegraph executable on Pi's PATH. Keep Pi's built-in MCP support enabled for automatic index updates. The extension registers its MCP server; no MCP configuration is necessary.

Works with

Package	Relationship	Purpose
@colbymchenry/codegraph	Required	Builds indexes and answers codegraph explore queries.
@hcflabs/pi-footer	Improves	Shows index status, setup progress, and direct tool activity.

Use

Use /diagnostics to read recent prerequisite warnings and seed failures that require a new index.

Start pi at the top level of a linked worktree. If the primary checkout has no index, the TUI asks for indexing consent once per repository. Accept to run codegraph init --yes there. Alternatively, run this command in the primary checkout yourself:

codegraph init --yes

Surface	Type	Purpose
codegraph_explore	tool	For agents: returns relevant symbol source grouped by file, with call paths.
pi-codegraph	mcp server	Runs codegraph serve --mcp --path <worktree-root>. Its file watcher updates the index. Its tools are hidden.
CodeGraph setup status	ui	Shows users ✓ CG for indexed, ○ CG for missing, or a dim spinner with elapsed setup time. Errors include recovery instructions.

codegraph_explore accepts query, optional maxFiles (default 12), and optional projectPath (default: Pi's working directory). It finds the Git top-level directory of projectPath. It runs codegraph explore --path <top-level> --max-files <maxFiles> <query> and returns unchanged output. A command error or runtime above 120 seconds fails the tool call and shows the end of the error output.

The tool fails before it runs CodeGraph in these cases:

• projectPath is not an existing directory.
• The directory is not in a Git repository.
• The Git top-level directory has no .codegraph/codegraph.db file. This includes a plain directory inside an unrelated outer repository, for example a dotfiles repository in your home directory.

The error tells the agent to pass projectPath for an indexed repository. It lists up to 10 indexed repositories below Pi's working directory, found up to 3 directory levels deep. The search stops after 10 seconds or at its other limits, and the error then says that the list can be incomplete.

Works with codemode, including codemode.mode set to only. Scripts call tools.codegraph_explore({ query }) and receive a string.

Flow

Setup starts with Pi, not when Git creates a worktree. In the TUI, setup runs in the background. RPC, print, and JSON modes do not ask for consent. RPC waits for setup before it can accept an answer.

If you decline or press Escape, the extension writes pi-codegraph-declined in the Git common directory. Delete that file to permit another consent request. Automatic worktree setup requires a primary index. The extension does not initialize non-Git directories or offer to index bare repositories. It never indexes the repositories below a parent directory.

The extension asks for consent only when Pi starts at the top level of the worktree. If Pi starts in a subdirectory, the extension does not ask, because the directory can be a plain directory inside an unrelated outer repository. The extension still uses an existing index, and it still creates a worktree index from a primary index.

A submodule is a repository with its own Git directory. Git lists that Git directory as the primary worktree, so the extension does not treat it as a primary checkout. It never asks to index it. Run codegraph init --yes in the submodule yourself. The extension then uses that index.

The MCP file watcher updates each checkout's separate index, including uncommitted edits and changes in the primary checkout. Sessions share one CodeGraph daemon per checkout. It stops five minutes after the last session closes.

Index status

During setup, the footer shows a dim status such as ⠋ CG · indexing 8s. It shows waiting for index while another session initializes the index. Only the TUI animates the spinner. Setup ends with the indexed or missing badge, without a success notice. Non-Git directories have no badge.

When Pi starts in a directory that is not in a Git repository, the TUI shows one short notice for the run. The notice tells you to pass projectPath to codegraph_explore.

Missing prerequisites and setup failures remain visible as ! CG: prerequisites missing or ! CG: setup failed. Each has a theme-colored ! icon and a notice with recovery instructions. With pi-footer, status stays on the third line. Direct codegraph_explore calls temporarily show ● CG.

Creating, resuming, or forking a session waits for active initialization without interrupting it. Quitting or reloading Pi cancels setup. Interrupted setup requires explicit lock recovery.

State and storage

Each checkout owns .codegraph/codegraph.db. The extension can read other indexes to prepare it, but does not change them. It writes pi-codegraph-init.lock in the worktree's Git metadata and pi-codegraph-declined in the Git common directory.

Setup rule	Requirement or result
Seed index	Complete index of the same repository, built by the installed CodeGraph version, with matching codegraph.json contents.
Selection	Fewest changed files compared to the worktree HEAD.
Copy	Holds the source writer lock .codegraph/codegraph.lock. Skips a source that another writer locks.
Status check	Accepts the copy only if codegraph status --json exits with code 0 and reports index.state:"complete" and index.reindexRecommended:false.
Accepted copy	Runs codegraph sync <worktree-root> after the status check.
Rejected copy	Deletes the copy and tries the next index.
No usable index	Runs codegraph init --yes <worktree-root>.

The extension does not add ignore rules, delete indexes, or prune worktrees. Add .codegraph/ to your ignore rules if necessary. Pi Subagent retains ignored files to prevent data loss, so indexed worker worktrees can require manual cleanup.

Limits and recovery

If the startup check codegraph --version fails, Pi warns, reports prerequisites missing, and skips setup. Install or fix the executable, then restart Pi or run /reload. The extension never installs prerequisites automatically.

Failed or interrupted initialization keeps pi-codegraph-init.lock to block use of a partial database. To recover:

1. Make sure that no initializer runs.
2. Run codegraph index from the affected worktree root, not a nested directory or another checkout.
3. After success, use rmdir to remove the lock directory at the path in the error message.
4. Run /reload.

For example:

cd /path/to/affected-worktree-root && codegraph index && rmdir /path/to/pi-codegraph-init.lock

For a primary-checkout failure, use the primary checkout and its lock. The error shows both paths.

Do not remove an active lock or run manual codegraph init commands during initialization. The lock does not control manual commands. Existing indexes without an extension-owned lock receive no health check.

Only Git worktree-root indexes in the default .codegraph directory are supported. Nested monorepo indexes do not initialize automatically. Keep the primary checkout indexed for automatic opt-in detection.

Each daemon uses approximately 230 MB of memory. With MCP disabled, for example through --no-mcp, indexes become stale. Run codegraph sync in the checkout to update its index. An mcp.json server named pi-codegraph replaces the extension's server.