pi-gortex

A Pi extension that gives the agent Gortex's code-graph tools, and applies Gortex's read-discipline decisions to Pi's own tools.

What is Gortex?

A code-intelligence engine that indexes your repositories into a queryable knowledge graph of functions, classes, call chains, routes and cross-service contracts, and serves it over MCP. Agents look up exactly the symbol they need instead of reading whole files around it, which is where the token savings come from. It is a single static binary with no dependency chain, and it covers 257 languages through tree-sitter.

This extension connects the two. It hands gortex mcp to Pi's built-in MCP, and read discipline goes through gortex hook.

What it does

• Hands Gortex's graph tools to Pi's built-in MCP, which offers them to the model as mcp__gortex__<tool>. The rest of the catalogue is discovered through the daemon's own tools_search.
• Applies read discipline. Pi's tool calls are forwarded to gortex hook --agent=pi, which answers block / soft guidance / nothing according to the posture you configured. Gortex owns that logic, so the behaviour matches every other agent it integrates with.
• Briefs the model once per session with Gortex's orientation for the current repository.
• Points each prompt at relevant code. A prompt typed while Pi is idle is sent to Gortex, and the graph symbols it finds relevant ride the turn as a hidden message.

See docs/architecture.md for how it works.

Requirements

• Node 24+, Pi 1.0+ with its built-in MCP loaded (not --no-mcp)
• The gortex binary on PATH, v0.61.2 or newer. See Gortex installation. gortex mcp starts the shared daemon itself, and the extension never blocks Pi's startup on it. It warns you on the first turn when the daemon is older than that. Run gortex upgrade to fix it.

Install

Add it to Pi's settings, ~/.pi/agent/settings.json for every project or <project>/.pi/settings.json for one:

{
  "packages": ["npm:pi-gortex"]
}

Leave the spec unpinned: Pi skips pinned specs during pi update.

For local development, point Pi at a checkout instead: a packages entry with the absolute path, or a single run with pi -e /path/to/pi-gortex.

Configure

Zero configuration required. Every value resolves at runtime, first hit wins: environment -> <session cwd>/.pi/gortex.json -> <agent dir>/extensions/gortex.json (agent dir is $PI_CODING_AGENT_DIR, else ~/.pi/agent) -> defaults.

Sidecar key	Environment	Default	Meaning
bin	GORTEX_BIN	gortex on PATH	The gortex binary. Read from the global sidecar only; a project file cannot set it. ~ expands, and a relative path resolves against the sidecar's directory (the launch directory for GORTEX_BIN).
hook_mode	GORTEX_HOOK_MODE	deny	Posture: deny, enrich, consult-unlock, nudge (adaptive-nudge is an alias).
enforce	GORTEX_ENFORCE	true	false keeps the graph tools and the briefing, and wires no enforcement.
tools_preset	GORTEX_TOOLS	daemon's default	Eager MCP surface: a Gortex preset (core, full, agent, edit, nav, readonly, localization), optionally followed by comma-separated tool names and +tool/-tool changes, e.g. nav,+edit_file. A value that does not open with a preset is ignored.

{
  "bin": "/usr/local/bin/gortex",
  "hook_mode": "enrich",
  "enforce": true
}

The extension reads its configuration at every session start, from the directory the session runs in, so a change takes effect on /reload or /new.

Pi's own mcp.json wins. The extension registers a server named gortex. A gortex entry in ~/.pi/agent/mcp.json or .pi/mcp.json replaces it, including its exposure, and Pi's default exposure there is codemode, which keeps the tools out of the model's tool list. Leave Gortex out of mcp.json, or set "exposure": "direct" on that entry. A Gortex server configured under another name runs as a second connection, and read discipline treats its tools as non-graph calls.

If the graph tools go missing, the first turn of the session says so and why: Pi's MCP support is not loaded, the gortex binary was not found, or Pi refused the registration. Fix the cause, then /reload, or restart Pi with MCP enabled when it was turned off. The extension fails open, always: an absent binary or a daemon that is down costs the session its graph tools, never the session. When the first turn finds no graph tools, Pi's own tools are not held to read discipline until some appear.

Develop

npm install
npm test         # node --test
npm run typecheck
npm run check    # both

Zero runtime dependencies. Pi's extension loader resolves Pi's own packages to the running Pi, so they are imported freely and kept in devDependencies, and the package also loads as a bare directory extension with no node_modules beside it.

The suites drive the extension through Pi's own ExtensionRunner; docs/tests.md explains the approach and the rules a suite follows.

License

Apache License 2.0, the same license as gortex itself.