@krosskinetic/pi-zg 0.1.1 → 0.1.3

package/README.md

@@ -1,13 +1,10 @@
-**WORK IN PROGRESS / ALPHA**
-
 # @krosskinetic/pi-zg
 
 A [Pi](https://github.com/earendil-works/pi-mono) package that natively integrates
-[zvec-grep](https://github.com/) (`zg`) semantic code search into Pi: it manages
-`zg`'s shared server, offers to build a missing index interactively, and gives
-the agent three tools (`zg_search`, `zg_rg`, `zg_index`) plus four commands
-(`/zg-settings`, `/zg-status`, `/zg-index`, `/zg-server`). It calls an existing local `zg` CLI;
-it does not install or bundle zvec-grep itself.
+[zvec-grep](https://github.com/) (`zg`) semantic code search into Pi: it offers
+to build a missing index interactively, and gives the agent four tools
+(`zg_search`, `zg_rg`, `zg_index`, `zg_status`) plus three commands
+(`/zg-settings`, `/zg-status`, `/zg-index`). It calls an existing local `zg` CLI;
 
 ## Prerequisites
 
@@ -32,9 +29,9 @@ pi -e .
 1. Install and configure `zg`, then verify that `zg version` works from your
    project directory.
 2. Install this package and start Pi in the project you want to search.
-3. At session start, pi-zg checks whether `zg` is available, whether its
-   shared server is ready, and whether the project has an index. Unless
-   disabled, it starts a stopped shared server.
+3. At session start, pi-zg checks whether `zg` is available and whether the
+   project has an index. Each `zg_search` refreshes the index first, so
+   results are never stale — no server daemon is used.
 4. Ask Pi a natural-language code-search question. Its `zg_search` tool
    searches the index. If the project has not been indexed, pi-zg offers to
    build one interactively.
@@ -44,22 +41,16 @@ exact identifier, literal, or regex search, Pi can use `zg_rg` instead.
 
 ## What it does
 
-### Shared server (`zg server`)
-
-`zg` runs a shared, loopback daemon that other tools (Claude, Cursor, etc.,
-configured via `zg install`) may also use. This extension:
+### Always-fresh direct searches
 
-- **Auto-starts** it at session start if it isn't already running
-  (`--no-zg-autostart` disables this). `zg server on` is idempotent, so this
-  is safe to run every session.
-- **Stops it at Pi session shutdown only when Pi started it.** Pi records the
-  daemon PID and rechecks it before stopping the server, so a server that was
-  already running—or has since been replaced—is left alone. Use
-  `/zg-server off` to stop a shared server explicitly.
+This extension runs every search in **direct mode and refreshes the index before
+answering** (`zg query --mode direct --refresh wait`). It does **not** use or manage
+zg's shared server daemon — there is no background process to keep alive, start,
+or shut down, so nothing can linger as an orphan between sessions.
 
-With the server running, `zg query` refreshes the index in the background
-automatically after file changes, so `zg_index` is rarely needed once a
-project has an initial index.
+Because each semantic search rebuilds any stale parts of the index first, results
+are never stale: after editing a file, the next `zg_search` reflects the change.
+This also means no index auto-refresh daemon needs to run at all.
 
 ### Tools (LLM-callable)
 
@@ -73,39 +64,48 @@ project has an initial index.
   does not require an index.
 - **`zg_index`** — build, rebuild, or drop the persistent index. Gated by
   prompt guidelines so the agent only uses it when the user explicitly asks.
+- **`zg_status`** — report zg version and the current project's index status.
+  Reads pi's cached zg state, so no extra `zg` subprocess is spawned for it.
 
 `zg_search` accepts a natural-language `query` and an optional `limit` of
 1–100 results (zg defaults to 7). `zg_rg` accepts a regex `pattern`, optional
 paths, `fixedString` for literal matching, and one `glob` filter. Its output
 and the output of the other tools are capped at 2,000 lines or 50 KB.
 
+
+#### Choosing a search tool
+
+Use the right tool for the kind of query, and don't reach for grep when semantic
+search is the better fit:
+
+- **`zg_search`** — find code by **meaning**. Use when you don't know the exact
+  identifiers or wording (“where is token refresh handled”, “how does the cache
+  layer work”). Keyword grep would miss these.
+- **`zg_rg`** — find code by **exact text**: a known identifier, string literal, or
+  regex, honoring the project's ignore/glob rules.
+- **Pi's built-in `grep`** — a quick literal scan when you don't need zg's
+  ignore rules or rg features.
+
+In short: concept → `zg_search`; exact token/regex → `zg_rg`; everything is
+refreshed before answering, so you always search current code.
 ### Commands (human-invoked)
 
-- **`/zg-settings`** — interactive configuration for Pi's search and refresh
-  mode, default embedding model, embedding device, and provider API key.
-- **`/zg-status`** — zg version, server state, and index status/coverage.
+- **`/zg-settings`** — interactive configuration for zg's default embedding
+  model, embedding device, and provider API key.
+- **`/zg-status`** — zg version and index status/coverage.
 - **`/zg-index [--rebuild|--drop]`** — build, rebuild, or drop the index
   directly, without going through the LLM. Confirms before `--drop`.
-- **`/zg-server <on|off|status>`** — explicit manual control of the shared
-  daemon. Confirms before `off`, since other tools may depend on it.
 
 ### Settings (`/zg-settings`)
 
 `/zg-settings` exposes the configuration that most directly affects Pi search:
 
-- **Search and refresh mode** — choose between a shared server with background
-  refresh, direct queries that refresh before every semantic search, or direct
-  queries that use the current index and can be stale. The choice applies to
-  the current Pi session. Switching to either direct mode stops a running
-  shared server only after confirmation, because the daemon owns index writes
-  and may be used by other tools.
 - **Default embedding model** — sets zg's persistent default for newly built
   indexes, for example `local/potion-code-16m-v2` or
   `qwen/text-embedding-v4`. Existing indexes keep their recorded embedding
   schema.
 - **Embedding device** — configures `auto`, `cpu`, `metal`, `vulkan`, or
-  `cuda` for a specified local model. The command can restart a running shared
-  server after confirmation so the changed runtime takes effect.
+  `cuda` for a specified local model.
 - **Provider API key** — saves credentials for a named embedding provider via
   `zg config provider set`. The value is passed directly to zg and is not
   shown in Pi notifications.
@@ -115,13 +115,11 @@ other less-common settings, use the underlying `zg` CLI directly.
 
 ### Status
 
-The footer shows `server ●/○` and `index ✓/✗` (colored via the active
-theme), refreshed at session start and at the start of every turn.
+The footer shows `index ✓/✗` (colored via the active theme), refreshed at
+session start and at the start of every turn.
 
 ### Flags
 
-- `--no-zg-autostart` — disable automatically starting the shared server at
-  Pi session start.
 - `--no-zg-onboard` — disable the interactive "build an index?" offer;
   `zg_search` fails with a manual-fix message instead (useful for
   non-interactive/scripted `pi -p` runs).
@@ -129,7 +127,6 @@ theme), refreshed at session start and at the start of every turn.
 Pass these when launching Pi, for example:
 
 ```bash
-pi --no-zg-autostart
 pi --no-zg-onboard
 ```
 
@@ -137,8 +134,7 @@ pi --no-zg-onboard
 
 - Does not register zg's MCP server as an actual MCP tool source inside Pi
   — Pi extensions have no MCP-client API, so integration stays CLI-based
-  (`pi.exec`), just daemon-aware and stateful rather than re-deriving status
-  via subprocess spawns before every call.
+  (`pi.exec`), stateful rather than re-deriving status via subprocess spawns
+  before every call.
 - Does not override Pi's built-in `grep` tool. `zg_search`/`zg_rg` are
   purely additive.
-- Does not stop a shared `zg` server that Pi did not start.

package/extensions/pi-zg.ts

@@ -9,10 +9,9 @@ import { Type } from "typebox";
  * pi-zg: a native Pi integration for the zvec-grep (`zg`) CLI.
  *
  * Beyond wrapping `zg query`/`zg index`, this extension:
- * - Auto-starts zg's shared server at session start so queries get
- *   background index auto-refresh for free, then shuts it down at Pi session
- *   end only when Pi owns that exact daemon PID.
- * - Caches zg's availability/server/index state per session (refreshed at
+ * - Runs every search in direct mode, refreshing the index before answering so
+ *   results are never stale (no background server daemon involved).
+ * - Caches zg's availability and index state per session (refreshed at
  *   session_start and each turn_start) instead of re-deriving it with
  *   extra `zg` subprocess spawns before every tool call.
  * - Offers to build a missing index interactively instead of just failing.
@@ -25,40 +24,24 @@ import { Type } from "typebox";
 
 const STATUS_KEY = "pi-zg";
 const DEFAULT_LOCAL_MODEL = "local/potion-code-16m-v2";
-type ZgQueryMode = "server" | "direct";
-type ZgRefreshPolicy = "background" | "wait" | "off";
-
 interface ZgState {
 	/** Whether refreshZgState has run at least once this session. */
 	checked: boolean;
 	/** Whether `zg` is on PATH. */
 	available: boolean;
 	version?: string;
-	/** Whether the shared zg server daemon is up and ready. */
-	serverRunning: boolean;
-	/** PID reported by the ready shared server, when available. */
-	serverPid?: string;
-	/** PID of the server Pi started and therefore owns for this session. */
-	ownedServerPid?: string;
 	/** Whether the current project has a ready index. */
 	indexed: boolean;
 	/** Whether the user already declined the "build an index?" offer this session. */
 	declinedIndexOffer: boolean;
-	/** Pi's active indexed-search transport for this session. */
-	queryMode: ZgQueryMode;
-	/** Pi's active freshness policy for this session. */
-	refreshPolicy: ZgRefreshPolicy;
 }
 
 function createZgState(): ZgState {
 	return {
 		checked: false,
 		available: false,
-		serverRunning: false,
 		indexed: false,
 		declinedIndexOffer: false,
-		queryMode: "server",
-		refreshPolicy: "background",
 	};
 }
 
@@ -77,21 +60,12 @@ function renderStatus(ctx: ExtensionContext, state: ZgState) {
 		ctx.ui.setStatus(STATUS_KEY, theme.fg("dim", "zg: not found"));
 		return;
 	}
-	const server = state.serverRunning ? theme.fg("success", "server\u25cf") : theme.fg("dim", "server\u25cb");
 	const index = state.indexed ? theme.fg("success", "index\u2713") : theme.fg("warning", "index\u2717");
-	ctx.ui.setStatus(STATUS_KEY, `${server} ${index}`);
+	ctx.ui.setStatus(STATUS_KEY, index);
 }
 
