@liuxincuit/pi-codegraph 0.1.0

package/CONTEXT.md

@@ -0,0 +1,21 @@
+# pi-codegraph
+
+A pi extension that gives the agent access to a CodeGraph index of the current project.
+
+## Language
+
+**Project**:
+The directory the pi session runs in (`ctx.cwd`). The unit that CodeGraph indexes and the default scope of every query.
+_Avoid_: workspace, repository, repo
+
+**Index**:
+The `.codegraph/` directory at the project root, holding the SQLite knowledge graph of the project's symbols, edges, and files. Built by `codegraph init`, updated by `codegraph sync`.
+_Avoid_: database, cache, graph (ambiguous with the data structure)
+
+**Explore**:
+The single agent-facing query operation: a natural-language or symbol question answered with the relevant symbols' verbatim source plus the call paths between them.
+_Avoid_: search, query, lookup
+
+**Sync**:
+An incremental update of the Index to match the files currently on disk. Cheap when nothing changed.
+_Avoid_: refresh, rebuild (that's a full re-index)

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 izhimu
+Copyright (c) 2026 liuxincuit
+
+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,114 @@
+# pi-codegraph
+
+> 本仓库 fork 自 [izhimu/pi-codegraph](https://github.com/izhimu/pi-codegraph)，原作者版权信息见 [LICENSE](LICENSE)。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![pi extension](https://img.shields.io/badge/pi-extension-green.svg)](https://github.com/earendil-works/pi)
+
+为 [pi](https://github.com/earendil-works/pi) 提供 [CodeGraph](https://github.com/colbymchenry/codegraph) 支持：智能体将获得一个 `codegraph_explore` 工具——一次查询即可返回相关符号逐字、带行号的源码，以及它们之间的调用路径。
+
+## 环境要求
+
+`PATH` 中需要存在 `codegraph` CLI：
+
+```bash
+npm i -g @colbymchenry/codegraph
+```
+
+## 安装
+
+### npm（推荐）
+
+```bash
+pi install @liuxincuit/pi-codegraph
+```
+
+### 从 Git 安装
+
+```bash
+# 全局安装
+pi install git:github.com/liuxincuit/pi-codegraph
+
+# 项目本地安装（通过 .pi/settings.json 与团队共享）
+pi install git:github.com/liuxincuit/pi-codegraph -l
+```
+
+### 从本地路径安装
+
+```bash
+pi install /path/to/pi-codegraph
+```
+
+### 快速测试（无需安装）
+
+```bash
+pi -e ./extensions/codegraph.ts
+```
+
+## 功能一览
+
+- **`codegraph_explore` 工具** — 面向智能体的核心代码智能工具。输入符号名或自然语言问题即可查询；可选传 `path` 查询其他已建索引的项目，传 `maxFiles` 限制返回的源码行数。
+- **`/codegraph-init [path]`** — 为项目建立索引（`codegraph init`）。
+- **`/codegraph-sync [path]`** — 手动同步自上次索引以来的改动（`codegraph sync`）。
+- **`/codegraph-status [path]`** — 查看索引状态与统计信息（`codegraph status`）。
+- **`/codegraph-unlock [path]`** — 守护进程崩溃后释放过期的数据库锁（`codegraph unlock`）。
+- **会话开始时自动同步** — 每个会话自动执行一次 `codegraph sync -q`，确保索引反映你最近的编辑。
+
+## 使用方法
+
+像往常一样提出结构性问题即可——项目建立索引后，智能体会优先调用 `codegraph_explore`：
+
+- "会话加载是如何工作的？"
+- "如果我修改 `ExtensionRunner.emit`，会破坏什么？"
+
+在新项目中第一次使用 pi 时，请先手动建立一次索引：
+
+```
+/codegraph-init
+```
+
+索引构建始终由你显式触发——智能体自身不会运行 `codegraph init`（见 `docs/adr/0002`）。
+
+## 工作原理
+
+pi 原生不支持 MCP，因此本扩展通过执行 CLI 来桥接 CodeGraph——`codegraph explore` 产生与 `codegraph_explore` MCP 工具相同的输出（见 `docs/adr/0001`）。每次工具调用仅需一次 `pi.exec`：没有守护进程、没有 JSON-RPC，没有可泄漏或需要恢复的状态。
+
+`skills/codegraph/` 下的 `SKILL.md` 会被 pi 的技能系统自动发现，用于指导智能体在何种情况下优先使用该工具而非 grep/read。
+
+## 项目结构
+
+```
+pi-codegraph/
+├── extensions/
+│   └── codegraph.ts      # pi ExtensionAPI 集成
+├── skills/
+│   └── codegraph/
+│       └── SKILL.md      # codegraph_explore 的智能体使用指南
+├── docs/adr/             # 设计决策记录
+├── CONTEXT.md            # 领域术语表
+├── package.json          # pi 包清单
+├── tsconfig.json
+├── LICENSE
+└── README.md
+```
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+```
+
+## 贡献
+
+欢迎提交贡献！请：
+
+1. Fork 本仓库
+2. 新建功能分支（`git checkout -b feat/amazing-feature`）
+3. 提交改动（`git commit -m 'feat: add amazing feature'`）
+4. 推送到分支（`git push origin feat/amazing-feature`）
+5. 发起 Pull Request
+
+## License
+
+[MIT](LICENSE) © [liuxincuit](https://github.com/liuxincuit)，fork 自 [izhimu/pi-codegraph](https://github.com/izhimu/pi-codegraph)。

package/extensions/codegraph.ts

@@ -0,0 +1,281 @@
+// pi-codegraph — pi extension
+//
+// CodeGraph support for pi: codegraph_explore tool, /codegraph-init,
+// /codegraph-sync, /codegraph-status, and /codegraph-unlock commands.
+//
+// Bridges to CodeGraph by executing the CLI (see docs/adr/0001). Requires the
+// codegraph CLI on PATH: npm i -g @colbymchenry/codegraph
+// Upstream: https://github.com/colbymchenry/codegraph
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+const INSTALL_HINT =
+	"codegraph CLI not found on PATH. Install: npm i -g @colbymchenry/codegraph";
+
+// Result of `codegraph version` this session — null until first check.
+let cliAvailable: boolean | null = null;
+let notifiedMissing = false;
+
+async function execCg(
+	pi: ExtensionAPI,
+	args: string[],
+	options: { signal?: AbortSignal; timeout?: number; cwd?: string } = {},
+) {
+	if (process.platform === "win32") {
+		return await pi.exec("cmd.exe", ["/d", "/s", "/c", "codegraph", ...args], options);
+	}
+	return await pi.exec("codegraph", args, options);
+}
+
+async function ensureCli(pi: ExtensionAPI): Promise<boolean> {
+	if (cliAvailable !== null) return cliAvailable;
+	try {
+		const result = await execCg(pi, ["version"], { timeout: 10_000 });
+		cliAvailable = result.code === 0;
+	} catch {
+		cliAvailable = false;
+	}
+	return cliAvailable;
+}
+
+function textResult(text: string) {
+	return { content: [{ type: "text" as const, text }], details: undefined };
+}
+
+function outputOf(result: { stdout: string; stderr: string; code: number }): string {
+	return (result.stdout + result.stderr).trim() || `exit ${result.code}`;
+}
+
+async function isIndexed(cwd: string): Promise<boolean> {
+	try {
+		await fs.access(path.join(cwd, ".codegraph", "codegraph.db"));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+type StatusState = "index" | "sync" | "init" | boolean | undefined;
+
+function updateStatusBar(ctx: ExtensionContext, state: StatusState) {
+	if (!ctx.hasUI) return;
+	const label = state === true ? "index" : state === false ? undefined : state;
+	if (label) {
+		const text = ctx.ui.theme?.fg
+			? `${ctx.ui.theme.fg("accent", "⬡")} ${label}`
+			: `⬡ ${label}`;
+		ctx.ui.setStatus("codegraph", text);
+	} else {
+		ctx.ui.setStatus("codegraph", undefined);
+	}
+}
+
+// Modeled on upstream's MCP SERVER_INSTRUCTIONS (src/mcp/server-instructions.ts):
+// lead the agent to codegraph_explore BEFORE grep/read, plus anti-patterns and staleness handling.
+const INDEX_HINT = `# CodeGraph — this project is indexed
+
+A \`.codegraph/\` index exists here: SQLite knowledge graph of every symbol, edge, and file (30+ languages). ONE \`codegraph_explore\` call returns the relevant symbols' verbatim line-numbered source (treat it as already Read — safe to Edit from) PLUS call paths between them and a blast-radius summary of what depends on them.
+
+- For structural questions (how does X work / where is X / who calls Y / what breaks if I change Z), call \`codegraph_explore\` INSTEAD of grep + read — usually ONE call answers the whole question.
+- Call it BEFORE and WHILE writing or editing code: it puts the blast radius in view before you touch a symbol you can name.
+- Flow tracing: name endpoint symbols (e.g. \`mutateElement renderScene\`) to surface the path across dynamic-dispatch hops.
+- Anti-patterns: don't grep or Read first; don't re-verify codegraph output with grep (AST-derived, more accurate than grep); don't reconstruct a flow by hand.
+- "Already sent earlier in this conversation": pointer means content is already in context — do not re-fetch or Read.
+- Staleness: if tool output contains "⚠️ Some files referenced below were edited since the last index sync", read only those flagged files directly.
+- Multi-project / Monorepo: pass \`path\` to query any indexed sub-project directory.
+- If a project has no \`.codegraph/\`, use built-in tools there; indexing is the user's decision — suggest /codegraph-init if it comes up.`;
+
+export default function codegraphExtension(pi: ExtensionAPI) {
+	// ── codegraph_explore tool ─────────────────────────────────────────────
+	pi.registerTool({
+		name: "codegraph_explore",
+		label: "CodeGraph Explore",
+		description:
+			"PRIMARY tool for code questions — call it BEFORE grep/read when the project has a .codegraph/ index. " +
+			"One query returns the relevant symbols' verbatim line-numbered source plus the call paths between them and a blast-radius summary. " +
+			"If the project is not indexed the output says so: continue with built-in tools and suggest the user run /codegraph-init.",
+		promptSnippet:
+			"codegraph_explore: symbol source + call paths in one shot from the project's CodeGraph index",
+		promptGuidelines: [
+			"For structural code questions (how does X work, where is X, what breaks if I change X), prefer codegraph_explore over grep when the project has a .codegraph/ index.",
+			"Indexing is the user's decision — never run codegraph init yourself; suggest /codegraph-init instead.",
+		],
+		parameters: Type.Object({
+			query: Type.String({
+				description: "Symbol names or a natural-language question about the code",
+			}),
+			path: Type.Optional(
+				Type.String({
+					description: "Project path to query; defaults to the current working directory",
+				}),
+			),
+			maxFiles: Type.Optional(
+				Type.Integer({
+					description: "Maximum number of files to include source from",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
+			if (!(await ensureCli(pi))) return textResult(INSTALL_HINT);
+			const cwd = params.path ?? ctx.cwd;
+			const args = ["explore", params.query, "-p", cwd];
+			if (typeof params.maxFiles === "number" && params.maxFiles > 0) {
+				args.push("--max-files", String(params.maxFiles));
+			}
+			const result = await execCg(pi, args, {
+				signal,
+				timeout: 120_000,
+			});
+			if (result.killed) return textResult("codegraph explore timed out (120s)");
+			// Non-zero exits carry upstream's agent-friendly guidance (e.g. the
+			// "not initialized" message) — pass it through verbatim.
+			if (result.code !== 0) return textResult(outputOf(result));
+			return textResult(result.stdout.trim());
+		},
+	});
+
+	// ── /codegraph-init ────────────────────────────────────────────────────
+	pi.registerCommand("codegraph-init", {
+		description: "Build the CodeGraph index for the current project (codegraph init)",
+		handler: async (args, ctx) => {
+			if (!(await ensureCli(pi))) {
+				if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "error");
+				return;
+			}
+			const target = args?.trim() || ctx.cwd;
+			if (ctx.hasUI) {
+				ctx.ui.notify(`Indexing ${target} — can take minutes on a large repo…`, "info");
+			}
+			updateStatusBar(ctx, "init");
+			try {
+				const result = await execCg(pi, ["init", target], { timeout: 1_800_000 });
+				const out = outputOf(result);
+				const success = result.code === 0;
+				if (ctx.hasUI) {
+					ctx.ui.notify(
+						success ? "CodeGraph index built." : `codegraph init failed (exit ${result.code})`,
+						success ? "info" : "error",
+					);
+				}
+				pi.sendMessage(
+					{ customType: "codegraph-init", content: out, display: true },
+					{ triggerTurn: false },
+				);
+			} finally {
+				updateStatusBar(ctx, await isIndexed(ctx.cwd));
+			}
+		},
+	});
+
+	// ── /codegraph-sync ────────────────────────────────────────────────────
+	pi.registerCommand("codegraph-sync", {
+		description: "Sync CodeGraph changes since last index (codegraph sync)",
+		handler: async (args, ctx) => {
+			if (!(await ensureCli(pi))) {
+				if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "error");
+				return;
+			}
+			const target = args?.trim() || ctx.cwd;
+			if (ctx.hasUI) {
+				ctx.ui.notify(`Syncing CodeGraph for ${target}…`, "info");
+			}
+			updateStatusBar(ctx, "sync");
+			try {
+				const result = await execCg(pi, ["sync", target], { timeout: 300_000 });
+				const out = outputOf(result);
+				if (ctx.hasUI) {
+					ctx.ui.notify(out, result.code === 0 ? "info" : "warning");
+				}
+				pi.sendMessage(
+					{ customType: "codegraph-sync", content: out, display: true },
+					{ triggerTurn: false },
+				);
+			} finally {
+				updateStatusBar(ctx, await isIndexed(ctx.cwd));
+			}
+		},
+	});
+
+	// ── /codegraph-status ──────────────────────────────────────────────────
+	pi.registerCommand("codegraph-status", {
+		description: "Show CodeGraph index status and statistics",
+		handler: async (args, ctx) => {
+			if (!(await ensureCli(pi))) {
+				if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "error");
+				return;
+			}
+			const target = args?.trim() || ctx.cwd;
+			const result = await execCg(pi, ["status", target], { timeout: 30_000 });
+			const out = outputOf(result);
+			if (ctx.hasUI) ctx.ui.notify(out, result.code === 0 ? "info" : "warning");
+			updateStatusBar(ctx, await isIndexed(ctx.cwd));
+			pi.sendMessage(
+				{ customType: "codegraph-status", content: out, display: true },
+				{ triggerTurn: false },
+			);
+		},
+	});
+
+	// ── /codegraph-unlock ──────────────────────────────────────────────────
+	pi.registerCommand("codegraph-unlock", {
+		description: "Release stale CodeGraph database lock (codegraph unlock)",
+		handler: async (args, ctx) => {
+			if (!(await ensureCli(pi))) {
+				if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "error");
+				return;
+			}
+			const target = args?.trim() || ctx.cwd;
+			const result = await execCg(pi, ["unlock", target], { timeout: 10_000 });
+			const out = outputOf(result);
+			if (ctx.hasUI) ctx.ui.notify(out, result.code === 0 ? "info" : "warning");
+			pi.sendMessage(
+				{ customType: "codegraph-unlock", content: out, display: true },
+				{ triggerTurn: false },
+			);
+		},
+	});
+
+	// ── session_start: CLI check + incremental sync + context hint ────────
+	pi.on("session_start", async (event, ctx) => {
+		if (!(await ensureCli(pi))) {
+			updateStatusBar(ctx, false);
+			if (ctx.hasUI && !notifiedMissing) {
+				notifiedMissing = true;
+				ctx.ui.notify(INSTALL_HINT, "warning");
+			}
+			return;
+		}
+
+		const indexed = await isIndexed(ctx.cwd);
+		if (indexed) {
+			updateStatusBar(ctx, "sync");
+			// Incremental sync; near-zero cost when nothing changed.
+			void execCg(pi, ["sync", "-q", ctx.cwd], { timeout: 300_000 })
+				.catch(() => {})
+				.finally(async () => {
+					updateStatusBar(ctx, await isIndexed(ctx.cwd));
+				});
+		} else {
+			updateStatusBar(ctx, false);
+		}
+
+		// Inject the agent playbook once per process when the project IS
+		// indexed (upstream does this via MCP initialize instructions). Skip
+		// "reload": extensions rebind in place and the message would duplicate.
+		if (event.reason !== "reload" && indexed) {
+			pi.sendMessage(
+				{ customType: "codegraph-context", content: INDEX_HINT, display: false },
+				{ triggerTurn: false },
+			);
+		}
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		if (ctx.hasUI) {
+			ctx.ui.setStatus("codegraph", undefined);
+		}
+	});
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@liuxincuit/pi-codegraph",
+	"version": "0.1.0",
+	"description": "CodeGraph support for pi — symbol source + call paths via the codegraph CLI",
+	"type": "module",
+	"keywords": [
+		"pi-package",
+		"codegraph",
+		"code-intelligence",
+		"knowledge-graph"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/liuxincuit/pi-codegraph.git"
+	},
+	"author": "liuxincuit",
+	"license": "MIT",
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@types/node": "^22.0.0",
+		"typebox": "^1.3.7",
+		"typescript": "^5.5.0"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"smoke": "tsc extensions/codegraph.ts --outDir .smoke-build --module esnext --target es2022 --moduleResolution bundler --skipLibCheck --noEmit false && node smoke.mjs"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions"
+		],
+		"skills": [
+			"./skills"
+		]
+	},
+	"files": [
+		"extensions/",
+		"skills/",
+		"CONTEXT.md",
+		"README.md",
+		"LICENSE"
+	]
+}

package/skills/codegraph/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: codegraph
+description: Query the project's CodeGraph index (symbol source + call paths) via the codegraph_explore tool. Use when answering structural code questions — how X works, where X is, what a change affects — in a project that has a .codegraph/ index.
+---
+
+# CodeGraph
+
+The `codegraph_explore` tool answers structural code questions in one shot: the relevant symbols' verbatim line-numbered source, the call paths between them, and a blast-radius summary. It reads the project's CodeGraph index (`.codegraph/`), built and maintained by the `codegraph` CLI.
+
+## When to use
+
+- "How does X work?" / "Where is X?" / "What calls Y?" / "What breaks if I change Z?"
+- Before an edit, to map the symbols you are about to touch and inspect the blast radius.
+- Prefer it over grep/read for structural exploration **when the project has a `.codegraph/` index**.
+
+## How to query
+
+- `query`: symbol names (`CodeGraph open`, `MCPSession`), endpoint flows (`mutateElement renderScene`), or a natural-language question. Naming a file or symbol returns its current line-numbered source.
+- `path`: optional project path. Defaults to the current working directory. In a monorepo, pass the sub-project directory that contains `.codegraph/`.
+- `maxFiles`: optional integer to limit how many file sources are returned.
+
+## Anti-patterns & Guidance
+
+- **Trust AST results.** Don't re-verify codegraph output with grep.
+- **Already sent earlier in this conversation.** When this pointer appears, the lines are already in your session context — scroll back instead of re-fetching or reading the file.
+- **Staleness banner.** If output warns `⚠️ Some files referenced below were edited since the last index sync`, read only those specific files directly; other files in the response remain fresh.
+- **No index, no tool.** If the output says the project isn't indexed, stop calling `codegraph_explore` for that project this session and use built-in tools. Indexing is the user's decision — suggest the user run `/codegraph-init` if appropriate.