@isac322/pi-codegraph

CodeGraph tools for Pi and OMP, with worktree-aware index lifecycle management.

Why this package

The extension exposes CodeGraph's structural tools with native Pi metadata and rendering while keeping OMP on its native MCP path. Indexes are separated per worktree, stored centrally, synchronized automatically, identity-checked, and garbage-collected after worktrees disappear.

Install

Pi

pi install npm:@isac322/pi-codegraph

OMP

omp install @isac322/pi-codegraph
omp plugin list

Restart OMP or run /reload-plugins after installation. omp install uses the user scope by default.

OMP loads the package-local .mcp.json and omp.extensions entry. Pi loads pi.extensions and starts the internal MCP facade at session start, never during extension discovery.

The package installs @colbymchenry/codegraph@1.6.2 as an optional dependency and falls back to a codegraph executable on PATH.

Node.js 22.19 through Node 24 is required. OMP itself may run under Bun, but it starts this package's compiled MCP facade with the node command declared in .mcp.json; MCP child processes do not inherit or need to match the host agent's runtime.

The repository contains TypeScript source only. Release builds compile it into dist, and the npm tarball includes the compiled JavaScript, declarations, and source maps rather than the TypeScript runtime source.

Tools

• codegraph_explore: broad architecture and flow exploration with line-numbered source
• codegraph_search: symbol-name lookup
• codegraph_node: indexed file reading, symbol inspection, and file/line disambiguation
• codegraph_files: indexed project structure
• codegraph_callers: inbound calls, optionally narrowed to a definition file
• codegraph_callees: outbound calls, optionally narrowed to a definition file
• codegraph_impact: transitive change impact, optionally narrowed to a definition file
• codegraph_status: CodeGraph index health

codegraph_node accepts file without symbol to return current source with line numbers and dependents. Use offset and limit for a line range, symbolsOnly for a structural overview, or combine symbol with file or line to select a same-named definition.

Pi adds compact call/result rendering and /codegraph status|sync|doctor|gc.

Worktrees

Each worktree gets a distinct database. New indexes are stored under the configured central index store and exposed to CodeGraph through the worktree's .codegraph symlink. Existing real .codegraph directories remain in place and receive identity metadata.

A project path is accepted only when it is inside an allowed root or resolves to a worktree with the same Git common directory as the session root. Repository and worktree identities are checked before an index is reused. Missing or replaced worktrees fail closed.

Projects listed in excludedProjectRoots are never indexed. Sessions started in an excluded project skip CodeGraph initialization and prompt guidance, and tool calls for it return an error. Nothing is excluded by default.

Garbage collection runs when the facade starts and then hourly. It removes managed indexes whose worktree is gone, was replaced, or is now excluded. It also removes index directories that never received metadata once no prepare holds their lock and they have been untouched for 24 hours. Collection waits while the shared daemon or a project writer may still hold a database open. Live, malformed, or changing ownership records retain the index; removal reserves CodeGraph's rebuild lock before deleting a verified stale index.

Configuration

Global configuration is read from ~/.config/pi-codegraph/config.json, or from PI_CODEGRAPH_CONFIG.

{
  "autoSync": true,
  "autoGc": true,
  "indexStore": "/home/me/.cache/pi-codegraph",
  "workerIdleTimeoutMs": 300000,
  "maxWorkers": 6,
  "requestTimeoutMs": 30000,
  "syncMinIntervalMs": 15000,
  "maxOutputChars": 60000,
  "allowedProjectRoots": ["/work/company"],
  "excludedProjectRoots": ["/tmp", "~/scratch/**"],
  "promptInjection": true,
  "codegraphExecutable": ""
}

Environment overrides:

