@vndv/pi-codegraph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Matveev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# pi-codegraph
+
+Pi package that adds CodeGraph tools to Pi Agent.
+
+## Requirements
+
+Node.js 22 LTS is recommended. CodeGraph blocks Node.js 25 because of a V8 WASM JIT bug in tree-sitter grammar compilation.
+
+Pi provides the package extension runtime and core libraries. This package declares `@earendil-works/pi-coding-agent` and `typebox` as peer dependencies, as required by Pi package loading.
+
+CodeGraph must already be installed and available on `PATH`:
+
+```bash
+npm install -g @colbymchenry/codegraph
+```
+
+Projects must be indexed before Pi can query them:
+
+```bash
+cd /path/to/project
+codegraph init -i
+```
+
+## Install
+
+From GitHub:
+
+```bash
+pi install https://github.com/vndv/pi-codegraph
+```
+
+From npm:
+
+```bash
+pi install npm:@vndv/pi-codegraph@0.1.0
+```
+
+This works only after `@vndv/pi-codegraph@0.1.0` has been published to npm. If npm returns `404 Not Found`, use the GitHub or local development install until the first npm publish is complete.
+
+Local development install:
+
+```bash
+git clone https://github.com/vndv/pi-codegraph.git
+cd pi-codegraph
+pi install "$(pwd)"
+```
+
+Verify Pi sees the package:
+
+```bash
+pi list
+```
+
+## Uninstall
+
+Remove the package using the same source shown by `pi list`:
+
+```bash
+pi remove https://github.com/vndv/pi-codegraph
+```
+
+If you installed from npm or a local path, remove that exact entry instead:
+
+```bash
+pi remove npm:@vndv/pi-codegraph@0.1.0
+pi remove /path/to/pi-codegraph
+```
+
+Then start Pi inside an indexed project:
+
+```bash
+cd /path/to/project
+pi
+```
+
+Example prompt:
+
+```text
+Use CodeGraph. Show project structure and main entry points.
+```
+
+## Tools
+
+This package registers:
+
+- `codegraph_search`
+- `codegraph_context`
+- `codegraph_callers`
+- `codegraph_callees`
+- `codegraph_impact`
+- `codegraph_explore`
+- `codegraph_node`
+- `codegraph_status`
+- `codegraph_files`
+- `codegraph_trace`
+
+Each tool proxies to:
+
+```bash
+codegraph serve --mcp --path <project>
+```
+
+For broad code questions, Pi should prefer `codegraph_context`. For known symbols, use `codegraph_node`. Use `codegraph_search` for declaration/symbol lookup, not literal constants or arbitrary text.
+
+## Development
+
+```bash
+npm ci
+npm run ci
+```
+
+## Release
+
+Run the full local package check before publishing:
+
+```bash
+npm run ci
+npm pack --dry-run
+```
+
+First npm publish:
+
+```bash
+npm login
+npm publish --access public
+```
+
+Future releases use Changesets:
+
+```bash
+npx changeset
+npm run local-release
+```
+
+GitHub publishing is also supported:
+
+1. Add `NPM_TOKEN` repository secret in GitHub.
+2. Update the package version with Changesets or by editing `package.json`.
+3. Commit and push to `main`.
+4. Create a GitHub release for the version tag.
+
+The publish workflow runs `npm publish --provenance`.

package/extensions/codegraph.ts

