--- title: "@henryqw/pi-codegraph" seo: description: "Initialize CodeGraph indexes in opted-in Git worktrees and expose codegraph_explore as a Pi tool." ---
Version v0.8.0
Monthly npm downloadsMIT license
Use separate [CodeGraph](https://github.com/colbymchenry/codegraph) indexes for explicitly selected Git worktrees in one Pi session. Agents use `codegraph_explore` to get relevant source and call paths. Each selected worktree has its own file watcher. ## Install The `-g` option installs CodeGraph globally. ```bash npm install -g @colbymchenry/codegraph pi install npm:@henryqw/pi-codegraph ``` Put the `codegraph` executable on Pi's `PATH`. Keep Pi's built-in Model Context Protocol (MCP) support enabled for automatic index updates. The extension registers its MCP servers; no MCP configuration is necessary. ## Works with | Package | Relationship | Purpose | | --- | --- | --- | | [`@colbymchenry/codegraph`](https://github.com/colbymchenry/codegraph) | Required | Builds indexes and answers `codegraph explore` queries. | | [`@henryqw/pi-footer`](https://pi.henry.wang/extensions/pi-footer) | Improves | Shows index status, setup progress, and direct tool activity. | ## Use Start `pi` in a linked worktree or in a directory that contains several repositories. Set `projectPath` to select another repository. Pi does not search child directories for repositories. For a linked worktree without an index, the text user interface (TUI) asks for indexing consent if the primary checkout has no index. It asks once per repository. Accept to run `codegraph init --yes` there; `--yes` accepts CodeGraph setup prompts. Alternatively, run this command in the primary checkout yourself: ```bash codegraph init --yes ``` In the status display, `CG` means CodeGraph. In server names, `root-hash` identifies the canonical worktree root. | Surface | Type | Purpose | | --- | --- | --- | | `codegraph_explore` | tool | For agents: returns relevant symbol source grouped by file, with call paths. | | `pi-codegraph` and `pi-codegraph-` | mcp server | One hidden server per selected worktree. Runs `codegraph serve --mcp --path `; `--mcp` selects MCP mode and `--path` selects the worktree root. | | 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). A nested directory selects its containing Git worktree, not a separate nested index. Relative paths use Pi's working directory. Symbolic links to the same worktree share setup and one watcher. The tool runs `codegraph explore --path --max-files ` and returns unchanged output. The `--max-files` option limits the source files in the result. A command error or runtime above 120 seconds fails the exploration and shows the end of the error output. Setup can take longer. For example, a session in `/workspace` can query two repositories: ```javascript await tools.codegraph_explore({ query: "authentication", projectPath: "/workspace/api/src" }); await tools.codegraph_explore({ query: "navigation", projectPath: "/workspace/web" }); ``` Without `projectPath`, a non-Git session directory produces an error that asks you to select a worktree. Missing directories and paths to files produce an invalid-directory error. A missing index produces manual setup instructions if automatic setup is not permitted. Selecting an unindexed primary checkout does not create its index or ask for consent. Works with `codemode`, including `codemode.mode` set to `only`. Scripts call `tools.codegraph_explore({ query })` and receive a string. ## Flow ```mermaid flowchart LR A[Startup directory or query projectPath] --> B[Resolve containing Git worktree] B --> C[Reuse setup for this worktree] C --> D[Index ready after lock check] D --> E[One hidden watcher per worktree] D --> F[Explore at worktree root] B --> G[No worktree: report path guidance] C --> H[No permitted index setup: report manual steps] ``` ![Selected linked-worktree setup: primary-index consent, seed selection, locked copy, status check, synchronization or new index, and a separate watcher.](data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3aWR0aD0iMTI4MCIgaGVpZ2h0PSI3MjAiIHZpZXdCb3g9IjAgMCAxMjgwIDcyMCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiByb2xlPSJpbWciIGFyaWEtbGFiZWxsZWRieT0iY29kZWdyYXBoLXNldHVwLWZsb3ctdGl0bGUgY29kZWdyYXBoLXNldHVwLWZsb3ctZGVzYyIgaWQ9ImNvZGVncmFwaC1zZXR1cC1mbG93LXJvb3QiPgogIDx0aXRsZSBpZD0iY29kZWdyYXBoLXNldHVwLWZsb3ctdGl0bGUiPkNvZGVHcmFwaCB3b3JrdHJlZSBpbmRleCBzZXR1cDwvdGl0bGU+CiAgPGRlc2MgaWQ9ImNvZGVncmFwaC1zZXR1cC1mbG93LWRlc2MiPlN0YXJ0dXAgb3IgcHJvamVjdFBhdGggc2VsZWN0cyBvbmUgR2l0IHdvcmt0cmVlLiBQaSBnZXRzIHByaW1hcnktaW5kZXggY29uc2VudCwgY2hlY2tzIGNvcGllZCBpbmRleGVzIGJlZm9yZSBzeW5jaHJvbml6YXRpb24sIGFuZCBzdGFydHMgYSBzZXBhcmF0ZSBNb2RlbCBDb250ZXh0IFByb3RvY29sIChNQ1ApIHdhdGNoZXIuPC9kZXNjPgogIDxkZWZzPgogICAgICA8c3R5bGU+QGltcG9ydCB1cmwoJ2h0dHBzOi8vZm9udHMuZ29vZ2xlYXBpcy5jb20vY3NzMj9mYW1pbHk9SW5zdHJ1bWVudCtTZXJpZjppdGFsQDA7MSZhbXA7ZmFtaWx5PUdlaXN0OndnaHRANDAwOzUwMDs2MDAmYW1wO2ZhbWlseT1HZWlzdCtNb25vOndnaHRANDAwOzUwMDs2MDAmYW1wO2ZhbWlseT1Ob3RvK1NlcmlmOml0YWxAMDsxJmFtcDtmYW1pbHk9Tm90bytTYW5zK0tSOndnaHRANDAwOzUwMDs2MDAmYW1wO2ZhbWlseT1Ob3RvK1NlcmlmK0tSOndnaHRANDAwJmFtcDtmYW1pbHk9Tm90bytTYW5zK1RDOndnaHRANDAwOzUwMDs2MDAmYW1wO2ZhbWlseT1Ob3RvK1NlcmlmK1RDOndnaHRANDAwJmFtcDtkaXNwbGF5PXN3YXAnKTsKICAgICAgI2NvZGVncmFwaC1zZXR1cC1mbG93LXJvb3QgeyBjb2xvcjogIzEwMTgyODsgfQogICAgICAjY29kZWdyYXBoLXNldHVwLWZsb3ctcm9vdCAuZGlhZ3JhbS1jb250YWluZXIgeyB3aWR0aDogMTAwJTsgb3ZlcmZsb3cteDogYXV0bzsgfQogICAgICAjY29kZWdyYXBoLXNldHVwLWZsb3ctcm9vdCAuZGlhZ3JhbS1jb250YWluZXIgeyBvdmVyZmxvdy14OiB2aXNpYmxlOyB9CiAgICAgICNjb2RlZ3JhcGgtc2V0dXAtZmxvdy1yb290IC5oZWFkaW5nIHsgZmlsbDogIzEwMTgyODsgZm9udDogNDAwIDI4cHggJ0luc3RydW1lbnQgU2VyaWYnLCBzZXJpZjsgfQogICAgICAjY29kZWdyYXBoLXNldHVwLWZsb3ctcm9vdCAubm90ZSB7IGZpbGw6ICM0YzU2NjU7IGZvbnQ6IDQwMCAxMnB4ICdHZWlzdCcsIHNhbnMtc2VyaWY7IH0KICAgICAgI2NvZGVncmFwaC1zZXR1cC1mbG93LXJvb3QgLm5vZGUgeyBmaWxsOiAjZmZmZmZmOyBzdHJva2U6ICMxMDE4Mjg7IHN0cm9rZS13aWR0aDogMTsgfQogICAgICAjY29kZWdyYXBoLXNldHVwLWZsb3ctcm9vdCAudGVybWluYWwgeyBmaWxsOiAjZTZlNGRlOyBzdHJva2U6ICM2YTcyODI7IHN0cm9rZS13aWR0aDogMTsgfQogICAgICAjY29kZWdyYXBoLXNldHVwLWZsb3ctcm9vdCAuZGVjaXNpb24geyBmaWxsOiAjZmZmZmZmOyBzdHJva2U6ICMxMDE4Mjg7IHN0cm9rZS13aWR0aDogMTsgfQogICAgICAjY29kZWdyYXBoLXNldHVwLWZsb3ctcm9vdCAuZ2F0ZSB7IGZpbGw6IHJnYmEoMjksNzgsMjE2LC4wOCk7IHN0cm9rZTogIzFkNGVkODsgc3Ryb2tlLXdpZHRoOiAxLjI7IH0KICAgICAgI2NvZGVncmFwaC1zZXR1cC1mbG93LXJvb3QgLm5hbWUgeyBmaWxsOiAjMTAxODI4OyBmb250OiA2MDAgMTRweCAnR2Vpc3QnLCBzYW5zLXNlcmlmOyB0ZXh0LWFuY2hvcjogbWlkZGxlOyB9CiAgICAgICNjb2RlZ3JhcGgtc2V0dXAtZmxvdy1yb290IC5kZXRhaWwgeyBmaWxsOiAjNGM1NjY1OyBmb250OiA0MDAgMTJweCAnR2Vpc3QnLCBzYW5zLXNlcmlmOyB0ZXh0LWFuY2hvcjogbWlkZGxlOyB9CiAgICAgICNjb2RlZ3JhcGgtc2V0dXAtZmxvdy1yb290IC5jb2RlIHsgZmlsbDogIzRjNTY2NTsgZm9udDogNDAwIDEwcHggJ0dlaXN0IE1vbm8nLCBtb25vc3BhY2U7IHRleHQtYW5jaG9yOiBtaWRkbGU7IH0KICAgICAgI2NvZGVncmFwaC1zZXR1cC1mbG93LXJvb3QgLmVkZ2UgeyBmaWxsOiBub25lOyBzdHJva2U6ICM0YzU2NjU7IHN0cm9rZS13aWR0aDogMS4yOyBtYXJrZXItZW5kOiB1cmwoI2NvZGVncmFwaC1zZXR1cC1mbG93LWFycm93KTsgfQogICAgICAjY29kZWdyYXBoLXNldHVwLWZsb3ctcm9vdCAucmV0cnkgeyBmaWxsOiBub25lOyBzdHJva2U6ICM0YzU2NjU7IHN0cm9rZS13aWR0aDogMS4yOyBzdHJva2UtZGFzaGFycmF5OiA1IDQ7IG1hcmtlci1lbmQ6IHVybCgjY29kZWdyYXBoLXNldHVwLWZsb3ctYXJyb3cpOyB9CiAgICAgICNjb2RlZ3JhcGgtc2V0dXAtZmxvdy1yb290IC5hY2NlcHRlZCB7IGZpbGw6IG5vbmU7IHN0cm9rZTogIzFkNGVkODsgc3Ryb2tlLXdpZHRoOiAxLjI7IG1hcmtlci1lbmQ6IHVybCgjY29kZWdyYXBoLXNldHVwLWZsb3ctYXJyb3ctYWNjZW50KTsgfQogICAgICAjY29kZWdyYXBoLXNldHVwLWZsb3ctcm9vdCAubGFiZWwtbWFzayB7IGZpbGw6ICNmMGVlZTk7IH0KICAgICAgI2NvZGVncmFwaC1zZXR1cC1mbG93LXJvb3QgLmxhYmVsIHsgZmlsbDogIzRjNTY2NTsgZm9udDogNTAwIDEwcHggJ0dlaXN0IE1vbm8nLCBtb25vc3BhY2U7IHRleHQtYW5jaG9yOiBtaWRkbGU7IH08L3N0eWxlPgogICAgPHN0eWxlPgogICAgICAuaGVhZGluZyB7IGZpbGw6ICMxMDE4Mjg7IGZvbnQ6IDQwMCAyOHB4ICdJbnN0cnVtZW50IFNlcmlmJywgc2VyaWY7IH0KICAgICAgLm5vdGUgeyBmaWxsOiAjNGM1NjY1OyBmb250OiA0MDAgMTJweCAnR2Vpc3QnLCBzYW5zLXNlcmlmOyB9CiAgICAgIC5ub2RlIHsgZmlsbDogI2ZmZmZmZjsgc3Ryb2tlOiAjMTAxODI4OyBzdHJva2Utd2lkdGg6IDE7IH0KICAgICAgLnRlcm1pbmFsIHsgZmlsbDogI2U2ZTRkZTsgc3Ryb2tlOiAjNmE3MjgyOyBzdHJva2Utd2lkdGg6IDE7IH0KICAgICAgLmRlY2lzaW9uIHsgZmlsbDogI2ZmZmZmZjsgc3Ryb2tlOiAjMTAxODI4OyBzdHJva2Utd2lkdGg6IDE7IH0KICAgICAgLmdhdGUgeyBmaWxsOiByZ2JhKDI5LDc4LDIxNiwuMDgpOyBzdHJva2U6ICMxZDRlZDg7IHN0cm9rZS13aWR0aDogMS4yOyB9CiAgICAgIC5uYW1lIHsgZmlsbDogIzEwMTgyODsgZm9udDogNjAwIDE0cHggJ0dlaXN0Jywgc2Fucy1zZXJpZjsgdGV4dC1hbmNob3I6IG1pZGRsZTsgfQogICAgICAuZGV0YWlsIHsgZmlsbDogIzRjNTY2NTsgZm9udDogNDAwIDEycHggJ0dlaXN0Jywgc2Fucy1zZXJpZjsgdGV4dC1hbmNob3I6IG1pZGRsZTsgfQogICAgICAuY29kZSB7IGZpbGw6ICM0YzU2NjU7IGZvbnQ6IDQwMCAxMHB4ICdHZWlzdCBNb25vJywgbW9ub3NwYWNlOyB0ZXh0LWFuY2hvcjogbWlkZGxlOyB9CiAgICAgIC5lZGdlIHsgZmlsbDogbm9uZTsgc3Ryb2tlOiAjNGM1NjY1OyBzdHJva2Utd2lkdGg6IDEuMjsgbWFya2VyLWVuZDogdXJsKCNjb2RlZ3JhcGgtc2V0dXAtZmxvdy1hcnJvdyk7IH0KICAgICAgLnJldHJ5IHsgZmlsbDogbm9uZTsgc3Ryb2tlOiAjNGM1NjY1OyBzdHJva2Utd2lkdGg6IDEuMjsgc3Ryb2tlLWRhc2hhcnJheTogNSA0OyBtYXJrZXItZW5kOiB1cmwoI2NvZGVncmFwaC1zZXR1cC1mbG93LWFycm93KTsgfQogICAgICAuYWNjZXB0ZWQgeyBmaWxsOiBub25lOyBzdHJva2U6ICMxZDRlZDg7IHN0cm9rZS13aWR0aDogMS4yOyBtYXJrZXItZW5kOiB1cmwoI2NvZGVncmFwaC1zZXR1cC1mbG93LWFycm93LWFjY2VudCk7IH0KICAgICAgLmxhYmVsLW1hc2sgeyBmaWxsOiAjZjBlZWU5OyB9CiAgICAgIC5sYWJlbCB7IGZpbGw6ICM0YzU2NjU7IGZvbnQ6IDUwMCAxMHB4ICdHZWlzdCBNb25vJywgbW9ub3NwYWNlOyB0ZXh0LWFuY2hvcjogbWlkZGxlOyB9CiAgICA8L3N0eWxlPgogICAgPG1hcmtlciBpZD0iY29kZWdyYXBoLXNldHVwLWZsb3ctYXJyb3ciIG1hcmtlcldpZHRoPSI4IiBtYXJrZXJIZWlnaHQ9IjYiIHJlZlg9IjciIHJlZlk9IjMiIG9yaWVudD0iYXV0byI+PHBvbHlnb24gcG9pbnRzPSIwIDAsOCAzLDAgNiIgZmlsbD0iIzRjNTY2NSIvPjwvbWFya2VyPgogICAgPG1hcmtlciBpZD0iY29kZWdyYXBoLXNldHVwLWZsb3ctYXJyb3ctYWNjZW50IiBtYXJrZXJXaWR0aD0iOCIgbWFya2VySGVpZ2h0PSI2IiByZWZYPSI3IiByZWZZPSIzIiBvcmllbnQ9ImF1dG8iPjxwb2x5Z29uIHBvaW50cz0iMCAwLDggMywwIDYiIGZpbGw9IiMxZDRlZDgiLz48L21hcmtlcj4KICA8L2RlZnM+CiAgPHJlY3Qgd2lkdGg9IjEyODAiIGhlaWdodD0iNzIwIiBmaWxsPSIjZjBlZWU5Ii8+CiAgPHRleHQgY2xhc3M9ImhlYWRpbmciIHg9IjQwIiB5PSI0OCI+UHJlcGFyZSBhIHNlbGVjdGVkIGxpbmtlZCB3b3JrdHJlZSBpbmRleDwvdGV4dD4KICA8dGV4dCBjbGFzcz0ibm90ZSIgeD0iNDAiIHk9IjcyIj5SZXNvbHZlIHRoZSBzdGFydHVwIGRpcmVjdG9yeSBvciBxdWVyeSBwcm9qZWN0UGF0aCB0byBpdHMgR2l0IHdvcmt0cmVlLiBEbyBub3Qgc2VhcmNoIGNoaWxkIHJlcG9zaXRvcmllcy4gU2VlIHRoZSBSRUFETUUgZm9yIGxvY2sgcmVjb3ZlcnkuPC90ZXh0PgoKICA8IS0tIENvbm5lY3RvcnMgcHJlY2VkZSBsYWJlbHMgYW5kIG5vZGVzLiBUaGUgY29waWVkLWluZGV4IGdhdGUgcnVucyBiZWZvcmUgc3luYy4gLS0+CiAgPGxpbmUgY2xhc3M9ImVkZ2UiIHgxPSIyNjQiIHkxPSIxNDAiIHgyPSIzMjAiIHkyPSIxNDAiLz4KICA8bGluZSBjbGFzcz0iZWRnZSIgeDE9IjU2MCIgeTE9IjE0MCIgeDI9IjY4MCIgeTI9IjE0MCIvPgogIDxsaW5lIGNsYXNzPSJlZGdlIiB4MT0iNDQwIiB5MT0iMjAwIiB4Mj0iNDQwIiB5Mj0iMjg0Ii8+CiAgPHBhdGggY2xhc3M9ImVkZ2UiIGQ9Ik04NjAgMjA4IFYyMzYgUTg2MCAyNDQgODUyIDI0NCBINTY4IFE1NjAgMjQ0IDU2MCAyNTIgVjI4NCIvPgogIDxsaW5lIGNsYXNzPSJlZGdlIiB4MT0iNjAwIiB5MT0iMzM2IiB4Mj0iNjgwIiB5Mj0iMzM2Ii8+CiAgPGxpbmUgY2xhc3M9ImVkZ2UiIHgxPSI4MjAiIHkxPSIzODgiIHgyPSI4MjAiIHkyPSI0MjQiLz4KICA8bGluZSBjbGFzcz0iZWRnZSIgeDE9IjQwMCIgeTE9IjM4OCIgeDI9IjQwMCIgeTI9IjQ3MiIvPgogIDxwYXRoIGNsYXNzPSJyZXRyeSIgZD0iTTY4MCA0OTYgSDY0MCBRNjMyIDQ5NiA2MzIgNDg4IFY0MjQgUTYzMiA0MTYgNjI0IDQxNiBINTM2IFE1MjggNDE2IDUyOCA0MDggVjM4OCIvPgogIDxsaW5lIGNsYXNzPSJhY2NlcHRlZCIgeDE9Ijk2MCIgeTE9IjQ5NiIgeDI9IjEwMDgiIHkyPSI0OTYiLz4KICA8bGluZSBjbGFzcz0iZWRnZSIgeDE9IjExMjQiIHkxPSI1MzYiIHgyPSIxMTI0IiB5Mj0iNjAwIi8+CiAgPHBhdGggY2xhc3M9ImVkZ2UiIGQ9Ik00NjAgNTY4IFY2MjggUTQ2MCA2MzYgNDY4IDYzNiBIMTAwOCIvPgoKICA8cmVjdCBjbGFzcz0ibGFiZWwtbWFzayIgeD0iNjAwIiB5PSIxMTYiIHdpZHRoPSI0MCIgaGVpZ2h0PSIxNCIgcng9IjIiLz4KICA8dGV4dCBjbGFzcz0ibGFiZWwiIHg9IjYyMCIgeT0iMTI2Ij5OTzwvdGV4dD4KICA8cmVjdCBjbGFzcz0ibGFiZWwtbWFzayIgeD0iNDQ4IiB5PSIyMzIiIHdpZHRoPSI0MCIgaGVpZ2h0PSIxNCIgcng9IjIiLz4KICA8dGV4dCBjbGFzcz0ibGFiZWwiIHg9IjQ2OCIgeT0iMjQyIj5ZRVM8L3RleHQ+CiAgPHJlY3QgY2xhc3M9ImxhYmVsLW1hc2siIHg9IjY4MCIgeT0iMjIwIiB3aWR0aD0iNjQiIGhlaWdodD0iMTQiIHJ4PSIyIi8+CiAgPHRleHQgY2xhc3M9ImxhYmVsIiB4PSI3MTIiIHk9IjIzMCI+QUNDRVBUPC90ZXh0PgogIDxyZWN0IGNsYXNzPSJsYWJlbC1tYXNrIiB4PSIyODAiIHk9IjQyNCIgd2lkdGg9IjExMiIgaGVpZ2h0PSIxNCIgcng9IjIiLz4KICA8dGV4dCBjbGFzcz0ibGFiZWwiIHg9IjMzNiIgeT0iNDM0Ij5OT05FIFVTQUJMRTwvdGV4dD4KICA8cmVjdCBjbGFzcz0ibGFiZWwtbWFzayIgeD0iNDcyIiB5PSI0NDAiIHdpZHRoPSIxNTIiIGhlaWdodD0iMTQiIHJ4PSIyIi8+CiAgPHRleHQgY2xhc3M9ImxhYmVsIiB4PSI1NDgiIHk9IjQ1MCI+REVMRVRFICsgUkVUUlk8L3RleHQ+CiAgPHJlY3QgY2xhc3M9ImxhYmVsLW1hc2siIHg9Ijk2NCIgeT0iNDcyIiB3aWR0aD0iNDAiIGhlaWdodD0iMTQiIHJ4PSIyIi8+CiAgPHRleHQgY2xhc3M9ImxhYmVsIiB4PSI5ODQiIHk9IjQ4MiI+UEFTUzwvdGV4dD4KCiAgPCEtLSBOaW5lIG5vZGVzOiBzdGFydCwgcHJpbWFyeSBjaGVjaywgY29uc2VudCwgc2VsZWN0aW9uLCBjb3B5LCBnYXRlLCBzeW5jLCBpbml0LCB3YXRjaGVyLiAtLT4KICA8cmVjdCBjbGFzcz0idGVybWluYWwiIHg9IjQwIiB5PSIxMDAiIHdpZHRoPSIyMjQiIGhlaWdodD0iODAiIHJ4PSIyMCIvPgogIDx0ZXh0IGNsYXNzPSJuYW1lIiB4PSIxNTIiIHk9IjEzNiI+U3RhcnR1cCBvciBxdWVyeTwvdGV4dD4KICA8dGV4dCBjbGFzcz0iZGV0YWlsIiB4PSIxNTIiIHk9IjE1NiI+UmVzb2x2ZWQgR2l0IHdvcmt0cmVlPC90ZXh0PgoKICA8cG9seWdvbiBjbGFzcz0iZGVjaXNpb24iIHBvaW50cz0iNDQwLDgwIDU2MCwxNDAgNDQwLDIwMCAzMjAsMTQwIi8+CiAgPHRleHQgY2xhc3M9Im5hbWUiIHg9IjQ0MCIgeT0iMTM2Ij5QcmltYXJ5IGluZGV4PC90ZXh0PgogIDx0ZXh0IGNsYXNzPSJuYW1lIiB4PSI0NDAiIHk9IjE1NiI+cHJlc2VudD88L3RleHQ+CgogIDxyZWN0IGNsYXNzPSJub2RlIiB4PSI2ODAiIHk9IjgwIiB3aWR0aD0iMzYwIiBoZWlnaHQ9IjEyOCIgcng9IjYiLz4KICA8dGV4dCBjbGFzcz0ibmFtZSIgeD0iODYwIiB5PSIxMDgiPlRleHQgdXNlciBpbnRlcmZhY2UgKFRVSSkgY29uc2VudDwvdGV4dD4KICA8dGV4dCBjbGFzcz0iZGV0YWlsIiB4PSI4NjAiIHk9IjEzMiI+QWNjZXB0OiBpbml0aWFsaXplIHRoZSBwcmltYXJ5IGNoZWNrb3V0PC90ZXh0PgogIDx0ZXh0IGNsYXNzPSJjb2RlIiB4PSI4NjAiIHk9IjE1MiI+Y29kZWdyYXBoIGluaXQgLS15ZXM8L3RleHQ+CiAgPHRleHQgY2xhc3M9ImRldGFpbCIgeD0iODYwIiB5PSIxNzYiPkRlY2xpbmU6IHdyaXRlIHRoZSBtYXJrZXIgYW5kIHN0b3A8L3RleHQ+CiAgPHRleHQgY2xhc3M9ImNvZGUiIHg9Ijg2MCIgeT0iMTkyIj5waS1jb2RlZ3JhcGgtZGVjbGluZWQ8L3RleHQ+CgogIDxyZWN0IGNsYXNzPSJub2RlIiB4PSIzMjAiIHk9IjI4NCIgd2lkdGg9IjI4MCIgaGVpZ2h0PSIxMDQiIHJ4PSI2Ii8+CiAgPHRleHQgY2xhc3M9Im5hbWUiIHg9IjQ2MCIgeT0iMzEyIj5QaWNrIHRoZSBjbG9zZXN0IHNlZWQgaW5kZXg8L3RleHQ+CiAgPHRleHQgY2xhc3M9ImRldGFpbCIgeD0iNDYwIiB5PSIzMzYiPkNvbXBsZXRlLCBjb21wYXRpYmxlLCBzYW1lIHJlcG9zaXRvcnk8L3RleHQ+CiAgPHRleHQgY2xhc3M9ImRldGFpbCIgeD0iNDYwIiB5PSIzNjAiPkZld2VzdCBjaGFuZ2VkIGZpbGVzIGFnYWluc3Qgd29ya3RyZWUgSEVBRDwvdGV4dD4KCiAgPHJlY3QgY2xhc3M9Im5vZGUiIHg9IjY4MCIgeT0iMjg0IiB3aWR0aD0iMjgwIiBoZWlnaHQ9IjEwNCIgcng9IjYiLz4KICA8dGV4dCBjbGFzcz0ibmFtZSIgeD0iODIwIiB5PSIzMTYiPkNvcHkgdW5kZXIgdGhlIHNvdXJjZSB3cml0ZXIgbG9jazwvdGV4dD4KICA8dGV4dCBjbGFzcz0iY29kZSIgeD0iODIwIiB5PSIzNDAiPi5jb2RlZ3JhcGgvY29kZWdyYXBoLmxvY2s8L3RleHQ+CiAgPHRleHQgY2xhc3M9ImRldGFpbCIgeD0iODIwIiB5PSIzNjQiPlNraXAgYSBsb2NrZWQgc291cmNlOyB0cnkgdGhlIG5leHQgaW5kZXg8L3RleHQ+CgogIDxwb2x5Z29uIGNsYXNzPSJnYXRlIiBwb2ludHM9IjgyMCw0MjQgOTYwLDQ5NiA4MjAsNTY4IDY4MCw0OTYiLz4KICA8dGV4dCBjbGFzcz0ibmFtZSIgeD0iODIwIiB5PSI0NjgiPkFjY2VwdCB0aGlzIGNvcHk/PC90ZXh0PgogIDx0ZXh0IGNsYXNzPSJjb2RlIiB4PSI4MjAiIHk9IjQ4OCI+Y29kZWdyYXBoIHN0YXR1cyAtLWpzb248L3RleHQ+CiAgPHRleHQgY2xhc3M9ImNvZGUiIHg9IjgyMCIgeT0iNTA4Ij5leGl0IDAgwrcgY29tcGxldGU8L3RleHQ+CiAgPHRleHQgY2xhc3M9ImNvZGUiIHg9IjgyMCIgeT0iNTI4Ij5yZWluZGV4UmVjb21tZW5kZWQ6ZmFsc2U8L3RleHQ+CgogIDxyZWN0IGNsYXNzPSJub2RlIiB4PSIxMDA4IiB5PSI0NTYiIHdpZHRoPSIyMzIiIGhlaWdodD0iODAiIHJ4PSI2Ii8+CiAgPHRleHQgY2xhc3M9Im5hbWUiIHg9IjExMjQiIHk9IjQ4NCI+U3luY2hyb25pemUgdGhlIGFjY2VwdGVkIGNvcHk8L3RleHQ+CiAgPHRleHQgY2xhc3M9ImNvZGUiIHg9IjExMjQiIHk9IjUwOCI+Y29kZWdyYXBoIHN5bmMgJmx0O3dvcmt0cmVlLXJvb3QmZ3Q7PC90ZXh0PgoKICA8cmVjdCBjbGFzcz0ibm9kZSIgeD0iMzIwIiB5PSI0NzIiIHdpZHRoPSIyODAiIGhlaWdodD0iOTYiIHJ4PSI2Ii8+CiAgPHRleHQgY2xhc3M9Im5hbWUiIHg9IjQ2MCIgeT0iNTA0Ij5DcmVhdGUgYSBuZXcgd29ya3RyZWUgaW5kZXg8L3RleHQ+CiAgPHRleHQgY2xhc3M9ImNvZGUiIHg9IjQ2MCIgeT0iNTMyIj5jb2RlZ3JhcGggaW5pdCAtLXllcyAmbHQ7d29ya3RyZWUtcm9vdCZndDs8L3RleHQ+CgogIDxyZWN0IGNsYXNzPSJ0ZXJtaW5hbCIgeD0iMTAwOCIgeT0iNjAwIiB3aWR0aD0iMjMyIiBoZWlnaHQ9IjcyIiByeD0iMjAiLz4KICA8dGV4dCBjbGFzcz0ibmFtZSIgeD0iMTEyNCIgeT0iNjI4Ij5PbmUgd2F0Y2hlciBwZXIgd29ya3RyZWU8L3RleHQ+CiAgPHRleHQgY2xhc3M9ImRldGFpbCIgeD0iMTEyNCIgeT0iNjQ4Ij5JbmNsdWRlcyB1bmNvbW1pdHRlZCBlZGl0czwvdGV4dD4KCiAgPHRleHQgY2xhc3M9Im5vdGUiIHg9IjQwIiB5PSI2ODAiPkRhc2hlZCBwYXRoOiByZWplY3QgdGhlIGNvcHkgYW5kIHRyeSB0aGUgbmV4dCBzZWVkIGluZGV4LiBTZXR1cCBmYWlsdXJlcyBzdG9wOyBzZWUgTGltaXRzIGFuZCByZWNvdmVyeS48L3RleHQ+Cjwvc3ZnPgo=) Setup starts with Pi for its session worktree. A query starts setup for another explicitly selected worktree. Git worktree creation does not start setup. In the TUI, startup setup runs in the background. Remote procedure call (RPC), print, and JavaScript Object Notation (JSON) modes do not ask for consent. RPC waits for startup 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. The MCP file watcher updates each selected checkout's separate index, including uncommitted edits. Selecting another repository does not stop earlier watchers. Pi starts watcher connections asynchronously; a successful query does not prove that a watcher is ready or that all edits are indexed. Sessions share one CodeGraph daemon per checkout. It stops five minutes after its last connection 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. 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`. Concurrent queries to one worktree share setup and watcher registration. Worktrees in the same repository share consent and pending primary initialization, but keep separate worktree locks. Accepted consent is not saved after primary setup ends. A failed or interrupted consent request does not record a decline. Cancelling one query stops its wait, not the shared setup. Creating, resuming, or forking a session waits for active initialization. Pi closes watcher connections and recreates the extension. In a non-Git workspace, query each selected worktree again to start its watcher in the new session. Selections do not persist across sessions. Quitting or reloading Pi cancels setup and removes all owned watcher registrations. Interrupted initialization 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 | Uses `codegraph status --json`; `--json` selects JSON output. Accepts the copy only with exit code 0, `index.state:"complete"`, and `index.reindexRecommended:false`. | | Accepted copy | Runs `codegraph sync ` after the status check. | | Rejected copy | Deletes the copy and tries the next index. | | No usable index | Runs `codegraph init --yes `. | 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 The `--version` option prints the CodeGraph version. 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: ```bash 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 selected worktree can start a daemon that uses approximately 230 megabytes of memory. Selecting more worktrees increases resource use until the session ends or Pi reloads. The `--no-mcp` option disables Pi's built-in MCP support. Without MCP, queries can use existing indexes, but automatic updates do not run. Run `codegraph sync` in each checkout to update its index. Pi can also report that no MCP handler connects the registered servers. The session worktree keeps the server name `pi-codegraph`. Other worktrees use `pi-codegraph-`. These names stay the same across reloads. A server in `mcp.json` with the same name replaces that extension registration. Use `/mcp` to inspect names, overrides, and connection status.