• PI_CODEGRAPH_AUTO_SYNC
• PI_CODEGRAPH_AUTO_GC
• PI_CODEGRAPH_INDEX_STORE
• PI_CODEGRAPH_WORKER_IDLE_MS
• PI_CODEGRAPH_MAX_WORKERS
• PI_CODEGRAPH_REQUEST_TIMEOUT_MS
• PI_CODEGRAPH_SYNC_MIN_INTERVAL_MS
• PI_CODEGRAPH_MAX_OUTPUT_CHARS
• PI_CODEGRAPH_ALLOWED_ROOTS
• PI_CODEGRAPH_EXCLUDED_ROOTS
• PI_CODEGRAPH_PROMPT_INJECTION
• PI_CODEGRAPH_EXECUTABLE

PI_CODEGRAPH_ALLOWED_ROOTS and PI_CODEGRAPH_EXCLUDED_ROOTS use the platform path delimiter.

An excludedProjectRoots entry matches a project whose root is exactly that directory. Add /** to also exclude every project below it. For example, "/tmp" stops a session started in /tmp from indexing the whole temp directory but still indexes a Git worktree at /tmp/fix-123, while "/tmp/**" excludes both. Entries may start with ~. Symlinks are resolved, so /tmp also matches /private/tmp on macOS.

Runtime behavior

• Pi defers process startup until session_start and closes all resources on session_shutdown.
• OMP uses the package-local MCP server and its native tool_call hook. For CodeGraph MCP tools, an omitted projectPath is rewritten to the trusted session ctx.cwd; an explicit path, sibling worktree, and unrelated OMP tool are left unchanged.
• Workers are capped, evicted by least-recently-used idle order, and terminated after the idle timeout.
• Tool cancellation and timeout propagate to the worker. Diagnostics are ANSI-stripped, size-limited, and redact common token and secret forms.
• On the first prepare after a CodeGraph engine upgrade, the facade checks the index extraction version and performs one quiet full rebuild when CodeGraph marks it stale. The rebuild runs independently of a client request timeout. A successful check is cached for the facade's lifetime; a status or rebuild failure preserves the existing index and allows a later prepare to check again.
• codegraph_files.path and supported tool file arguments accept absolute in-project paths and ~; the facade normalizes them to repo-relative POSIX paths.
• Large results are bounded and retain both their beginning and end with an explicit truncation marker.
• After CodeGraph initializes, rebuilds, or syncs an index, the facade truncates the SQLite write-ahead log so a large indexing transaction does not leave a WAL file as large as the data it wrote. A reader holding the log only postpones this until the next sync.

Development

npm ci
npm run typecheck
npm run build

npm pack and local npm publish run the build through prepack. Pull requests and releases run the shared Release QA workflow, including both supported Node versions, OMP, Pi, shared-daemon integration, and an installed-package smoke test. The release workflow checks the exact revision before Release Please creates a tag, then typechecks and builds the tagged distribution before publishing through npm OIDC.

Security

Pi checks project trust before initialization or tool execution. The MCP facade resolves real paths and restricts access to the active workspace, sibling worktrees of the same repository, and explicitly configured roots.

Pi package gallery

The npm package declares the pi-package keyword and an explicit pi.extensions manifest. After npm publication, Pi's package gallery can index it at pi.dev/packages.

Releases are managed by Release Please. Conventional commits on main update a release PR. Merging that PR updates package.json and CHANGELOG.md, creates the version tag and GitHub Release, and publishes the package through npm trusted publishing in the same workflow. See CONTRIBUTING.md for the version rules and release process.

Use fix: for patch releases, feat: for minor releases, and a ! or BREAKING CHANGE: footer for major releases. Configure the npm trusted publisher with GitHub owner isac322, repository pi-codegraph, workflow filename publish.yml, no environment, and the npm publish action.

Shared daemon lifecycle

All Pi and OMP sessions that use the same indexStore attach to one CodeGraph daemon. Each tool request forwards its canonical projectPath, so the daemon can serve multiple repositories and Git worktrees without merging their indexes.

maxWorkers controls the shared daemon's query worker count. workerIdleTimeoutMs controls how long the daemon remains alive after the last Pi or OMP client disconnects; the default is five minutes. Set the same indexStore for every session that should share a daemon.

License

MIT