@@ -0,0 +1,306 @@
+import { spawn } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import type { Static } from "typebox";
+import { Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const OptionalProjectPath = Type.Optional(Type.String({
+  description: "Path to a different project with .codegraph/ initialized. Defaults to current project.",
+}));
+
+const ToolKind = Type.Optional(Type.Union([
+  Type.Literal("function"),
+  Type.Literal("method"),
+  Type.Literal("class"),
+  Type.Literal("interface"),
+  Type.Literal("type"),
+  Type.Literal("variable"),
+  Type.Literal("route"),
+  Type.Literal("component"),
+]));
+
+const ToolDefinitions = [
+  {
+    name: "codegraph_search",
+    label: "CodeGraph Search",
+    description: "Quick symbol search by name. Returns locations only.",
+    parameters: Type.Object({
+      query: Type.String({ description: "Symbol name or partial name." }),
+      kind: ToolKind,
+      limit: Type.Optional(Type.Number({ default: 10 })),
+      projectPath: OptionalProjectPath,
+    }),
+  },
+  {
+    name: "codegraph_context",
+    label: "CodeGraph Context",
+    description: "Primary tool for architecture, feature, bug-context, or how-does-X-work questions.",
+    parameters: Type.Object({
+      task: Type.String({ description: "Task, question, or code area to understand." }),
+      maxNodes: Type.Optional(Type.Number({ default: 20 })),
+      includeCode: Type.Optional(Type.Boolean({ default: true })),
+      projectPath: OptionalProjectPath,
+    }),
+  },
+  {
+    name: "codegraph_callers",
+    label: "CodeGraph Callers",
+    description: "Find all functions or methods that call a specific symbol.",
+    parameters: Type.Object({
+      symbol: Type.String(),
+      limit: Type.Optional(Type.Number({ default: 20 })),
+      projectPath: OptionalProjectPath,
+    }),
+  },
+  {
+    name: "codegraph_callees",
+    label: "CodeGraph Callees",
+    description: "Find all functions or methods that a specific symbol calls.",
+    parameters: Type.Object({
+      symbol: Type.String(),
+      limit: Type.Optional(Type.Number({ default: 20 })),
+      projectPath: OptionalProjectPath,
+    }),
+  },
+  {
+    name: "codegraph_impact",
+    label: "CodeGraph Impact",
+    description: "Analyze the impact radius of changing a symbol.",
+    parameters: Type.Object({
+      symbol: Type.String(),
+      depth: Type.Optional(Type.Number({ default: 2 })),
+      projectPath: OptionalProjectPath,
+    }),
+  },
+  {
+    name: "codegraph_explore",
+    label: "CodeGraph Explore",
+    description: "Return source for several related symbols grouped by file.",
+    parameters: Type.Object({
+      query: Type.String({ description: "Specific symbols, files, or code terms to explore." }),
+      maxFiles: Type.Optional(Type.Number({ default: 12 })),
+      projectPath: OptionalProjectPath,
+    }),
+  },
+  {
+    name: "codegraph_node",
+    label: "CodeGraph Node",
+    description: "Get one symbol's details plus callers and callees trail.",
+    parameters: Type.Object({
+      symbol: Type.String(),
+      includeCode: Type.Optional(Type.Boolean({ default: false })),
+      projectPath: OptionalProjectPath,
+    }),
+  },
+  {
+    name: "codegraph_status",
+    label: "CodeGraph Status",
+    description: "Get CodeGraph index status.",
+    parameters: Type.Object({
+      projectPath: OptionalProjectPath,
+    }),
+  },
+  {
+    name: "codegraph_files",
+    label: "CodeGraph Files",
+    description: "Get project file structure from the CodeGraph index.",
+    parameters: Type.Object({
+      path: Type.Optional(Type.String()),
+      pattern: Type.Optional(Type.String()),
+      format: Type.Optional(Type.Union([
+        Type.Literal("tree"),
+        Type.Literal("flat"),
+        Type.Literal("grouped"),
+      ], { default: "tree" })),
+      includeMetadata: Type.Optional(Type.Boolean({ default: true })),
+      maxDepth: Type.Optional(Type.Number()),
+      projectPath: OptionalProjectPath,
+    }),
+  },
+  {
+    name: "codegraph_trace",
+    label: "CodeGraph Trace",
+    description: "Trace the call path between two symbols.",
+    parameters: Type.Object({
+      from: Type.String(),
+      to: Type.String(),
+      projectPath: OptionalProjectPath,
+    }),
+  },
+] as const;
+
+type ToolName = (typeof ToolDefinitions)[number]["name"];
+type ToolParams = Record<string, unknown> & { projectPath?: string };
+type JsonRpcRequest = (method: string, params: Record<string, unknown>) => Promise<any>;
+
+export const codegraphToolNames = ToolDefinitions.map((tool) => tool.name);
+
+export async function withCodeGraphMcp<T>(
+  projectPath: string | undefined,
+  signal: AbortSignal | undefined,
+  fn: (request: JsonRpcRequest) => Promise<T>,
+): Promise<T> {
+  const cwd = projectPath || process.cwd();
+  const child = spawn("codegraph", ["serve", "--mcp", "--path", cwd], {
+    cwd,
+    env: process.env,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  return runJsonRpcSession(child, cwd, signal, fn);
+}
+
+async function runJsonRpcSession<T>(
+  child: ChildProcessWithoutNullStreams,
+  cwd: string,
+  signal: AbortSignal | undefined,
+  fn: (request: JsonRpcRequest) => Promise<T>,
+): Promise<T> {
+  let nextId = 1;
+  let stdout = "";
+  let stderr = "";
+  const pending = new Map<number, {
+    resolve: (value: any) => void;
+    reject: (error: Error) => void;
+  }>();
+
+  const cleanup = () => {
+    for (const entry of pending.values()) {
+      entry.reject(new Error("CodeGraph MCP process closed before responding."));
+    }
+    pending.clear();
+    if (!child.killed) child.kill();
+  };
+
+  const onAbort = () => cleanup();
+  signal?.addEventListener("abort", onAbort, { once: true });
+
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk.toString("utf-8");
+    let newline;
+    while ((newline = stdout.indexOf("\n")) !== -1) {
+      const line = stdout.slice(0, newline).trim();
+      stdout = stdout.slice(newline + 1);
+      if (!line) continue;
+
+      let msg: any;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue;
+      }
+
+      if (msg.id !== undefined && pending.has(msg.id)) {
+        const { resolve, reject } = pending.get(msg.id)!;
+        pending.delete(msg.id);
+        if (msg.error) reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+        else resolve(msg.result);
+      }
+    }
+  });
+
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk.toString("utf-8");
+  });
+
+  child.on("error", (err) => {
+    for (const entry of pending.values()) entry.reject(err);
+    pending.clear();
+  });
+
+  child.on("exit", (code) => {
+    if (pending.size === 0) return;
+    const msg = stderr.trim() || `CodeGraph MCP process exited with code ${code}`;
+    for (const entry of pending.values()) entry.reject(new Error(msg));
+    pending.clear();
+  });
+
+  const sendRequest: JsonRpcRequest = (method, params) => {
+    const id = nextId++;
+    const payload = { jsonrpc: "2.0", id, method, params };
+    const promise = new Promise<any>((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+    });
+    child.stdin.write(`${JSON.stringify(payload)}\n`);
+    return promise;
+  };
+
+  const sendNotification = (method: string, params: Record<string, unknown>) => {
+    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+  };
+
+  try {
+    const rootUri = pathToFileURL(cwd).href;
+    await sendRequest("initialize", {
+      protocolVersion: "2024-11-05",
+      rootUri,
+      workspaceFolders: [{ uri: rootUri, name: cwd.split(/[\\/]/).pop() || cwd }],
+      capabilities: {},
+      clientInfo: { name: "pi-codegraph", version: "0.1.0" },
+    });
+    sendNotification("initialized", {});
+    return await fn(sendRequest);
+  } finally {
+    signal?.removeEventListener("abort", onAbort);
+    cleanup();
+  }
+}
+
+export async function callCodeGraphTool(
+  name: ToolName,
+  params: ToolParams,
+  signal?: AbortSignal,
+): Promise<string> {
+  const projectPath = typeof params.projectPath === "string" ? params.projectPath : undefined;
+  const result = await withCodeGraphMcp(projectPath, signal, (request) =>
+    request("tools/call", {
+      name,
+      arguments: params || {},
+    })
+  );
+
+  const text = (result?.content || [])
+    .filter((part: any) => part?.type === "text")
+    .map((part: any) => part.text)
+    .join("\n");
+
+  if (result?.isError) throw new Error(text || "CodeGraph tool failed.");
+  return text || JSON.stringify(result);
+}
+
+export default function codegraphExtension(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", async (event) => {
+    const guidance = [
+      "CodeGraph tools are available as codegraph_* Pi tools.",
+      "For architecture, flow, where-is-symbol, impact, and codebase navigation questions, use CodeGraph tools directly before grep/read.",
+      "Use codegraph_context first for broad questions, codegraph_search for symbol-name lookup, codegraph_files for project structure, codegraph_node for a known symbol, and codegraph_trace for call paths.",
+      "If codegraph_search returns no exact result, try codegraph_context or codegraph_files/codegraph_explore before falling back to grep/read; CodeGraph symbol search may miss literal constants or generated names that still exist in source text.",
+      "Only use grep/read after CodeGraph is insufficient or when the user asks for literal text matching.",
+    ].join("\n");
+
+    return {
+      systemPrompt: event.systemPrompt ? `${event.systemPrompt}\n\n${guidance}` : guidance,
+    };
+  });
+
+  for (const tool of ToolDefinitions) {
+    pi.registerTool({
+      name: tool.name,
+      label: tool.label,
+      description: tool.description,
+      promptSnippet: tool.description,
+      promptGuidelines: [
+        `${tool.name} is available for structural code questions backed by the local CodeGraph index.`,
+      ],
+      parameters: tool.parameters,
+      async execute(_toolCallId, params: Static<typeof tool.parameters>, signal) {
+        const text = await callCodeGraphTool(tool.name, (params || {}) as ToolParams, signal);
+        return {
+          content: [{ type: "text" as const, text }],
+          details: {},
+        };
+      },
+    });
+  }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@vndv/pi-codegraph",
+  "version": "0.1.0",
+  "description": "CodeGraph tools for Pi Agent.",
+  "license": "MIT",
+  "type": "module",
+  "author": "CodeGraph contributors",
+  "homepage": "https://github.com/vndv/pi-codegraph#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vndv/pi-codegraph.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vndv/pi-codegraph/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "codegraph",
+    "coding-agent",
+    "code-intelligence"
+  ],
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./extensions/codegraph": "./extensions/codegraph.ts",
+    "./extensions/codegraph.ts": "./extensions/codegraph.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "scripts": {
+    "ci": "npm run typecheck && npm test && npm pack --dry-run",
+    "local-release": "changeset version && changeset publish",
+    "prepack": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run ci",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=22.19.0 <25"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@earendil-works/pi-coding-agent": "^0.76.0",
+    "@types/node": "^20.19.30",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.9"
+  }
+}