@wwjd/pi-graphify 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0](https://github.com/WianVDM/pi-graphify/compare/pi-graphify-v0.1.0...pi-graphify-v0.2.0) (2026-07-12)
+
+
+### Features
+
+* add graphify_status tool and /graphify-status command ([99f809c](https://github.com/WianVDM/pi-graphify/commit/99f809caace328e5af97a5dcdac50af025437776))
+* implement phase 2 backend abstraction ([40afa65](https://github.com/WianVDM/pi-graphify/commit/40afa65bbadf9bcb72676a613d94f6bdb677cc5d))
+
+
+### Bug Fixes
+
+* correct status tool description and missing-Graphify warning ([c4225c1](https://github.com/WianVDM/pi-graphify/commit/c4225c1591124a65ca0df33565168970a6720a9d))
+* normalize package author email casing ([fcfa352](https://github.com/WianVDM/pi-graphify/commit/fcfa3520463ed860be1264daa6443c608a197444))
+
 ## [Unreleased]
 
 ## 0.1.0 (2026-07-11)

package/extensions/index.ts

@@ -9,23 +9,61 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadConfig } from "../src/config.js";
+import { GraphifyCoordinator } from "../src/coordinator.js";
 import { buildGraphifyHint, graphifyStatus } from "../src/graphify.js";
 import { registerGraphifyTools } from "../src/tools/index.js";
 
 export default function (pi: ExtensionAPI) {
-  const config = loadConfig();
+  // Coordinator is created per session and shared by tools and commands.
+  let coordinator: GraphifyCoordinator | null = null;
+  const getCoordinator = () => coordinator;
 
-  // ── 1. Notify and inject context when a graph is present ──────────
+  // ── 1. Register tools and commands synchronously ──────────────────
+  registerGraphifyTools(pi, getCoordinator);
+
+  pi.registerCommand("graphify-status", {
+    description: "Show Graphify graph status for the current project",
+    handler: async (_args, ctx) => {
+      const current = getCoordinator();
+      if (!current) {
+        ctx.ui.notify("Graphify is not initialized.", "warning");
+        return;
+      }
+
+      const status = await current.status({ cwd: ctx.cwd });
+      if (status.hasGraph && status.graphPath) {
+        ctx.ui.notify(`Graphify graph ready: ${status.graphPath}`, "info");
+      } else {
+        ctx.ui.notify("No Graphify graph found. Run /graphify-build to create one.", "warning");
+      }
+    },
+  });
+
+  // ── 2. Initialize coordinator per session ─────────────────────────
   pi.on("session_start", async (_event, ctx) => {
-    const status = await graphifyStatus(ctx.cwd);
+    coordinator = new GraphifyCoordinator({ cwd: ctx.cwd });
+    await coordinator.initialize();
+
+    const status = await coordinator.status({ cwd: ctx.cwd });
     if (status.hasGraph && status.graphPath) {
       ctx.ui.notify(`Graphify graph ready: ${status.graphPath}`, "info");
     }
+
+    if (coordinator.version === null) {
+      ctx.ui.notify(
+        "Graphify CLI was not detected on PATH. Install Graphify to use build, query, and other graph tools.",
+        "warning",
+      );
+    }
+
+    for (const warning of coordinator.warnings) {
+      ctx.ui.notify(warning, "warning");
+    }
   });
 
+  // ── 3. Inject context hint when a graph is present ────────────────
   pi.on("before_agent_start", async (event, ctx) => {
-    const status = await graphifyStatus(ctx.cwd);
+    const status = graphifyStatus(ctx.cwd);
     if (!status.hasGraph || !status.graphPath) {
       return;
     }
@@ -36,19 +74,11 @@ export default function (pi: ExtensionAPI) {
     };
   });
 
-  // ── 2. Register custom tools the LLM can call ─────────────────────
-  registerGraphifyTools(pi, config);
-
-  // ── 3. Register slash commands ────────────────────────────────────
-  pi.registerCommand("graphify-status", {
-    description: "Show Graphify graph status for the current project",
-    handler: async (_args, ctx) => {
-      const status = await graphifyStatus(ctx.cwd);
-      if (status.hasGraph && status.graphPath) {
-        ctx.ui.notify(`Graphify graph ready: ${status.graphPath}`, "info");
-      } else {
-        ctx.ui.notify("No Graphify graph found. Run /graphify-build to create one.", "warning");
-      }
-    },
+  // ── 4. Clean up coordinator on shutdown ─────────────────────────
+  pi.on("session_shutdown", async () => {
+    if (coordinator) {
+      await coordinator.close();
+      coordinator = null;
+    }
   });
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@wwjd/pi-graphify",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Graphify knowledge graph integration for Pi coding agent",
   "type": "module",
   "license": "MIT",
-  "author": "WIAN <WIANVDM4@GMAIL.COM>",
+  "author": "Wian <wianvdm4@gmail.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/WianVDM/pi-graphify.git"

package/src/backends/cli.ts

@@ -0,0 +1,201 @@
+/**
+ * CLI backend for Graphify.
+ *
+ * Resolves the `graphify` executable, runs commands via `execFile`, and
+ * normalizes the results into the backend-agnostic `GraphifyResult` shape.
+ */
+
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { buildCapabilities, detectVersion } from "../version.js";
+import type { GraphifyBackend, GraphifyCapabilities, GraphifyResult } from "./types.js";
+import { allCapabilitiesDisabled } from "./types.js";
+
+const DEFAULT_TIMEOUT = 30_000;
+
+export interface CliBackendOptions {
+  cwd: string;
+  timeoutMs?: number;
+  /** Explicit executable path from config or env. */
+  explicitPath?: string;
+}
+
+export class CliBackend implements GraphifyBackend {
+  readonly type = "cli" as const;
+  private readonly cwd: string;
+  private readonly timeoutMs: number;
+  private readonly explicitPath: string | undefined;
+  private _cli: string | null = null;
+  private _version: string | null = null;
+  private _capabilities: GraphifyCapabilities | null = null;
+
+  constructor(options: CliBackendOptions) {
+    this.cwd = options.cwd;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT;
+    this.explicitPath = options.explicitPath;
+  }
+
+  get version(): string | null {
+    return this._version;
+  }
+
+  get capabilities(): GraphifyCapabilities {
+    return this._capabilities ?? allCapabilitiesDisabled();
+  }
+
+  async initialize(): Promise<void> {
+    this._cli = await this.resolveCli();
+    const versionInfo = await detectVersion(this._cli, this.cwd);
+    this._version = versionInfo.version;
+
+    this._capabilities = await buildCapabilities(this._cli, this.cwd, versionInfo, async (args) =>
+      this.runHelp(args),
+    );
+  }
+
+  async run(operation: string, options: unknown): Promise<GraphifyResult> {
+    const cli = await this.resolveCli();
+    const args = buildArgs(operation, options);
+    const start = performance.now();
+
+    return new Promise((resolve) => {
+      execFile(cli, args, { cwd: this.cwd, timeout: this.timeoutMs }, (error, stdout, stderr) => {
+        const durationMs = Math.round(performance.now() - start);
+        if (error) {
+          resolve({
+            stdout: stdout.trim(),
+            stderr: stderr.trim() || error.message,
+            exitCode: typeof error.code === "number" ? error.code : 1,
+            durationMs,
+            backend: "cli",
+            feature: operation,
+          });
+          return;
+        }
+        resolve({
+          stdout: stdout.trim(),
+          stderr: stderr.trim(),
+          exitCode: 0,
+          durationMs,
+          backend: "cli",
+          feature: operation,
+        });
+      });
+    });
+  }
+
+  async close(): Promise<void> {
+    // CLI backend has no persistent process to clean up.
+    this._cli = null;
+  }
+
+  private async resolveCli(): Promise<string> {
+    if (this._cli) return this._cli;
+    if (this.explicitPath) return this.explicitPath;
+
+    // Try the PATH first.
+    const fromPath = await findOnPath("graphify");
+    if (fromPath) return fromPath;
+
+    // Common install locations.
+    const candidates = [
+      join(homedir(), ".local", "bin", "graphify"),
+      join(homedir(), ".cargo", "bin", "graphify"),
+      join(homedir(), ".pipx", "venvs", "graphify", "bin", "graphify"),
+    ];
+
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) return candidate;
+    }
+
+    // Fall back to the bare command and let execFile report the error.
+    return "graphify";
+  }
+
+  private async runHelp(args: string[]): Promise<{ stdout: string; exitCode: number }> {
+    const cli = await this.resolveCli();
+    return new Promise((resolve) => {
+      execFile(cli, args, { cwd: this.cwd, timeout: 10_000 }, (error, stdout, _stderr) => {
+        if (error) {
+          resolve({
+            stdout: stdout.trim(),
+            exitCode: typeof error.code === "number" ? error.code : 1,
+          });
+          return;
+        }
+        resolve({ stdout: stdout.trim(), exitCode: 0 });
+      });
+    });
+  }
+}
+
+/** Best-effort find an executable on the user PATH. */
+function findOnPath(command: string): Promise<string | null> {
+  const checkCmd = process.platform === "win32" ? "where" : "which";
+  const shell = process.platform === "win32" ? "cmd.exe" : undefined;
+
+  return new Promise((resolve) => {
+    execFile(checkCmd, [command], { shell }, (error, stdout) => {
+      if (error || !stdout.trim()) {
+        resolve(null);
+        return;
+      }
+      resolve(stdout.split("\n")[0].trim());
+    });
+  });
+}
+
+/** Build a CLI argument array from an operation and options. */
+function buildArgs(operation: string, options: unknown): string[] {
+  if (!options || typeof options !== "object") {
+    return [operation];
+  }
+
+  const opts = options as Record<string, unknown>;
+  const args = [operation];
+
+  if (opts.cwd && typeof opts.cwd === "string") {
+    // graphify commands operate on cwd via the spawned process working directory;
+    // no explicit flag is needed for most operations.
+  }
+
+  if (opts.codeOnly === true) args.push("--code-only");
+  if (opts.update === true) args.push("--update");
+  if (opts.directed === true) args.push("--directed");
+
+  if (opts.question && typeof opts.question === "string") {
+    args.push(opts.question);
+  }
+  if (opts.source && typeof opts.source === "string") {
+    args.push("--source", opts.source);
+  }
+  if (opts.target && typeof opts.target === "string") {
+    args.push("--target", opts.target);
+  }
+  if (opts.node && typeof opts.node === "string") {
+    args.push("--node", opts.node);
+  }
+  if (Array.isArray(opts.files)) {
+    for (const file of opts.files) {
+      if (typeof file === "string") args.push(file);
+    }
+  }
+  if (Array.isArray(opts.paths)) {
+    for (const p of opts.paths) {
+      if (typeof p === "string") {
+        args.push(resolve(p));
+      }
+    }
+  }
+
+  return args;
+}
+
+/** Create a CLI backend and initialize it. */
+export async function createCliBackend(options: CliBackendOptions): Promise<CliBackend> {
+  const backend = new CliBackend(options);
+  await backend.initialize();
+  return backend;
+}

package/src/backends/types.ts

@@ -0,0 +1,158 @@
+/**
+ * Backend abstraction types for pi-graphify.
+ *
+ * All Graphify operations go through the `GraphifyBackend` interface so the
+ * rest of the extension is agnostic to whether the CLI or MCP is used.
+ */
+
+export interface GraphifyCapabilities {
+  /** Core graph build. */
+  build: boolean;
+  /** Query the graph. */
+  query: boolean;
+  /** Shortest path between nodes. */
+  path: boolean;
+  /** Explain a node or relationship. */
+  explain: boolean;
+  /** Affected nodes/files. */
+  affected: boolean;
+  /** Add content to the graph. */
+  add: boolean;
+  /** Watch source files for changes. */
+  watch: boolean;
+  /** Reflect on graph structure. */
+  reflect: boolean;
+  /** MCP server support. */
+  mcp: boolean;
+  /** Graph status check. */
+  status: boolean;
+  /** Version reporting. */
+  version: boolean;
+  /** Directed graph support. */
+  directedGraph: boolean;
+  /** Incremental code-only updates. */
+  incrementalUpdate: boolean;
+  /** Semantic extraction beyond code. */
+  semanticExtraction: boolean;
+}
+
+/** Normalized result from any Graphify backend. */
+export interface GraphifyResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  durationMs: number;
+  backend: "cli" | "mcp";
+  feature: string;
+}
+
+/** Backend-agnostic interface for all Graphify operations. */
+export interface GraphifyBackend {
+  readonly type: "cli" | "mcp";
+  readonly version: string | null;
+  readonly capabilities: GraphifyCapabilities;
+
+  /**
+   * Run a Graphify operation.
+   *
+   * @param operation - The operation name, e.g. `"build"`, `"query"`, `"status"`.
+   * @param options - Operation-specific options.
+   */
+  run(operation: string, options: unknown): Promise<GraphifyResult>;
+
+  /** Optional cleanup hook called on session shutdown. */
+  close?(): Promise<void>;
+}
+
+/** Options for the `status` operation. */
+export interface StatusOptions {
+  cwd: string;
+}
+
+/** Options for the `version` operation. */
+export interface VersionOptions {
+  cwd?: string;
+}
+
+/** Options for the `build` operation. */
+export interface BuildOptions {
+  cwd: string;
+  codeOnly?: boolean;
+  update?: boolean;
+  directed?: boolean;
+}
+
+/** Options for the `query` operation. */
+export interface QueryOptions {
+  cwd: string;
+  question: string;
+}
+
+/** Options for the `path` operation. */
+export interface PathOptions {
+  cwd: string;
+  source: string;
+  target: string;
+}
+
+/** Options for the `explain` operation. */
+export interface ExplainOptions {
+  cwd: string;
+  node: string;
+}
+
+/** Options for the `affected` operation. */
+export interface AffectedOptions {
+  cwd: string;
+  files: string[];
+}
+
+/** Options for the `add` operation. */
+export interface AddOptions {
+  cwd: string;
+  paths: string[];
+}
+
+/** Options for the `watch` operation. */
+export interface WatchOptions {
+  cwd: string;
+  codeOnly?: boolean;
+}
+
+/** Options for the `reflect` operation. */
+export interface ReflectOptions {
+  cwd: string;
+  question?: string;
+}
+
+/** All operation option types unioned together. */
+export type GraphifyOperationOptions =
+  | StatusOptions
+  | VersionOptions
+  | BuildOptions
+  | QueryOptions
+  | PathOptions
+  | ExplainOptions
+  | AffectedOptions
+  | AddOptions
+  | WatchOptions
+  | ReflectOptions;
+
+export function allCapabilitiesDisabled(): GraphifyCapabilities {
+  return {
+    build: false,
+    query: false,
+    path: false,
+    explain: false,
+    affected: false,
+    add: false,
+    watch: false,
+    reflect: false,
+    mcp: false,
+    status: false,
+    version: false,
+    directedGraph: false,
+    incrementalUpdate: false,
+    semanticExtraction: false,
+  };
+}

package/src/coordinator.ts

@@ -0,0 +1,187 @@
+/**
+ * GraphifyCoordinator — the single entry point for all Graphify operations.
+ *
+ * The coordinator loads configuration, selects a backend, detects the installed
+ * Graphify version, builds a capability matrix, and routes tool/command
+ * requests to the backend. It also normalizes backend results and errors.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createCliBackend } from "./backends/cli.js";
+import {
+  type AddOptions,
+  type AffectedOptions,
+  allCapabilitiesDisabled,
+  type BuildOptions,
+  type ExplainOptions,
+  type GraphifyBackend,
+  type GraphifyCapabilities,
+  type GraphifyResult,
+  type PathOptions,
+  type QueryOptions,
+  type ReflectOptions,
+  type StatusOptions,
+  type VersionOptions,
+  type WatchOptions,
+} from "./backends/types.js";
+import { type GraphifyConfig, loadConfig } from "./config.js";
+import { codeForOperation, GraphifyError, messageForCliFailure } from "./errors.js";
+
+export interface GraphifyStatusResult {
+  hasGraph: boolean;
+  graphPath?: string;
+  backendVersion: string | null;
+}
+
+export interface CoordinatorOptions {
+  cwd: string;
+  config?: GraphifyConfig;
+}
+
+export class GraphifyCoordinator {
+  readonly config: GraphifyConfig;
+  readonly cwd: string;
+  private backend: GraphifyBackend | null = null;
+  private readonly _warnings: string[] = [];
+  private closed = false;
+
+  constructor(options: CoordinatorOptions) {
+    this.cwd = options.cwd;
+    this.config = options.config ?? loadConfig();
+  }
+
+  async initialize(): Promise<void> {
+    if (this.closed) {
+      throw new GraphifyError("UNKNOWN", "Coordinator has already been closed");
+    }
+
+    try {
+      // Phase 2 only supports CLI backend. MCP is a Phase 6 addition.
+      this.backend = await createCliBackend({
+        cwd: this.cwd,
+        timeoutMs: this.config.queryTimeoutMs,
+      });
+    } catch (error) {
+      this.backend = null;
+      this._warnings.push(
+        error instanceof Error ? error.message : "Graphify backend failed to initialize",
+      );
+    }
+  }
+
+  get version(): string | null {
+    return this.backend?.version ?? null;
+  }
+
+  get capabilities(): GraphifyCapabilities {
+    return this.backend?.capabilities ?? allCapabilitiesDisabled();
+  }
+
+  get warnings(): readonly string[] {
+    return this._warnings;
+  }
+
+  supports(feature: keyof GraphifyCapabilities): boolean {
+    return this.capabilities[feature] ?? false;
+  }
+
+  async status(_options: StatusOptions): Promise<GraphifyStatusResult> {
+    const graphPath = join(this.cwd, "graphify-out", "graph.json");
+    return {
+      hasGraph: existsSync(graphPath),
+      graphPath,
+      backendVersion: this.version,
+    };
+  }
+
+  async getVersion(_options?: VersionOptions): Promise<GraphifyResult> {
+    if (!this.backend) {
+      throw new GraphifyError("MISSING", "Graphify is not installed or not available on PATH.");
+    }
+    return {
+      stdout: this.version ?? "unknown",
+      stderr: "",
+      exitCode: 0,
+      durationMs: 0,
+      backend: "cli",
+      feature: "version",
+    };
+  }
+
+  async build(options: BuildOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("build", options);
+  }
+
+  async query(options: QueryOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("query", options);
+  }
+
+  async path(options: PathOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("path", options);
+  }
+
+  async explain(options: ExplainOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("explain", options);
+  }
+
+  async affected(options: AffectedOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("affected", options);
+  }
+
+  async add(options: AddOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("add", options);
+  }
+
+  async watch(options: WatchOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("watch", options);
+  }
+
+  async reflect(options: ReflectOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("reflect", options);
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    if (this.backend?.close) {
+      await this.backend.close();
+    }
+    this.backend = null;
+  }
+
+  private async runWithFeature(
+    operation: keyof GraphifyCapabilities,
+    options: unknown,
+  ): Promise<GraphifyResult> {
+    if (!this.backend) {
+      throw new GraphifyError("MISSING", `Graphify is not available. Cannot run ${operation}.`);
+    }
+
+    if (!this.supports(operation)) {
+      throw new GraphifyError(
+        "VERSION",
+        `The installed Graphify version does not support "${operation}".`,
+      );
+    }
+
+    const result = await this.backend.run(operation, options);
+    if (result.exitCode !== 0) {
+      throw new GraphifyError(
+        codeForOperation(operation),
+        messageForCliFailure(operation, result.exitCode, result.stderr),
+        { exitCode: result.exitCode, stderr: result.stderr },
+      );
+    }
+    return result;
+  }
+}
+
+/** Convenience factory. */
+export async function createGraphifyCoordinator(
+  cwd: string,
+  config?: GraphifyConfig,
+): Promise<GraphifyCoordinator> {
+  const coordinator = new GraphifyCoordinator({ cwd, config });
+  await coordinator.initialize();
+  return coordinator;
+}

package/src/errors.ts

@@ -0,0 +1,67 @@
+/**
+ * Normalized error handling for pi-graphify.
+ */
+
+export type GraphifyErrorCode =
+  | "MISSING"
+  | "VERSION"
+  | "BUILD"
+  | "QUERY"
+  | "PATH"
+  | "EXPLAIN"
+  | "AFFECTED"
+  | "ADD"
+  | "WATCH"
+  | "REFLECT"
+  | "TIMEOUT"
+  | "MCP"
+  | "UNKNOWN";
+
+export class GraphifyError extends Error {
+  readonly code: GraphifyErrorCode;
+  readonly details: Record<string, unknown>;
+  readonly userMessage: string;
+
+  constructor(code: GraphifyErrorCode, userMessage: string, details: Record<string, unknown> = {}) {
+    super(userMessage);
+    this.code = code;
+    this.userMessage = userMessage;
+    this.details = details;
+    this.name = "GraphifyError";
+  }
+}
+
+/** Map a Graphify operation name to an error code. */
+export function codeForOperation(operation: string): GraphifyErrorCode {
+  switch (operation) {
+    case "build":
+      return "BUILD";
+    case "query":
+      return "QUERY";
+    case "path":
+      return "PATH";
+    case "explain":
+      return "EXPLAIN";
+    case "affected":
+      return "AFFECTED";
+    case "add":
+      return "ADD";
+    case "watch":
+      return "WATCH";
+    case "reflect":
+      return "REFLECT";
+    case "mcp":
+      return "MCP";
+    default:
+      return "UNKNOWN";
+  }
+}
+
+/** Build a user-friendly message from a backend result. */
+export function messageForCliFailure(operation: string, exitCode: number, stderr: string): string {
+  const trimmed = stderr.trim();
+  if (trimmed) {
+    return `graphify ${operation} failed (exit ${exitCode}): ${trimmed}`;
+  }
+  return `graphify ${operation} failed with exit code ${exitCode}`;
+}

package/src/graphify.ts

@@ -1,72 +1,23 @@
 /**
- * Graphify CLI helpers
+ * High-level Graphify helpers used by the extension and tools.
+ *
+ * CLI execution has moved to `src/backends/cli.ts`. This module retains:
+ *   - graph existence checks
+ *   - system-prompt hint construction
+ *   - result formatting utilities
  */
 
-import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import type { GraphifyConfig } from "./config.js";
-
-export interface GraphifyResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}
+import type { GraphifyResult } from "./backends/types.js";
 
 export interface GraphStatus {
   hasGraph: boolean;
   graphPath?: string;
-  error?: string;
-}
-
-/** Best-effort resolve of the graphify CLI executable name. */
-export async function findGraphifyCli(): Promise<string> {
-  // Pi shells run with the user's PATH, so the bare command is usually enough.
-  // We try a platform-aware check first; if it fails, we fall back to "graphify".
-  const checkCmd = process.platform === "win32" ? "where" : "which";
-  const shell = process.platform === "win32" ? "cmd.exe" : undefined;
-
-  return new Promise((resolve) => {
-    execFile(checkCmd, ["graphify"], { shell }, (error, stdout) => {
-      if (error || !stdout.trim()) {
-        resolve("graphify");
-        return;
-      }
-      // Use the first match returned by where/which.
-      resolve(stdout.split("\n")[0].trim());
-    });
-  });
-}
-
-/** Run a graphify CLI command with a timeout. */
-export async function runGraphify(
-  args: string[],
-  cwd: string,
-  timeoutMs: number,
-): Promise<GraphifyResult> {
-  const cli = await findGraphifyCli();
-
-  return new Promise((resolve) => {
-    execFile(cli, args, { cwd, timeout: timeoutMs }, (error, stdout, stderr) => {
-      if (error) {
-        resolve({
-          stdout: stdout.trim(),
-          stderr: stderr.trim() || error.message,
-          exitCode: typeof error.code === "number" ? error.code : 1,
-        });
-        return;
-      }
-      resolve({
-        stdout: stdout.trim(),
-        stderr: stderr.trim(),
-        exitCode: 0,
-      });
-    });
-  });
 }
 
 /** Check whether a graph exists for the given project directory. */
-export async function graphifyStatus(cwd: string): Promise<GraphStatus> {
+export function graphifyStatus(cwd: string): GraphStatus {
   const graphPath = join(cwd, "graphify-out", "graph.json");
 
   if (!existsSync(graphPath)) {
@@ -94,5 +45,3 @@ export function formatResult(result: GraphifyResult): string {
   }
   return `graphify exited with code ${result.exitCode}\n${result.stderr || result.stdout}`.trim();
 }
-
-export type { GraphifyConfig };

package/src/tools/index.ts

@@ -3,9 +3,10 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { GraphifyConfig } from "../config.js";
 import { registerStatusTool } from "./status.js";
 
-export function registerGraphifyTools(pi: ExtensionAPI, config: GraphifyConfig): void {
-  registerStatusTool(pi, config);
+export type CoordinatorProvider = () => import("../coordinator.js").GraphifyCoordinator | null;
+
+export function registerGraphifyTools(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  registerStatusTool(pi, getCoordinator);
 }

package/src/tools/status.ts

@@ -4,39 +4,62 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import type { GraphifyConfig } from "../config.js";
-import { graphifyStatus } from "../graphify.js";
+import type { CoordinatorProvider } from "./index.js";
 
-export function registerStatusTool(pi: ExtensionAPI, _config: GraphifyConfig): void {
+export function registerStatusTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
   pi.registerTool({
     name: "graphify_status",
     label: "Graphify Status",
-    description:
-      "Check whether a Graphify knowledge graph exists for the current project and whether the graphify CLI is available.",
+    description: "Check whether a Graphify knowledge graph exists for the current project.",
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
-      const status = await graphifyStatus(ctx.cwd);
+      const coordinator = getCoordinator();
+      if (!coordinator) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Graphify is not initialized yet.",
+            },
+          ],
+          details: {},
+        };
+      }
+
+      const status = await coordinator.status({ cwd: ctx.cwd });
+      const details: Record<string, unknown> = {
+        hasGraph: status.hasGraph,
+        backendVersion: status.backendVersion,
+      };
 
       if (!status.hasGraph) {
+        const cliNote = status.backendVersion ? "" : " The Graphify CLI was not detected on PATH.";
         return {
           content: [
             {
               type: "text",
-              text: "No Graphify graph found. Run /graphify-build to build one.",
+              text: `No Graphify graph found. Run /graphify-build to build one.${cliNote}`,
             },
           ],
-          details: {},
+          details,
         };
       }
 
+      const graphText = status.backendVersion
+        ? `Graphify graph is available at ${status.graphPath}.`
+        : `Graphify graph is available at ${status.graphPath}, but the Graphify CLI was not detected on PATH.`;
+
       return {
         content: [
           {
             type: "text",
-            text: `Graphify graph is available at ${status.graphPath}.`,
+            text: graphText,
           },
         ],
-        details: {},
+        details: {
+          ...details,
+          graphPath: status.graphPath,
+        },
       };
     },
   });

package/src/version.ts

@@ -0,0 +1,172 @@
+/**
+ * Graphify CLI version detection and capability matrix.
+ */
+
+import { execFile } from "node:child_process";
+import type { GraphifyCapabilities } from "./backends/types.js";
+
+/** Minimum Graphify CLI version considered supported. */
+export const MIN_SUPPORTED_GRAPHIFY = "2.100.0";
+
+export interface GraphifyVersionInfo {
+  /** Detected version, or null if unknown. */
+  version: string | null;
+  /** Whether the detected version is at or above the minimum. */
+  isSupported: boolean;
+  /** Human-readable warnings about version/capability issues. */
+  warnings: string[];
+}
+
+/** Run a command to detect the Graphify version. */
+export async function detectVersion(cli: string, cwd: string): Promise<GraphifyVersionInfo> {
+  const warnings: string[] = [];
+
+  let version: string | null = null;
+  for (const args of [["--version"], ["version"]]) {
+    const result = await runProbe(cli, args, cwd, 10_000);
+    if (result.exitCode === 0) {
+      version = parseVersion(result.stdout);
+      if (version) break;
+    }
+  }
+
+  if (!version) {
+    warnings.push("Could not detect Graphify version; entering best-effort mode.");
+    return { version: null, isSupported: false, warnings };
+  }
+
+  const isSupported = isAtLeast(version, MIN_SUPPORTED_GRAPHIFY);
+  if (!isSupported) {
+    warnings.push(
+      `Detected Graphify ${version} is below the supported minimum (${MIN_SUPPORTED_GRAPHIFY}). Some features may be disabled.`,
+    );
+  }
+
+  return { version, isSupported, warnings };
+}
+
+/** Best-effort parse a version string from CLI output. */
+export function parseVersion(output: string): string | null {
+  // Match semver-like strings such as 2.100.0, 2.100.0-alpha, etc.
+  const match = output.match(/(\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?)/);
+  return match?.[1] ?? null;
+}
+
+/** Compare two semver strings. Returns true if `version` >= `minimum`. */
+export function isAtLeast(version: string, minimum: string): boolean {
+  const v = version.split(".").map(Number);
+  const m = minimum.split(".").map(Number);
+  for (let i = 0; i < Math.max(v.length, m.length); i++) {
+    const a = v[i] ?? 0;
+    const b = m[i] ?? 0;
+    if (a > b) return true;
+    if (a < b) return false;
+  }
+  return true;
+}
+
+/** Build a capability matrix from version and runtime help probes. */
+export async function buildCapabilities(
+  _cli: string,
+  _cwd: string,
+  versionInfo: GraphifyVersionInfo,
+  runHelp: (args: string[]) => Promise<{ stdout: string; exitCode: number }>,
+): Promise<GraphifyCapabilities> {
+  const caps: GraphifyCapabilities = {
+    build: false,
+    query: false,
+    path: false,
+    explain: false,
+    affected: false,
+    add: false,
+    watch: false,
+    reflect: false,
+    mcp: false,
+    status: false,
+    version: false,
+    directedGraph: false,
+    incrementalUpdate: false,
+    semanticExtraction: false,
+  };
+
+  // Without a version, we can only safely probe. With a supported version, we
+  // still probe because runtime presence is more reliable than version numbers.
+  const canProbe = versionInfo.version !== null;
+  if (!canProbe) {
+    // Best-effort mode: leave everything disabled and let the coordinator warn.
+    return caps;
+  }
+
+  // Probe each subcommand. A zero exit on `<cmd> --help` means the command exists.
+  const commands = [
+    "build",
+    "query",
+    "path",
+    "explain",
+    "affected",
+    "add",
+    "watch",
+    "reflect",
+  ] as const;
+
+  for (const cmd of commands) {
+    const result = await runHelp([cmd, "--help"]);
+    if (result.exitCode === 0) {
+      // Map command existence to capability. Some capabilities share a command.
+      if (cmd === "build") {
+        caps.build = true;
+        caps.status = true;
+        caps.incrementalUpdate = helpMentions(result.stdout, "--update");
+        caps.directedGraph = helpMentions(result.stdout, "--directed");
+      } else {
+        caps[cmd] = true;
+      }
+    }
+  }
+
+  // Version is always reported if we can run the binary.
+  caps.version = true;
+
+  // MCP support requires both the CLI and the ability to spawn --mcp.
+  const mcpHelp = await runHelp(["--mcp", "--help"]).catch(() => ({ stdout: "", exitCode: 1 }));
+  caps.mcp = mcpHelp.exitCode === 0 || helpMentions(mcpHelp.stdout, "--mcp");
+
+  // Semantic extraction is inferred from help on build or extract commands.
+  caps.semanticExtraction =
+    caps.build &&
+    helpMentions(
+      await runHelp(["build", "--help"])
+        .then((r) => r.stdout)
+        .catch(() => ""),
+      ["--semantic", "--extract"],
+    );
+
+  return caps;
+}
+
+function helpMentions(help: string, flags: string | string[]): boolean {
+  const terms = Array.isArray(flags) ? flags : [flags];
+  return terms.some((flag) => help.includes(flag));
+}
+
+/** Run a quick probe command. */
+function runProbe(
+  cli: string,
+  args: string[],
+  cwd: string,
+  timeout: number,
+): Promise<{ stdout: string; exitCode: number; stderr: string }> {
+  return new Promise((resolve) => {
+    execFile(cli, args, { cwd, timeout }, (error, stdout, stderr) => {
+      if (error) {
+        resolve({
+          stdout: stdout.trim(),
+          stderr: stderr.trim(),
+          exitCode: typeof error.code === "number" ? error.code : 1,
+        });
+        return;
+      }
+      resolve({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 });
+    });
+  });
+}