# @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

```sh
pi install npm:@isac322/pi-codegraph
```

### OMP

```sh
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`.

```json
{
  "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

```sh
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](https://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](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