@bopstack/pi-codegraph

CodeGraph-powered code intelligence for Pi and Oh My Pi.

Get started · Actions · Workflows · Development

@bopstack/pi-codegraph adds one action-first codegraph tool to Pi and Oh My Pi. It lets an agent explore an indexed codebase, read exact source, trace dependencies, estimate impact, identify affected tests, and maintain the local CodeGraph index—without a slash command or JSON-wrapped output.

Calls are rendered as their equivalent CodeGraph CLI command, while results remain plain text for direct use in an agent session.

Highlights

• One focused tool. Every capability is selected with a required action field.
• Code-aware investigation. Explore architecture, inspect symbols or files, browse indexed files, and search for names.
• Change planning support. Trace callers and callees, estimate symbol impact, and find likely affected tests.
• Local index maintenance. Check status, initialize, refresh, fully rebuild, or unlock an index when needed.
• Safe agent boundary. Destructive, interactive, package-management, and other setup/admin commands stay out of the tool.
• Readable large results. ANSI sequences are removed; output over 50 KiB or 3,000 lines is truncated with a path to its complete temporary file.

Requirements

• Pi or Oh My Pi
• CodeGraph CLI on PATH wherever the tool runs
• Node.js 22.19.0+ and pnpm 11.3.0+ when developing this package

Get started

Install from npm

# Pi
pi install npm:@bopstack/pi-codegraph

# Oh My Pi
omp install @bopstack/pi-codegraph

The package registers src/index.ts as an extension for both hosts.

Develop from a checkout

git clone https://github.com/bopstack/pi-codegraph.git
cd pi-codegraph
pnpm install

# Load the extension from this checkout.
pi -e .
# or
omp -e .

The package declares extension entrypoints for both Pi and Oh My Pi.

Install and initialize CodeGraph

# Once per machine
npm install -g @colbymchenry/codegraph

# In each project you want to inspect
cd /path/to/project
codegraph init

[!NOTE] codegraph init creates the local CodeGraph state and builds the initial index. Use codegraph status to confirm that an existing index is healthy, codegraph sync after edits, and codegraph index when a full rebuild is required.

Verify the setup

First, verify the local CLI:

codegraph status

Then, in Pi or Oh My Pi, ask the registered tool about the same project:

codegraph({ action: "status" })

Use the tool

Every call requires action. Parameters are ordinary tool fields—do not wrap them in a JSON string.

codegraph({
  action: "explore",
  query: "How is authentication established and propagated?",
  max_files: 8,
})

Pi and Oh My Pi render that call in CLI form:

codegraph explore "How is authentication established and propagated?" --max-files 8

[!TIP] Start unfamiliar-code and edit-preparation questions with explore. It returns relevant source and call paths in one result; follow with node when you need exact source and line numbers.

Action contract

• action is mandatory for every call.
• node needs at least one of file or symbol; when both are present, file identifies the target.
• search maps to the CLI command codegraph query; help is generated by the extension; the remaining supported actions map directly to CodeGraph CLI commands.
• project_path selects a project for applicable actions. It maps to --path for graph-query actions and to the CLI's positional path for status and index-maintenance actions.
• Use help for the full generated reference, including required and optional fields for every action.

Actions

Explore and read

Trace change impact

Maintain the local index

Workflows

Understand an unfamiliar area

codegraph({ action: "status" })
codegraph({ action: "explore", query: "Where is a user session created?" })
codegraph({ action: "node", symbol: "create_session" })

Prepare a focused change

codegraph({ action: "search", query: "create_session", kind: "function" })
codegraph({ action: "callers", symbol: "create_session" })
codegraph({ action: "callees", symbol: "create_session" })
codegraph({ action: "impact", symbol: "create_session", depth: 2 })

Find tests after editing

codegraph({ action: "sync" })
codegraph({ action: "affected", files: ["src/session.ts"], depth: 2 })

Safety and output behavior

The tool runs CodeGraph without shell interpolation and returns text rather than a JSON envelope. It strips terminal control sequences and preserves the full output in a temporary file when the agent-facing result exceeds its display limit.

[!IMPORTANT] init, index, and unlock are caution actions because they operate on local index state. Forced init or index requests are blocked for the home directory, filesystem root, and Windows drive roots. Use force only for an explicit project directory when a full re-index is required.

These CodeGraph commands are intentionally unsupported through the agent tool: uninit, uninstall, daemon, daemons, install, install_config, telemetry, upgrade, upgrade_check, and version. For each, the tool returns a reason and a safe CLI alternative for a human operator.

Troubleshooting

Development

git clone https://github.com/bopstack/pi-codegraph.git
cd pi-codegraph
pnpm install

# Load the extension from this checkout.
pi -e .
# or
omp -e .

Quality checks

pnpm check      # Biome check, TypeScript typecheck, and Vitest
pnpm test       # Vitest test suite
pnpm typecheck  # tsc --noEmit
pnpm lint       # Biome lint

CI runs pnpm check and verifies the publishable package with npm pack --dry-run.

Project layout

src/
├── index.ts        Extension registration and tool schema
├── descriptors.ts  Action metadata and CLI argument mapping
├── router.ts       Validation, dispatch, and force guard
├── run.ts          Streaming CodeGraph CLI execution
├── output.ts       Text formatting and truncation
├── help.ts         Generated action reference
└── *.test.ts       Colocated Vitest coverage