@matyah00/openpi 0.1.2

package/extensions/minimal.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal — Model name + context meter in a compact footer
+ *
+ * Shows model ID and a 10-block context usage bar: [###-------] 30%
+ *
+ * Usage: pi -e extensions/minimal.ts
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { applyExtensionDefaults } from "./themeMap.ts";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		applyExtensionDefaults(import.meta.url, ctx);
+		ctx.ui.setFooter((_tui, theme, _footerData) => ({
+			dispose: () => {},
+			invalidate() {},
+			render(width: number): string[] {
+				const model = ctx.model?.id || "no-model";
+				const usage = ctx.getContextUsage();
+				const pct = (usage && usage.percent !== null) ? usage.percent : 0;
+				const filled = Math.round(pct / 10);
+				const bar = "#".repeat(filled) + "-".repeat(10 - filled);
+
+				const left = theme.fg("dim", ` ${model}`);
+				const right = theme.fg("dim", `[${bar}] ${Math.round(pct)}% `);
+				const pad = " ".repeat(Math.max(1, width - visibleWidth(left) - visibleWidth(right)));
+
+				return [truncateToWidth(left + pad + right, width)];
+			},
+		}));
+	});
+}

package/extensions/openpi.ts

@@ -0,0 +1,255 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { extensionDir } from "./lib/packagePaths.ts";
+
+type Profile = {
+  name: string;
+  description: string;
+  extensions: string[];
+  notes?: string[];
+};
+
+const PROFILES: Profile[] = [
+  {
+    name: "commands",
+    description: "Pi-native slash commands from bundled and project .pi/prompts.",
+    extensions: ["commands.ts", "search-tools.ts", "audit-tools.ts", "state-tools.ts", "minimal.ts", "theme-cycler.ts"],
+  },
+  {
+    name: "explore",
+    description: "Project tree, batched code search, and discovery commands.",
+    extensions: ["commands.ts", "search-tools.ts", "audit-tools.ts", "state-tools.ts", "workflow.ts", "minimal.ts", "theme-cycler.ts"],
+  },
+  {
+    name: "guard",
+    description: "Security, dependency, environment, test-integrity, and ship-readiness tools.",
+    extensions: ["commands.ts", "audit-tools.ts", "search-tools.ts", "state-tools.ts", "workflow.ts", "minimal.ts", "theme-cycler.ts"],
+  },
+  {
+    name: "workflow",
+    description: "Pi-native /add, /fix, /review workflows with isolated role-agent delegation.",
+    extensions: ["workflow.ts", "search-tools.ts", "audit-tools.ts", "state-tools.ts", "minimal.ts", "theme-cycler.ts"],
+    notes: ["This profile owns /review; the bundled prompt-template review command is exposed as /code-review."],
+  },
+  {
+    name: "focus",
+    description: "Distraction-free Pi UI with theme defaults.",
+    extensions: ["pure-focus.ts", "theme-cycler.ts"],
+  },
+  {
+    name: "purpose",
+    description: "Require a session purpose and keep it visible while working.",
+    extensions: ["purpose-gate.ts", "minimal.ts", "theme-cycler.ts"],
+  },
+  {
+    name: "metrics",
+    description: "Show model, context, token, cost, branch, and tool usage metrics.",
+    extensions: ["tool-counter.ts", "theme-cycler.ts"],
+  },
+  {
+    name: "tool-widget",
+    description: "Show live per-tool usage counts above the editor.",
+    extensions: ["tool-counter-widget.ts", "minimal.ts", "theme-cycler.ts"],
+  },
+  {
+    name: "safety",
+    description: "Load Damage-Control rules and return actionable feedback for blocked tool calls.",
+    extensions: ["damage-control-continue.ts", "minimal.ts", "theme-cycler.ts"],
+  },
+  {
+    name: "system",
+    description: "Switch the active system persona from Pi-native agents.",
+    extensions: ["system-select.ts", "minimal.ts", "theme-cycler.ts"],
+  },
+  {
+    name: "team",
+    description: "Dispatcher-only specialist-agent team with dispatch_agent.",
+    extensions: ["agent-team.ts"],
+  },
+  {
+    name: "chain",
+    description: "Sequential agent workflow runner with run_chain.",
+    extensions: ["agent-chain.ts"],
+  },
+  {
+    name: "full",
+    description: "Commands, workflow, purpose gate, safety, metrics, personas, team dispatcher, and chains.",
+    extensions: ["commands.ts", "search-tools.ts", "audit-tools.ts", "state-tools.ts", "workflow.ts", "purpose-gate.ts", "damage-control-continue.ts", "tool-counter.ts", "system-select.ts", "agent-team.ts", "agent-chain.ts", "theme-cycler.ts"],
+    notes: ["Team and chain both alter system prompts; enable together only when you want the full orchestration surface."],
+  },
+];
+
+const PROFILE_BY_NAME = new Map(PROFILES.map((profile) => [profile.name, profile]));
+const MANAGED_EXTENSION_FILES = new Set(["openpi.ts", ...PROFILES.flatMap((profile) => profile.extensions)]);
+const MANAGED_EXTENSION_PATHS = new Set(
+  Array.from(MANAGED_EXTENSION_FILES).map((file) => normalizePath(path.join(extensionDir, file))),
+);
+
+function normalizePath(value: string): string {
+  return path.resolve(value).replace(/\\/g, "/").toLowerCase();
+}
+
+function extensionPath(file: string): string {
+  return path.join(extensionDir, file);
+}
+
+function readJsonFile(filePath: string): Record<string, unknown> {
+  if (!fs.existsSync(filePath)) return {};
+  return JSON.parse(fs.readFileSync(filePath, "utf-8")) as Record<string, unknown>;
+}
+
+function writeJsonFile(filePath: string, value: Record<string, unknown>) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+}
+
+function addUnique(items: string[], additions: string[]): string[] {
+  const seen = new Set(items.map((item) => normalizePath(item)));
+  const out = [...items];
+  for (const item of additions) {
+    const key = normalizePath(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
+function isManagedExtensionEntry(entry: string, settingsDir: string): boolean {
+  const absolute = path.isAbsolute(entry) ? entry : path.resolve(settingsDir, entry);
+  return MANAGED_EXTENSION_PATHS.has(normalizePath(absolute));
+}
+
+function resolveSettingsPath(cwd: string, global: boolean): string {
+  return global ? path.join(os.homedir(), ".pi", "agent", "settings.json") : path.join(cwd, ".pi", "settings.json");
+}
+
+function applyProfileToSettings(settingsPath: string, profile: Profile): { added: string[]; removed: number } {
+  const settingsDir = path.dirname(settingsPath);
+  const settings = readJsonFile(settingsPath);
+  const currentExtensions = stringArray(settings.extensions);
+  const keptExtensions = currentExtensions.filter((entry) => !isManagedExtensionEntry(entry, settingsDir));
+  const added = profile.extensions.map(extensionPath);
+
+  settings.extensions = addUnique(keptExtensions, added);
+  writeJsonFile(settingsPath, settings);
+
+  return { added, removed: currentExtensions.length - keptExtensions.length };
+}
+
+function clearProfileFromSettings(settingsPath: string): { removed: number } {
+  const settingsDir = path.dirname(settingsPath);
+  const settings = readJsonFile(settingsPath);
+  const currentExtensions = stringArray(settings.extensions);
+  settings.extensions = currentExtensions.filter((entry) => !isManagedExtensionEntry(entry, settingsDir));
+  writeJsonFile(settingsPath, settings);
+  return { removed: currentExtensions.length - stringArray(settings.extensions).length };
+}
+
+function profileListMarkdown(): string {
+  return [
+    "# openpi profiles",
+    "",
+    "Use `/openpi use <profile>` to activate a profile for this project.",
+    "Use `/openpi use <profile> --global` to activate it globally.",
+    "Run `/reload` or restart Pi after changing profiles.",
+    "",
+    ...PROFILES.map((profile) => `- **${profile.name}** - ${profile.description}`),
+  ].join("\n");
+}
+
+function parseArgs(args: string | undefined): string[] {
+  return (args || "").trim().split(/\s+/).filter(Boolean);
+}
+
+function emit(pi: ExtensionAPI, content: string) {
+  pi.sendMessage({ customType: "openpi", content, display: true });
+}
+
+function registerProfileCommand(pi: ExtensionAPI, name: string, description: string) {
+  pi.registerCommand(name, {
+    description,
+    getArgumentCompletions: (prefix) => {
+      const words = prefix.trim().split(/\s+/);
+      const first = words[0] || "";
+      if (!prefix.includes(" ")) {
+        return ["list", "use", "clear", ...PROFILES.map((p) => p.name)]
+          .filter((value) => value.startsWith(first))
+          .map((value) => ({ value, label: value }));
+      }
+      if (words[0] === "use") {
+        const partial = words[1] || "";
+        return PROFILES.filter((profile) => profile.name.startsWith(partial)).map((profile) => ({
+          value: profile.name,
+          label: profile.name,
+          description: profile.description,
+        }));
+      }
+      return null;
+    },
+    handler: async (args, ctx) => {
+      const tokens = parseArgs(args);
+      const action = tokens[0] || "list";
+
+      if (action === "list" || action === "help") {
+        emit(pi, profileListMarkdown());
+        return;
+      }
+
+      if (PROFILE_BY_NAME.has(action)) tokens.unshift("use");
+
+      if (tokens[0] === "use") {
+        const profile = PROFILE_BY_NAME.get(tokens[1] || "");
+        if (!profile) {
+          ctx.ui.notify("Usage: /openpi use <profile> [--global]", "error");
+          return;
+        }
+        const global = tokens.includes("--global");
+        const settingsPath = resolveSettingsPath(ctx.cwd, global);
+        const result = applyProfileToSettings(settingsPath, profile);
+        emit(pi, [
+          `Activated **${profile.name}** in ${global ? "global" : "project"} Pi settings.`,
+          "",
+          `Settings: \`${settingsPath}\``,
+          `Removed previous openpi profile entries: ${result.removed}`,
+          "Added:",
+          ...result.added.map((entry) => `- \`${entry}\``),
+          "",
+          "Run `/reload` or restart Pi.",
+          ...(profile.notes?.length ? ["", ...profile.notes.map((note) => `- ${note}`)] : []),
+        ].join("\n"));
+        return;
+      }
+
+      if (tokens[0] === "clear") {
+        const global = tokens.includes("--global");
+        const settingsPath = resolveSettingsPath(ctx.cwd, global);
+        const result = clearProfileFromSettings(settingsPath);
+        emit(pi, `Cleared ${result.removed} openpi extension entr${result.removed === 1 ? "y" : "ies"} from \`${settingsPath}\`. Run \`/reload\` or restart Pi.`);
+        return;
+      }
+
+      emit(pi, profileListMarkdown());
+    },
+  });
+}
+
+export default function (pi: ExtensionAPI) {
+  registerProfileCommand(pi, "openpi", "Manage openpi native profiles");
+  registerProfileCommand(pi, "azpi", "Deprecated alias for /openpi");
+
+  pi.registerCommand("open-pi", {
+    description: "Show openpi native package profiles",
+    handler: async () => emit(pi, profileListMarkdown()),
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setStatus("openpi", `openpi profiles: ${PROFILES.length}`);
+  });
+}

package/extensions/pure-focus.ts

@@ -0,0 +1,24 @@
+/**
+ * Pure Focus — Strip all footer and status line UI
+ *
+ * Removes the footer bar and status line entirely, leaving only
+ * the conversation and editor. Pure distraction-free mode.
+ *
+ * Usage: pi -e examples/extensions/pure-focus.ts
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { applyExtensionDefaults } from "./themeMap.ts";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		applyExtensionDefaults(import.meta.url, ctx);
+		ctx.ui.setFooter((_tui, _theme, _footerData) => ({
+			dispose: () => {},
+			invalidate() {},
+			render(_width: number): string[] {
+				return [];
+			},
+		}));
+	});
+}

package/extensions/purpose-gate.ts

@@ -0,0 +1,84 @@
+/**
+ * Purpose Gate — Forces the engineer to declare intent before working
+ *
+ * On session start, immediately asks "What is the purpose of this agent?"
+ * via a text input dialog. A persistent widget shows the purpose for the
+ * rest of the session, keeping focus. Blocks all prompts until answered.
+ *
+ * Usage: pi -e extensions/purpose-gate.ts
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Text, truncateToWidth } from "@mariozechner/pi-tui";
+import { applyExtensionDefaults } from "./themeMap.ts";
+
+// synthwave: bgWarm #4a1e6a → rgb(74,30,106)
+function bg(s: string): string {
+	return `\x1b[48;2;74;30;106m${s}\x1b[49m`;
+}
+
+// synthwave: pink #ff7edb
+function pink(s: string): string {
+	return `\x1b[38;2;255;126;219m${s}\x1b[39m`;
+}
+
+// synthwave: cyan #36f9f6
+function cyan(s: string): string {
+	return `\x1b[38;2;54;249;246m${s}\x1b[39m`;
+}
+
+function bold(s: string): string {
+	return `\x1b[1m${s}\x1b[22m`;
+}
+
+export default function (pi: ExtensionAPI) {
+	let purpose: string | undefined;
+
+	async function askForPurpose(ctx: any) {
+		while (!purpose) {
+			const answer = await ctx.ui.input(
+				"What is the purpose of this agent?",
+				"e.g. Refactor the auth module to use JWT"
+			);
+
+			if (answer && answer.trim()) {
+				purpose = answer.trim();
+			} else {
+				ctx.ui.notify("Purpose is required.", "warning");
+			}
+		}
+
+		ctx.ui.setWidget("purpose", () => {
+			return {
+				render(width: number): string[] {
+					const pad = bg(" ".repeat(width));
+					const label = pink(bold("  PURPOSE: "));
+					const msg = cyan(bold(purpose!));
+					const content = bg(truncateToWidth(label + msg + " ".repeat(width), width, ""));
+					return [pad, content, pad];
+				},
+				invalidate() {},
+			};
+		});
+	}
+
+	pi.on("session_start", async (_event, ctx) => {
+		applyExtensionDefaults(import.meta.url, ctx);
+		void askForPurpose(ctx);
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		if (!purpose) return;
+		return {
+			systemPrompt: event.systemPrompt + `\n\n<purpose>\nYour singular purpose this session: ${purpose}\nStay focused on this goal. If a request drifts from this purpose, gently remind the user.\n</purpose>`,
+		};
+	});
+
+	pi.on("input", async (_event, ctx) => {
+		if (!purpose) {
+			ctx.ui.notify("Set a purpose first.", "warning");
+			return { action: "handled" as const };
+		}
+		return { action: "continue" as const };
+	});
+}

package/extensions/search-tools.ts

@@ -0,0 +1,277 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+const DEFAULT_IGNORES = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  "node_modules",
+  ".next",
+  ".nuxt",
+  ".turbo",
+  ".cache",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".pytest_cache",
+  ".mypy_cache",
+  ".ruff_cache",
+  "target",
+]);
+
+type TreeNode = {
+  name: string;
+  relativePath: string;
+  isDirectory: boolean;
+  children?: TreeNode[];
+};
+
+type SearchQuery = {
+  pattern: string;
+  cwd?: string;
+  globs?: string[];
+  caseInsensitive?: boolean;
+  before?: number;
+  after?: number;
+  maxResults?: number;
+};
+
+function isInside(parent: string, candidate: string): boolean {
+  const relative = path.relative(parent, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function resolveProjectPath(projectRoot: string, requested?: string): string {
+  const resolved = path.resolve(projectRoot, requested || ".");
+  if (!isInside(path.resolve(projectRoot), resolved)) {
+    throw new Error(`Path must stay inside project root: ${requested}`);
+  }
+  return resolved;
+}
+
+function normalizeRelative(projectRoot: string, value: string): string {
+  const relative = path.relative(projectRoot, value).replace(/\\/g, "/");
+  return relative || ".";
+}
+
+function readIgnoreNames(dir: string): Set<string> {
+  const names = new Set(DEFAULT_IGNORES);
+  for (const ignoreFile of [".gitignore", ".piignore"]) {
+    const filePath = path.join(dir, ignoreFile);
+    if (!fs.existsSync(filePath)) continue;
+    const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/);
+    for (const rawLine of lines) {
+      const line = rawLine.trim();
+      if (!line || line.startsWith("#") || line.startsWith("!") || line.includes("*")) continue;
+      names.add(line.replace(/\/$/, ""));
+    }
+  }
+  return names;
+}
+
+function buildTree(params: {
+  projectRoot: string;
+  root: string;
+  maxDepth: number;
+  maxEntries: number;
+  includeHidden: boolean;
+}): { nodes: TreeNode[]; omitted: number; visited: number } {
+  const ignoreNames = readIgnoreNames(params.projectRoot);
+  let visited = 0;
+  let omitted = 0;
+
+  const walk = (dir: string, depth: number): TreeNode[] => {
+    if (depth > params.maxDepth || visited >= params.maxEntries) return [];
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      omitted++;
+      return [];
+    }
+
+    entries.sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name));
+    const nodes: TreeNode[] = [];
+    for (const entry of entries) {
+      if (visited >= params.maxEntries) {
+        omitted++;
+        continue;
+      }
+      if (!params.includeHidden && entry.name.startsWith(".")) continue;
+      if (ignoreNames.has(entry.name)) continue;
+
+      const absolutePath = path.join(dir, entry.name);
+      const relativePath = normalizeRelative(params.projectRoot, absolutePath);
+      visited++;
+
+      if (entry.isDirectory()) {
+        nodes.push({
+          name: entry.name,
+          relativePath,
+          isDirectory: true,
+          children: walk(absolutePath, depth + 1),
+        });
+      } else {
+        nodes.push({ name: entry.name, relativePath, isDirectory: false });
+      }
+    }
+    return nodes;
+  };
+
+  return { nodes: walk(params.root, 0), omitted, visited };
+}
+
+function renderTree(nodes: TreeNode[], prefix = ""): string[] {
+  const lines: string[] = [];
+  nodes.forEach((node, index) => {
+    const isLast = index === nodes.length - 1;
+    const connector = isLast ? "`-- " : "|-- ";
+    lines.push(`${prefix}${connector}${node.name}${node.isDirectory ? "/" : ""}`);
+    if (node.children?.length) {
+      lines.push(...renderTree(node.children, `${prefix}${isLast ? "    " : "|   "}`));
+    }
+  });
+  return lines;
+}
+
+function runRipgrep(projectRoot: string, query: SearchQuery): Promise<string> {
+  const cwd = resolveProjectPath(projectRoot, query.cwd);
+  const args = ["--line-number", "--column", "--no-heading", "--color", "never"];
+  if (query.caseInsensitive) args.push("-i");
+  if (query.before) args.push("-B", String(query.before));
+  if (query.after) args.push("-A", String(query.after));
+  for (const glob of query.globs || []) args.push("-g", glob);
+  if (query.maxResults && query.maxResults > 0) args.push("-m", String(query.maxResults));
+  args.push(query.pattern, ".");
+
+  return new Promise((resolve) => {
+    const proc = spawn("rg", args, { cwd, shell: false });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    proc.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    proc.on("error", (error) => {
+      resolve(`ERROR: ${error.message}`);
+    });
+    proc.on("close", (code) => {
+      if (code === 0 || code === 1) resolve(stdout.trim());
+      else resolve(`ERROR: rg exited ${code}\n${stderr.trim()}`);
+    });
+  });
+}
+
+function truncateLines(text: string, maxLines: number): string {
+  const lines = text.split(/\r?\n/).filter(Boolean);
+  if (lines.length <= maxLines) return lines.join("\n");
+  return `${lines.slice(0, maxLines).join("\n")}\n[truncated ${lines.length - maxLines} lines]`;
+}
+
+export default function searchToolsExtension(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "project_tree",
+    label: "Project Tree",
+    description: "Build a compact project tree while ignoring common generated folders.",
+    promptSnippet: "Use project_tree before broad exploration to understand repo shape without reading many files.",
+    promptGuidelines: [
+      "Use project_tree with maxDepth 2-4 before broad file discovery.",
+      "Keep maxEntries bounded; follow up with code_search_batch for specific symbols or terms.",
+    ],
+    parameters: Type.Object({
+      root: Type.Optional(Type.String({ description: "Project-relative root directory. Defaults to current project root." })),
+      maxDepth: Type.Optional(Type.Number({ description: "Maximum directory depth. Default 3." })),
+      maxEntries: Type.Optional(Type.Number({ description: "Maximum entries to include. Default 400." })),
+      includeHidden: Type.Optional(Type.Boolean({ description: "Include hidden files and directories. Default false." })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const root = resolveProjectPath(ctx.cwd, params.root as string | undefined);
+      const maxDepth = Math.max(0, Math.min(Number(params.maxDepth ?? 3), 8));
+      const maxEntries = Math.max(20, Math.min(Number(params.maxEntries ?? 400), 4000));
+      const includeHidden = Boolean(params.includeHidden);
+      const result = buildTree({ projectRoot: ctx.cwd, root, maxDepth, maxEntries, includeHidden });
+      const header = [
+        `root: ${normalizeRelative(ctx.cwd, root)}`,
+        `depth: ${maxDepth}`,
+        `entries: ${result.visited}`,
+        result.omitted ? `omitted: ${result.omitted}` : undefined,
+      ]
+        .filter(Boolean)
+        .join(" | ");
+      const tree = renderTree(result.nodes).join("\n") || "(empty)";
+      return {
+        content: [{ type: "text", text: `${header}\n\n${tree}` }],
+        details: result,
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(`${theme.fg("toolTitle", theme.bold("project_tree "))}${theme.fg("accent", args.root || ".")}`, 0, 0);
+    },
+  });
+
+  pi.registerTool({
+    name: "code_search_batch",
+    label: "Code Search Batch",
+    description: "Run multiple read-only ripgrep searches and return compact line-oriented results.",
+    promptSnippet: "Use code_search_batch when several symbols, routes, keys, or error strings need to be searched together.",
+    promptGuidelines: [
+      "Batch related patterns instead of making many single searches.",
+      "Use globs to constrain language or test files when the task is narrow.",
+      "Ask for file paths, line numbers, and exact matching lines in follow-up analysis.",
+    ],
+    parameters: Type.Object({
+      queries: Type.Array(
+        Type.Object({
+          pattern: Type.String({ description: "ripgrep pattern to search for." }),
+          cwd: Type.Optional(Type.String({ description: "Project-relative directory to search in." })),
+          globs: Type.Optional(Type.Array(Type.String(), { description: "Optional ripgrep -g patterns." })),
+          caseInsensitive: Type.Optional(Type.Boolean({ description: "Use case-insensitive search." })),
+          before: Type.Optional(Type.Number({ description: "Context lines before each match." })),
+          after: Type.Optional(Type.Number({ description: "Context lines after each match." })),
+          maxResults: Type.Optional(Type.Number({ description: "Maximum matches per file from rg -m." })),
+        }),
+      ),
+      maxLinesPerQuery: Type.Optional(Type.Number({ description: "Maximum output lines per query. Default 80." })),
+    }),
+    async execute(_toolCallId, params, _signal, onUpdate, ctx) {
+      const queries = (params.queries || []) as SearchQuery[];
+      if (!queries.length) throw new Error("code_search_batch requires at least one query");
+      if (queries.length > 12) throw new Error("code_search_batch supports at most 12 queries");
+      const maxLinesPerQuery = Math.max(10, Math.min(Number(params.maxLinesPerQuery ?? 80), 300));
+
+      const sections: string[] = [];
+      for (let i = 0; i < queries.length; i++) {
+        const query = queries[i];
+        if (!query.pattern?.trim()) throw new Error(`query ${i + 1} is missing pattern`);
+        onUpdate?.({ content: [{ type: "text", text: `code_search_batch: ${i + 1}/${queries.length} ${query.pattern}` }] });
+        const output = await runRipgrep(ctx.cwd, query);
+        sections.push([
+          `## ${i + 1}. ${query.pattern}`,
+          query.cwd ? `cwd: ${query.cwd}` : undefined,
+          query.globs?.length ? `globs: ${query.globs.join(", ")}` : undefined,
+          "",
+          output ? truncateLines(output, maxLinesPerQuery) : "(no matches)",
+        ].filter((part) => part !== undefined).join("\n"));
+      }
+
+      return {
+        content: [{ type: "text", text: sections.join("\n\n---\n\n") }],
+        details: { queryCount: queries.length },
+      };
+    },
+    renderCall(args, theme) {
+      const count = Array.isArray(args.queries) ? args.queries.length : 0;
+      return new Text(`${theme.fg("toolTitle", theme.bold("code_search_batch "))}${theme.fg("accent", `${count} queries`)}`, 0, 0);
+    },
+  });
+}