-function parseServerPid(output: string): string | undefined {
-	return output.match(/^PID:\s*(\d+)$/m)?.[1];
-}
 
-function markServerOwnedByPi(state: ZgState) {
-	// Do not risk stopping a daemon if zg did not report a stable PID for it.
-	if (state.serverRunning && state.serverPid) state.ownedServerPid = state.serverPid;
-}
-
-/** Refresh cached zg availability/server/index state and update the footer. */
+/** Refresh cached zg availability and index state, then update the footer. */
 async function refreshZgState(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
@@ -104,19 +78,12 @@ async function refreshZgState(
 	state.version = state.available ? version.stdout.trim() : undefined;
 
 	if (!state.available) {
-		state.serverRunning = false;
-		state.serverPid = undefined;
 		state.indexed = false;
 		renderStatus(ctx, state);
 		return state;
 	}
 
-	const [server, status] = await Promise.all([
-		execZg(pi, ["server", "status", "--check-ready"], ctx, { signal, timeout: 5_000 }),
-		execZg(pi, ["status", "--check-ready"], ctx, { signal, timeout: 5_000 }),
-	]);
-	state.serverRunning = server.code === 0;
-	state.serverPid = state.serverRunning ? parseServerPid(server.stdout) : undefined;
+	const status = await execZg(pi, ["status", "--check-ready"], ctx, { signal, timeout: 5_000 });
 	state.indexed = status.code === 0;
 
 	renderStatus(ctx, state);
@@ -137,97 +104,9 @@ function parseHitCount(output: string): number | undefined {
 	return match ? Number(match[1]) : undefined;
 }
 
-function searchModeLabel(state: ZgState): string {
-	if (state.queryMode === "server") return "server / background refresh";
-	return state.refreshPolicy === "wait" ? "direct / refresh before search" : "direct / current index";
-}
-
-async function ensureServerRunning(pi: ExtensionAPI, ctx: ExtensionContext, state: ZgState): Promise<boolean> {
-	if (state.serverRunning) return true;
-	ctx.ui.setWorkingMessage("Starting zg server...");
-	const result = await execZg(pi, ["server", "on"], ctx, { timeout: 20_000 });
-	ctx.ui.setWorkingMessage();
-	await refreshZgState(pi, ctx, state);
-	if (result.code === 0) markServerOwnedByPi(state);
-	if (result.code !== 0 || !state.serverRunning) {
-		ctx.ui.notify("zg server could not be started. Choose a direct search mode in /zg-settings or inspect /zg-server status.", "error");
-		return false;
-	}
-	return true;
-}
-
-/**
- * A daemon has an exclusive lease on index writes, so direct refresh must stop
- * it first. Ask because that daemon can be shared with other agent clients.
- */
-async function stopServerForDirectMode(pi: ExtensionAPI, ctx: ExtensionContext, state: ZgState): Promise<boolean> {
-	if (!state.serverRunning) return true;
-	const confirmed = await ctx.ui.confirm(
-		"Switch to direct searches?",
-		"Direct refresh writes to the index itself and requires stopping the shared zg server. This may affect other tools using it.",
-	);
-	if (!confirmed) return false;
-
-	ctx.ui.setWorkingMessage("Stopping zg server...");
-	const result = await execZg(pi, ["server", "off"], ctx, { timeout: 20_000 });
-	ctx.ui.setWorkingMessage();
-	await refreshZgState(pi, ctx, state);
-	if (result.code !== 0 || state.serverRunning) {
-		ctx.ui.notify("zg server could not be stopped; direct refresh was not enabled.", "error");
-		return false;
-	}
-	state.ownedServerPid = undefined;
-	return true;
-}
-
-async function offerServerRestart(pi: ExtensionAPI, ctx: ExtensionContext, state: ZgState): Promise<void> {
-	if (!state.serverRunning) return;
-	const restart = await ctx.ui.confirm(
-		"Restart zg server?",
-		"Restarting applies the changed embedding runtime to the shared server. Other tools using it will briefly lose access.",
-	);
-	if (!restart) return;
-	ctx.ui.setWorkingMessage("Restarting zg server...");
-	const stopped = await execZg(pi, ["server", "off"], ctx, { timeout: 20_000 });
-	if (stopped.code === 0) state.ownedServerPid = undefined;
-	const started = stopped.code === 0 ? await execZg(pi, ["server", "on"], ctx, { timeout: 20_000 }) : stopped;
-	ctx.ui.setWorkingMessage();
-	await refreshZgState(pi, ctx, state);
-	if (started.code === 0) markServerOwnedByPi(state);
-	ctx.ui.notify(
-		started.code === 0 && state.serverRunning ? "zg server restarted." : "zg server restart failed; inspect /zg-server status.",
-		started.code === 0 && state.serverRunning ? "info" : "error",
-	);
-}
-
-async function configureSearchMode(pi: ExtensionAPI, ctx: ExtensionContext, state: ZgState): Promise<void> {
-	const choice = await ctx.ui.select("Search and refresh mode", [
-		"Server — background refresh (fast repeated searches)",
-		"Direct — refresh before each search (no daemon)",
-		"Direct — use current index (fast, may be stale)",
-		"Cancel",
-	]);
-	if (!choice || choice === "Cancel") return;
-
-	if (choice.startsWith("Server")) {
-		state.queryMode = "server";
-		state.refreshPolicy = "background";
-		if (await ensureServerRunning(pi, ctx, state)) ctx.ui.notify("zg searches use the shared server with background refresh.", "info");
-		return;
-	}
 
-	if (!(await stopServerForDirectMode(pi, ctx, state))) return;
-	state.queryMode = "direct";
-	state.refreshPolicy = choice.startsWith("Direct — refresh") ? "wait" : "off";
-	ctx.ui.notify(
-		state.refreshPolicy === "wait"
-			? "zg searches refresh the index before each semantic query."
-			: "zg searches use the current index and may be stale after edits.",
-		"info",
-	);
-}
 
-async function configureDefaultModel(pi: ExtensionAPI, ctx: ExtensionContext, state: ZgState): Promise<void> {
+async function configureDefaultModel(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
 	const model = await ctx.ui.input("Default embedding model", "e.g. local/potion-code-16m-v2 or qwen/text-embedding-v4");
 	if (!model?.trim()) return;
 	const result = await execZg(pi, ["config", "model", "set", model.trim(), "--default"], ctx);
@@ -236,10 +115,9 @@ async function configureDefaultModel(pi: ExtensionAPI, ctx: ExtensionContext, st
 		return;
 	}
 	ctx.ui.notify(`Default embedding model set to ${model.trim()}. Existing indexes keep their current schema.`, "info");
-	await offerServerRestart(pi, ctx, state);
 }
 
-async function configureEmbeddingDevice(pi: ExtensionAPI, ctx: ExtensionContext, state: ZgState): Promise<void> {
+async function configureEmbeddingDevice(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
 	const model = await ctx.ui.input("Model to configure", "e.g. local/potion-code-16m-v2");
 	if (!model?.trim()) return;
 	const device = await ctx.ui.select("Embedding device", ["auto", "cpu", "metal", "vulkan", "cuda", "Cancel"]);
@@ -250,7 +128,6 @@ async function configureEmbeddingDevice(pi: ExtensionAPI, ctx: ExtensionContext,
 		return;
 	}
 	ctx.ui.notify(`Embedding device for ${model.trim()} set to ${device}.`, "info");
-	await offerServerRestart(pi, ctx, state);
 }
 
 async function configureProviderKey(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
@@ -270,8 +147,7 @@ async function openZgSettings(pi: ExtensionAPI, ctx: ExtensionContext, state: Zg
 	if (!state.checked) await refreshZgState(pi, ctx, state);
 
 	while (true) {
-		const choice = await ctx.ui.select(`zg settings — ${searchModeLabel(state)}`, [
-			"Search and refresh mode",
+		const choice = await ctx.ui.select("zg settings", [
 			"Default embedding model",
 			"Embedding device",
 			"Provider API key",
@@ -281,14 +157,11 @@ async function openZgSettings(pi: ExtensionAPI, ctx: ExtensionContext, state: Zg
 		if (!choice || choice === "Done") return;
 
 		switch (choice) {
-			case "Search and refresh mode":
-				await configureSearchMode(pi, ctx, state);
-				break;
 			case "Default embedding model":
-				await configureDefaultModel(pi, ctx, state);
+				await configureDefaultModel(pi, ctx);
 				break;
 			case "Embedding device":
-				await configureEmbeddingDevice(pi, ctx, state);
+				await configureEmbeddingDevice(pi, ctx);
 				break;
 			case "Provider API key":
 				await configureProviderKey(pi, ctx);
@@ -298,9 +171,6 @@ async function openZgSettings(pi: ExtensionAPI, ctx: ExtensionContext, state: Zg
 				const detail = await execZg(pi, ["status"], ctx);
 				ctx.ui.notify(
 					[
-						`Pi search mode: ${searchModeLabel(state)} (session setting)`,
-						`zg server: ${state.serverRunning ? "running" : "stopped"}`,
-						"",
 						(detail.stdout || detail.stderr).trim(),
 					].join("\n"),
 					state.indexed ? "info" : "warning",
@@ -337,7 +207,7 @@ async function offerToBuildIndex(
 	}
 
 	ctx.ui.setWorkingMessage("Building zg index...");
-	let result = await execZg(pi, ["index", "--mode", state.queryMode], ctx, { signal, timeout: 300_000 });
+	let result = await execZg(pi, ["index", "--mode", "direct"], ctx, { signal, timeout: 300_000 });
 
 	if (result.code !== 0 && /embedding/i.test(result.stderr)) {
 		// No default embedding model configured yet -- offer to set one and retry.
@@ -354,7 +224,7 @@ async function offerToBuildIndex(
 		}
 		if (model) {
 			await execZg(pi, ["config", "model", "set", model, "--default"], ctx, { signal });
-			result = await execZg(pi, ["index", "--mode", state.queryMode, "--embedding", model], ctx, {
+			result = await execZg(pi, ["index", "--mode", "direct", "--embedding", model], ctx, {
 				signal,
 				timeout: 300_000,
 			});
@@ -376,46 +246,16 @@ async function offerToBuildIndex(
 export default function (pi: ExtensionAPI) {
 	const state = createZgState();
 
-	pi.registerFlag("no-zg-autostart", {
-		description: "Disable automatically starting the shared zg server at session start",
-		type: "boolean",
-		default: false,
-	});
 	pi.registerFlag("no-zg-onboard", {
 		description: "Disable the interactive offer to build a missing zg index; fail with a manual-fix message instead",
 		type: "boolean",
 		default: false,
 	});
 
-	pi.on("session_start", async (_event, ctx) => {
-		await refreshZgState(pi, ctx, state);
-
-		if (!pi.getFlag("no-zg-autostart") && state.queryMode === "server" && state.available && !state.serverRunning) {
-			// Fire-and-forget: don't block startup on daemon warmup. `zg server on`
-			// is idempotent, so this is safe even if something else started it
-			// in the meantime.
-			execZg(pi, ["server", "on"], ctx, { timeout: 20_000 })
-				.then(async (result) => {
-					await refreshZgState(pi, ctx, state);
-					if (result.code === 0) markServerOwnedByPi(state);
-				})
-				.catch(() => {});
-		}
-	});
-
-	pi.on("session_shutdown", async (_event, ctx) => {
-		if (!state.ownedServerPid) return;
+pi.on("session_start", async (_event, ctx) => {
+	await refreshZgState(pi, ctx, state);
+});
 
-		// Recheck the PID before stopping anything. If another process replaced the
-		// daemon, it is no longer the server Pi started and must be left alone.
-		const server = await execZg(pi, ["server", "status", "--check-ready"], ctx, { timeout: 5_000 });
-		if (server.code !== 0 || parseServerPid(server.stdout) !== state.ownedServerPid) return;
-
-		await execZg(pi, ["server", "off"], ctx, { timeout: 20_000 });
-		state.serverRunning = false;
-		state.serverPid = undefined;
-		state.ownedServerPid = undefined;
-	});
 
 	pi.on("turn_start", async (_event, ctx) => {
 		if (state.available) {
@@ -427,7 +267,7 @@ export default function (pi: ExtensionAPI) {
 		name: "zg_search",
 		label: "zg search",
 		description:
-			"Semantic code search over the current project's zvec-grep index. Requires zg on PATH; offers to build a missing index interactively when possible. With the zg server running, the index refreshes in the background automatically. Returns at most 2,000 lines or 50 KB of CLI output.",
+				"Semantic (meaning-based) code search over the current project's zvec-grep index. The go-to when you want to find code by CONCEPT rather than exact text — e.g. where authentication is handled, or how a feature works — without knowing the precise identifiers. Each call refreshes the index first, so results are never stale; it offers to build the index interactively if none exists. Prefer over keyword grep when an exact-token search would miss relevant code. For precise identifiers, string literals, or regex, use zg_rg or the built-in grep tool instead. Returns at most 2,000 lines or 50 KB of CLI output.",
 		promptSnippet: "Semantic search in the current project's zg index",
 		parameters: Type.Object({
 			query: Type.String({ minLength: 1, description: "Semantic code-search query" }),
@@ -448,16 +288,13 @@ export default function (pi: ExtensionAPI) {
 				);
 			}
 
-			if (state.queryMode === "server" && !(await ensureServerRunning(pi, ctx, state))) {
-				throw new Error("zg server is unavailable. Use /zg-settings to choose a direct search mode or /zg-server to inspect it.");
-			}
 			if (!state.indexed && !(await offerToBuildIndex(pi, ctx, state, signal))) {
 				throw new Error(
 					`This project does not appear to be indexed. Run \`zg index\` manually in ${ctx.cwd}, then retry.`,
 				);
 			}
 
-			const args = ["query", "--mode", state.queryMode, "--refresh", state.refreshPolicy];
+			const args = ["query", "--mode", "direct", "--refresh", "wait"];
 			if (params.limit !== undefined) args.push("--limit", String(params.limit));
 			args.push(params.query);
 
@@ -480,7 +317,7 @@ export default function (pi: ExtensionAPI) {
 		name: "zg_rg",
 		label: "zg managed ripgrep",
 		description:
-			"Exhaustive exact-match search via zvec-grep's managed ripgrep (`zg query --rg`). Respects this project's configured ignore/glob rules. Complements zg_search (semantic) and the built-in grep tool; does not require an index.",
+			"Exhaustive exact-match search via zvec-grep's managed ripgrep (`zg query --rg`). Use when you know the precise identifier, string literal, or regex to locate and want results that honor the project's configured ignore/glob rules (e.g. excluding node_modules). Prefer it over zg_search when you need literal/regex matches rather than meaning; prefer it over the built-in grep tool when you want rg's powers (globs, -F literal) with the project's ignore rules applied. Does not require an index.",
 		promptSnippet: "Exhaustive managed ripgrep search via zg (respects project ignore rules)",
 		parameters: Type.Object({
 			pattern: Type.String({ minLength: 1, description: "Pattern to search for" }),
@@ -522,7 +359,7 @@ export default function (pi: ExtensionAPI) {
 		name: "zg_index",
 		label: "zg index",
 		description:
-			"Build, rebuild, or drop the current project's persistent zvec-grep index. Use only when the user explicitly asks: with the zg server running, an existing index already refreshes in the background after edits, so this is mainly for the first-time build, an explicit rebuild, or dropping the index.",
+			"Build, rebuild, or drop the current project's persistent zvec-grep index. Use only when the user explicitly asks: searches already refresh a stale index before answering, so this is mainly for the first-time build, an explicit rebuild, or dropping the index.",
 		promptSnippet: "Explicitly build, rebuild, or drop the current project's zg index",
 		promptGuidelines: [
 			"Use zg_index only when the user explicitly requests indexing, rebuilding, or dropping the zg index; do not call it merely because zg_search reports a missing index -- that flow already offers to build it interactively.",
@@ -543,7 +380,7 @@ export default function (pi: ExtensionAPI) {
 				throw new Error("`zg` is not available on PATH. Install @zvec/zvec-grep separately before indexing.");
 			}
 
-			const args = ["index", "--mode", state.queryMode];
+			const args = ["index", "--mode", "direct"];
 			if (params.drop) args.push("--drop", "--yes");
 			else if (params.rebuild) args.push("--rebuild");
 
@@ -561,15 +398,49 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerTool({
+		name: "zg_status",
+		label: "zg status",
+		description:
+			"Report zg availability and the current project's index status (ready or not). Use to confirm zg is set up and the index is current before relying on semantic search, or to diagnose why zg_search/zg_rg return nothing. Reads pi's cached state (refreshed for this call) and does not spawn a separate `zg` subprocess. For full index detail/coverage, humans can use `/zg-status`.",
+		promptSnippet: "Check zg availability and index status",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
+			if (!state.checked) await refreshZgState(pi, ctx, state, signal);
+			if (!state.available) {
+				throw new Error("`zg` is not available on PATH. Install @zvec/zvec-grep separately before checking status.");
+			}
+
+			await refreshZgState(pi, ctx, state, signal);
+			const index = state.indexed ? "index: ready" : "index: not ready";
+			return {
+				content: [
+					{
+						type: "text",
+						text: [
+							`zg: ${state.version || "available"}`,
+							index,
+						].join("\n"),
+					},
+				],
+				details: {
+					available: true,
+					version: state.version,
+					indexed: state.indexed,
+				},
+			};
+		},
+	});
+
 	pi.registerCommand("zg-settings", {
-		description: "Configure Pi search mode plus zg embedding model, device, and provider credentials",
+		description: "Configure zg embedding model, device, and provider credentials",
 		handler: async (_args, ctx) => {
 			await openZgSettings(pi, ctx, state);
 		},
 	});
 
 	pi.registerCommand("zg-status", {
-		description: "Report zg version, server, and index status for this project",
+		description: "Report zg version and index status for this project",
 		handler: async (_args, ctx) => {
 			await refreshZgState(pi, ctx, state);
 			if (!state.available) {
@@ -580,8 +451,6 @@ export default function (pi: ExtensionAPI) {
 			const detail = await execZg(pi, ["status"], ctx);
 			const lines = [
 				`zg: ${state.version || "available"}`,
-				`server: ${state.serverRunning ? "running" : "stopped"}`,
-				`Pi search mode: ${searchModeLabel(state)} (session setting)`,
 				"",
 				(detail.stdout || detail.stderr).trim(),
 			];
@@ -606,7 +475,7 @@ export default function (pi: ExtensionAPI) {
 				if (!confirmed) return;
 			}
 
-			const cmdArgs = ["index", "--mode", state.queryMode];
+			const cmdArgs = ["index", "--mode", "direct"];
 			if (drop) cmdArgs.push("--drop", "--yes");
 			else if (rebuild) cmdArgs.push("--rebuild");
 
@@ -623,37 +492,4 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerCommand("zg-server", {
-		description: "Control the shared zg server: /zg-server <on|off|status>",
-		handler: async (args, ctx) => {
-			if (!state.available) {
-				ctx.ui.notify("zg: not found on PATH", "error");
-				return;
-			}
-
-			const action = args.trim().toLowerCase() || "status";
-			if (action !== "on" && action !== "off" && action !== "status") {
-				ctx.ui.notify("Usage: /zg-server <on|off|status>", "warning");
-				return;
-			}
-
-			if (action === "off") {
-				const confirmed = await ctx.ui.confirm(
-					"Stop the shared zg server?",
-					"This daemon may be used by other agents/tools (Claude, Cursor, etc.) configured via `zg install`. Stopping it affects all of them, not just this session.",
-				);
-				if (!confirmed) return;
-			}
-
-			const wasServerRunning = state.serverRunning;
-			const result = await execZg(pi, ["server", action], ctx, { timeout: 20_000 });
-			await refreshZgState(pi, ctx, state);
-			if (action === "on" && !wasServerRunning && result.code === 0) markServerOwnedByPi(state);
-			if (action === "off" && result.code === 0) state.ownedServerPid = undefined;
-			ctx.ui.notify(
-				(result.stdout || result.stderr).trim() || `zg server ${action} done.`,
-				result.code === 0 ? "info" : "error",
-			);
-		},
-	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@krosskinetic/pi-zg",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"description": "Pi extension for zvec-grep (zg): semantic code search, managed ripgrep, and shared-server-aware index management",
 	"type": "module",
 	"keywords": [