@shelken/pi-add-dir 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 itisbryan
+
+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,39 @@
+# pi-add-dir
+
+将会话外目录加入当前 pi session：加载 `AGENTS.md` / `CLAUDE.md`、发现 skills，并跨重启持久化。
+
+初始 fork 自 [itisbryan/pi-add-dir](https://github.com/itisbryan/pi-add-dir)；本仓库已大幅简化（去掉 smart suggestions / monorepo 推荐 / 扩展探测等）。
+
+## 能力
+
+| 类型 | 名称 | 说明 |
+|---|---|---|
+| 命令 | `/add-dir [path]` | 添加目录；无参时交互输入路径 |
+| 命令 | `/remove-dir [path\|label]` | 移除目录 |
+| 命令 | `/dirs` | 列出已添加目录 |
+| 工具 | `add_directory` | 让 agent 请求添加目录 |
+| 工具 | `search_external_files` | 在外部目录中按文件名/glob 搜索 |
+
+Skills 通过 `resources_discover` 注册为 `/skill:name`。
+
+## 安装
+
+从 npm 安装：
+
+```bash
+pi install npm:@shelken/pi-add-dir
+```
+
+本 monorepo 根 `package.json` 的 `pi.extensions` 也已包含入口。本地使用时可直接引用整个仓库：
+
+```json
+{
+  "packages": ["/path/to/pi-extensions"]
+}
+```
+
+## 验证
+
+```bash
+bun --filter pi-add-dir test
+```

package/helpers.ts

@@ -0,0 +1,206 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export interface AddedDir {
+  absolutePath: string;
+  label: string;
+  addedAt: number;
+}
+
+export interface DirContext {
+  dir: string;
+  agentsMd: string | null;
+  claudeMd: string | null;
+  skillPaths: Map<string, string>;
+  skills: Map<string, string>;
+}
+
+const CONTEXT_FILES = ["AGENTS.md", "CLAUDE.md"] as const;
+
+const SKILL_DIRS = [".pi/skills", ".agents/skills", ".claude/skills"] as const;
+
+export function expandUserPath(input: string): string {
+  if (input === "~") return os.homedir();
+  if (input.startsWith("~/")) return path.join(os.homedir(), input.slice(2));
+  return input;
+}
+
+export function resolveDir(input: string, cwd: string): string {
+  const expanded = expandUserPath(input);
+  const resolved = path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded);
+  try {
+    return fs.realpathSync(resolved);
+  } catch {
+    return path.resolve(resolved);
+  }
+}
+
+export function dirExists(dir: string): boolean {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function readFileSafe(filePath: string): string | null {
+  try {
+    return fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+export function cwdHash(cwd: string): string {
+  return crypto.createHash("sha256").update(cwd).digest("hex").slice(0, 12);
+}
+
+export function getTempStatePath(cwd: string): string {
+  return path.join(os.tmpdir(), `pi-add-dir-${cwdHash(cwd)}.json`);
+}
+
+export function writeTempState(cwd: string, dirs: AddedDir[]): void {
+  try {
+    fs.writeFileSync(getTempStatePath(cwd), JSON.stringify({ dirs }), "utf-8");
+  } catch {
+    // temp state is only a bridge for resources_discover
+  }
+}
+
+export function readTempState(cwd: string): AddedDir[] {
+  try {
+    const content = fs.readFileSync(getTempStatePath(cwd), "utf-8");
+    const data = JSON.parse(content) as { dirs?: AddedDir[] };
+    return data.dirs ?? [];
+  } catch {
+    return [];
+  }
+}
+
+export function removeTempState(cwd: string): void {
+  try {
+    fs.unlinkSync(getTempStatePath(cwd));
+  } catch {
+    // already gone
+  }
+}
+
+export function scanDirContext(dir: string): DirContext {
+  const ctx: DirContext = {
+    dir,
+    agentsMd: null,
+    claudeMd: null,
+    skillPaths: new Map(),
+    skills: new Map(),
+  };
+
+  for (const name of CONTEXT_FILES) {
+    const content = readFileSafe(path.join(dir, name));
+    if (name === "AGENTS.md") ctx.agentsMd = content;
+    if (name === "CLAUDE.md") ctx.claudeMd = content;
+  }
+
+  for (const name of CONTEXT_FILES) {
+    const piContent = readFileSafe(path.join(dir, ".pi", name));
+    if (!piContent) continue;
+    if (name === "AGENTS.md") ctx.agentsMd = (ctx.agentsMd ?? "") + "\n\n" + piContent;
+    if (name === "CLAUDE.md") ctx.claudeMd = (ctx.claudeMd ?? "") + "\n\n" + piContent;
+  }
+
+  for (const skillDir of SKILL_DIRS) {
+    const fullSkillDir = path.join(dir, skillDir);
+    if (!dirExists(fullSkillDir)) continue;
+    try {
+      for (const entry of fs.readdirSync(fullSkillDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const skillMdPath = path.join(fullSkillDir, entry.name, "SKILL.md");
+        const skillMd = readFileSafe(skillMdPath);
+        if (skillMd) {
+          ctx.skillPaths.set(entry.name, skillMdPath);
+          ctx.skills.set(entry.name, skillMd);
+        }
+      }
+    } catch {
+      // skip unreadable skill dirs
+    }
+  }
+
+  return ctx;
+}
+
+export function collectSkillPaths(dirs: AddedDir[]): string[] {
+  const skillPaths: string[] = [];
+  for (const dir of dirs) {
+    if (!dirExists(dir.absolutePath)) continue;
+    for (const skillDir of SKILL_DIRS) {
+      const fullSkillDir = path.join(dir.absolutePath, skillDir);
+      if (!dirExists(fullSkillDir)) continue;
+      try {
+        for (const entry of fs.readdirSync(fullSkillDir, { withFileTypes: true })) {
+          if (!entry.isDirectory()) continue;
+          const skillMdPath = path.join(fullSkillDir, entry.name, "SKILL.md");
+          if (readFileSafe(skillMdPath) !== null) {
+            skillPaths.push(skillMdPath);
+          }
+        }
+      } catch {
+        // skip unreadable skill dirs
+      }
+    }
+  }
+  return skillPaths;
+}
+
+let contextCache: { dirs: string; injection: string } | null = null;
+
+export function invalidateContextCache(): void {
+  contextCache = null;
+}
+
+export function buildContextInjection(dirs: AddedDir[]): string {
+  if (dirs.length === 0) return "";
+
+  const cacheKey = dirs
+    .map((d) => d.absolutePath)
+    .sort()
+    .join("\0");
+  if (contextCache && contextCache.dirs === cacheKey) {
+    return contextCache.injection;
+  }
+
+  const sections: string[] = [];
+  sections.push("\n\n## External Directories (added via pi-add-dir)");
+  sections.push(
+    `\nThe following ${dirs.length} external director${dirs.length === 1 ? "y is" : "ies are"} included in this session. You can read, edit, and write files in these directories using absolute paths.\n`,
+  );
+
+  for (const dir of dirs) {
+    const ctx = scanDirContext(dir.absolutePath);
+    sections.push(`### ${dir.label} - \`${dir.absolutePath}\``);
+
+    if (ctx.agentsMd) {
+      sections.push(`\n#### AGENTS.md (from ${dir.label})\n${ctx.agentsMd}`);
+    }
+    if (ctx.claudeMd) {
+      sections.push(`\n#### CLAUDE.md (from ${dir.label})\n${ctx.claudeMd}`);
+    }
+
+    if (ctx.skills.size > 0) {
+      sections.push(`\n#### Skills from ${dir.label} (registered as /skill:name commands):`);
+      for (const [name, content] of ctx.skills) {
+        const descMatch = content.match(/^---\n[\s\S]*?description:\s*>?\s*\n?\s*(.*?)(?:\n---|\n\w)/m);
+        const desc = descMatch?.[1]?.trim() ?? "No description";
+        sections.push(
+          `- **${name}**: ${desc} - use \`/skill:${name}\` or read \`${ctx.skillPaths.get(name)}\``,
+        );
+      }
+    }
+    // 顶层目录列表会随文件创建/删除变化，放入 system prompt 会破坏 prompt cache。
+  }
+
+  const injection = sections.join("\n");
+  contextCache = { dirs: cacheKey, injection };
+  return injection;
+}

package/index.ts

@@ -0,0 +1,485 @@
+/**
+ * pi-add-dir - 将会话外目录加入当前 pi session。
+ *
+ * 加载 AGENTS.md / CLAUDE.md，发现 skills，注入 system prompt，并跨重启持久化。
+ * 外部 skills 通过 resources_discover 注册为 /skill:name。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import * as childProcess from "node:child_process";
+import * as path from "node:path";
+import {
+  type AddedDir,
+  buildContextInjection,
+  collectSkillPaths,
+  dirExists,
+  invalidateContextCache,
+  readTempState,
+  removeTempState,
+  resolveDir,
+  scanDirContext,
+  writeTempState,
+} from "./helpers.ts";
+
+export default function addDirExtension(pi: ExtensionAPI): void {
+  let addedDirs: AddedDir[] = [];
+  let currentCwd = "";
+
+  pi.on("resources_discover", (event, _ctx) => {
+    const dirs = readTempState(event.cwd);
+    if (dirs.length === 0) return;
+    const skillPaths = collectSkillPaths(dirs);
+    if (skillPaths.length === 0) return;
+    return { skillPaths };
+  });
+
+  function reconstructState(ctx: ExtensionContext): void {
+    addedDirs = [];
+    currentCwd = ctx.cwd;
+
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type !== "custom") continue;
+      if (entry.customType === "add-dir:state") {
+        addedDirs = (entry.data as { dirs: AddedDir[] })?.dirs ?? [];
+      }
+    }
+
+    invalidateContextCache();
+    writeTempState(currentCwd, addedDirs);
+    updateWidget(ctx);
+  }
+
+  function persistState(cwd?: string): void {
+    pi.appendEntry("add-dir:state", { dirs: addedDirs });
+    const effectiveCwd = cwd || currentCwd;
+    if (effectiveCwd) {
+      writeTempState(effectiveCwd, addedDirs);
+    }
+  }
+
+  function updateWidget(ctx: ExtensionContext): void {
+    if (!ctx.hasUI) return;
+
+    if (addedDirs.length === 0) {
+      ctx.ui.setWidget("add-dir", undefined);
+      return;
+    }
+
+    ctx.ui.setWidget("add-dir", (_tui, theme) => {
+      return {
+        dispose() {},
+        invalidate() {},
+        render(width: number): string[] {
+          const prefix = theme.fg("accent", "📂");
+          const count = theme.fg(
+            "muted",
+            ` ${addedDirs.length} external dir${addedDirs.length === 1 ? "" : "s"}`,
+          );
+          const sep = theme.fg("dim", " | ");
+          const suffix = theme.fg("dim", "  (/dirs to manage)");
+          const dirLabels = addedDirs.map((d) => theme.fg("text", d.label)).join(theme.fg("dim", ", "));
+          const fullLine = ` ${prefix}${count}${sep}${dirLabels}${suffix}`;
+
+          if (visibleWidth(fullLine) <= width) {
+            return [fullLine];
+          }
+
+          const withoutLabels = ` ${prefix}${count}${sep}`;
+          const available = width - visibleWidth(withoutLabels) - visibleWidth(suffix);
+          if (available > 5) {
+            return [`${withoutLabels}${truncateToWidth(dirLabels, available, "…")}${suffix}`];
+          }
+          return [truncateToWidth(` ${prefix}${count}`, width, "…")];
+        },
+      };
+    });
+  }
+
+  function addDir(
+    dirPath: string,
+    cwd: string,
+    ctx: ExtensionContext,
+  ): { ok: boolean; message: string; hasNewSkills: boolean } {
+    const absolutePath = resolveDir(dirPath, cwd);
+
+    if (!dirExists(absolutePath)) {
+      return { ok: false, message: `Directory does not exist: ${absolutePath}`, hasNewSkills: false };
+    }
+    if (addedDirs.some((d) => d.absolutePath === absolutePath)) {
+      return { ok: false, message: `Already added: ${absolutePath}`, hasNewSkills: false };
+    }
+    if (absolutePath === resolveDir(cwd, cwd)) {
+      return {
+        ok: false,
+        message: "That's the current working directory - already in scope.",
+        hasNewSkills: false,
+      };
+    }
+
+    const label = path.basename(absolutePath);
+    addedDirs.push({ absolutePath, label, addedAt: Date.now() });
+    invalidateContextCache();
+    persistState(cwd);
+    updateWidget(ctx);
+
+    const dirCtx = scanDirContext(absolutePath);
+    const found: string[] = [];
+    if (dirCtx.agentsMd) found.push("AGENTS.md");
+    if (dirCtx.claudeMd) found.push("CLAUDE.md");
+    if (dirCtx.skills.size > 0) found.push(`${dirCtx.skills.size} skill(s)`);
+
+    const hasNewSkills = dirCtx.skills.size > 0;
+    const foundStr = found.length > 0 ? ` Found: ${found.join(", ")}.` : " No context files found.";
+    let message = `Added ${label} (${absolutePath}).${foundStr}`;
+    if (hasNewSkills) {
+      message += " Reloading to register skills as /skill:name commands...";
+    }
+    return { ok: true, message, hasNewSkills };
+  }
+
+  function removeDir(
+    absolutePath: string,
+    ctx: ExtensionContext,
+  ): { ok: boolean; message: string; hadSkills: boolean } {
+    const idx = addedDirs.findIndex((d) => d.absolutePath === absolutePath);
+    if (idx === -1) {
+      return { ok: false, message: `Not found: ${absolutePath}`, hadSkills: false };
+    }
+
+    const hadSkills = scanDirContext(absolutePath).skills.size > 0;
+    const removed = addedDirs.splice(idx, 1)[0];
+    invalidateContextCache();
+    persistState();
+    updateWidget(ctx);
+
+    let message = `Removed ${removed.label} (${removed.absolutePath}).`;
+    if (hadSkills) {
+      message += " Reloading to unregister skills...";
+    }
+    return { ok: true, message, hadSkills };
+  }
+
+  pi.on("session_start", async (_e, ctx) => reconstructState(ctx));
+  pi.on("session_tree", async (_e, ctx) => reconstructState(ctx));
+  pi.on("session_shutdown", async () => {
+    if (currentCwd) removeTempState(currentCwd);
+  });
+
+  pi.on("before_agent_start", async (event, _ctx) => {
+    if (addedDirs.length === 0) return;
+    return {
+      systemPrompt: event.systemPrompt + buildContextInjection(addedDirs),
+    };
+  });
+
+  pi.registerCommand("add-dir", {
+    description: "Add an external directory to this session",
+    handler: async (args, ctx) => {
+      let inputPath = args?.trim();
+      if (!inputPath) {
+        const prompted = await ctx.ui.input("Directory path:", "");
+        if (!prompted) return;
+        inputPath = prompted;
+      }
+
+      const result = addDir(inputPath, ctx.cwd, ctx);
+      ctx.ui.notify(result.message, result.ok ? "info" : "error");
+      if (result.ok && result.hasNewSkills) {
+        await ctx.reload();
+      }
+    },
+  });
+
+  pi.registerCommand("remove-dir", {
+    description: "Remove an external directory from this session",
+    getArgumentCompletions(prefix: string) {
+      if (addedDirs.length === 0) return null;
+      const lower = prefix.toLowerCase();
+      return addedDirs
+        .filter(
+          (d) =>
+            d.label.toLowerCase().startsWith(lower) || d.absolutePath.toLowerCase().startsWith(lower),
+        )
+        .map((d) => ({ label: d.label, value: d.absolutePath, description: d.absolutePath }));
+    },
+    handler: async (args, ctx) => {
+      if (addedDirs.length === 0) {
+        ctx.ui.notify("No external directories added.", "info");
+        return;
+      }
+
+      let absolutePath: string | undefined;
+      if (args?.trim()) {
+        const input = args.trim();
+        const byLabel = addedDirs.find((d) => d.label === input);
+        absolutePath = byLabel ? byLabel.absolutePath : resolveDir(input, ctx.cwd);
+      } else {
+        const choices = addedDirs.map((d) => `${d.label} - ${d.absolutePath}`);
+        const selected = await ctx.ui.select("Remove which directory?", choices);
+        if (selected === undefined) return;
+        const selectedIdx = choices.indexOf(selected);
+        absolutePath = selectedIdx >= 0 ? addedDirs[selectedIdx]?.absolutePath : undefined;
+      }
+
+      if (!absolutePath) return;
+      const result = removeDir(absolutePath, ctx);
+      ctx.ui.notify(result.message, result.ok ? "info" : "error");
+      if (result.ok && result.hadSkills) {
+        await ctx.reload();
+      }
+    },
+  });
+
+  pi.registerCommand("dirs", {
+    description: "List all external directories in this session",
+    handler: async (_args, ctx) => {
+      if (addedDirs.length === 0) {
+        ctx.ui.notify("No external directories added. Use /add-dir <path> to add one.", "info");
+        return;
+      }
+
+      const lines: string[] = [`External directories (${addedDirs.length}):\n`];
+      for (const dir of addedDirs) {
+        const dirCtx = scanDirContext(dir.absolutePath);
+        const badges: string[] = [];
+        if (dirCtx.agentsMd) badges.push("AGENTS.md");
+        if (dirCtx.claudeMd) badges.push("CLAUDE.md");
+        if (dirCtx.skills.size > 0) badges.push(`${dirCtx.skills.size} skill(s)`);
+
+        lines.push(`  📂 ${dir.label}`);
+        lines.push(`     ${dir.absolutePath}`);
+        if (badges.length > 0) lines.push(`     Found: ${badges.join(", ")}`);
+        if (dirCtx.skills.size > 0) {
+          lines.push(`     Skills: ${[...dirCtx.skills.keys()].map((s) => `/skill:${s}`).join(", ")}`);
+        }
+        lines.push("");
+      }
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
+
+  pi.registerTool({
+    name: "add_directory",
+    label: "Add Directory",
+    description:
+      "Add an external directory to this session so its AGENTS.md, CLAUDE.md, and skills are loaded into context. " +
+      "Use this when you need to reference or work with code in a directory outside the current working directory.",
+    promptSnippet: "Add an external directory to this session (loads its AGENTS.md, skills, etc.)",
+    promptGuidelines: [
+      "Use add_directory when you need context from another project or directory outside cwd.",
+      "The directory's AGENTS.md and CLAUDE.md are injected into the system prompt automatically.",
+      "After adding, you can read/edit/write files in that directory using absolute paths.",
+    ],
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Absolute or relative path to the directory to add",
+      }),
+      reason: Type.Optional(
+        Type.String({
+          description: "Why this directory is being added (shown to user)",
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const dirPath = params.path.replace(/^@/, "");
+      const result = addDir(dirPath, ctx.cwd, ctx);
+      if (!result.ok) throw new Error(result.message);
+
+      const absolutePath = resolveDir(dirPath, ctx.cwd);
+      const dirCtx = scanDirContext(absolutePath);
+      const response: string[] = [result.message];
+      if (dirCtx.agentsMd) response.push("\nAGENTS.md content has been injected into system context.");
+      if (dirCtx.claudeMd) response.push("CLAUDE.md content has been injected into system context.");
+      if (dirCtx.skills.size > 0) {
+        response.push(`\nDiscovered skills: ${[...dirCtx.skills.keys()].join(", ")}`);
+        response.push("Skills will be registered as /skill:name commands after reload.");
+      }
+      response.push(`\nYou can now access files at: ${absolutePath}`);
+
+      return {
+        content: [{ type: "text", text: response.join("\n") }],
+        details: {
+          directory: absolutePath,
+          hasAgentsMd: !!dirCtx.agentsMd,
+          hasClaudeMd: !!dirCtx.claudeMd,
+          skillCount: dirCtx.skills.size,
+          skillNames: [...dirCtx.skills.keys()],
+        },
+      };
+    },
+
+    renderCall(args, theme, _context) {
+      const dirPath = args.path?.replace(/^@/, "") ?? "";
+      let text = theme.fg("toolTitle", theme.bold("add_directory "));
+      text += theme.fg("accent", dirPath);
+      if (args.reason) text += theme.fg("dim", ` (${args.reason})`);
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme, _context) {
+      const details = result.details as
+        | {
+            directory?: string;
+            hasAgentsMd?: boolean;
+            hasClaudeMd?: boolean;
+            skillCount?: number;
+            skillNames?: string[];
+          }
+        | undefined;
+
+      if (!details) {
+        const content = result.content?.[0];
+        const text = content && "text" in content ? content.text : "Done";
+        return new Text(theme.fg("success", `✓ ${text}`), 0, 0);
+      }
+
+      const parts: string[] = [];
+      parts.push(theme.fg("success", `✓ Added ${path.basename(details.directory ?? "")}`));
+
+      const badges: string[] = [];
+      if (details.hasAgentsMd) badges.push(theme.fg("accent", "AGENTS.md"));
+      if (details.hasClaudeMd) badges.push(theme.fg("accent", "CLAUDE.md"));
+      if (details.skillCount && details.skillCount > 0) {
+        badges.push(theme.fg("warning", `${details.skillCount} skills`));
+      }
+      if (badges.length > 0) {
+        parts.push(theme.fg("dim", " | ") + badges.join(theme.fg("dim", ", ")));
+      }
+      if (expanded && details.skillNames && details.skillNames.length > 0) {
+        parts.push(
+          "\n" +
+            theme.fg("muted", "  Skills: ") +
+            details.skillNames.map((s) => theme.fg("text", s)).join(", "),
+        );
+      }
+      return new Text(parts.join(""), 0, 0);
+    },
+  });
+
+  pi.registerTool({
+    name: "search_external_files",
+    label: "Search External Files",
+    description:
+      "Search for files across all external directories added to this session. " +
+      "Use this when you need to find files in external directories, since the @ file picker " +
+      "only searches the current working directory.",
+    promptSnippet: "Search for files across all added external directories by name pattern",
+    promptGuidelines: [
+      "Use search_external_files when you need to find a file in an external directory but don't know its exact path.",
+      "Supports glob-style patterns like '*.ts', '**/*.test.js', 'src/**/*.rb'.",
+      "Returns matching file paths with their parent directory labels.",
+    ],
+    parameters: Type.Object({
+      pattern: Type.String({
+        description: "File name or glob pattern to search for (e.g., '*.ts', 'config/**', 'README.md')",
+      }),
+      maxResults: Type.Optional(
+        Type.Number({
+          description: "Maximum number of results to return (default: 50)",
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+      if (addedDirs.length === 0) {
+        throw new Error("No external directories added. Use /add-dir or add_directory first.");
+      }
+
+      const maxResults = params.maxResults ?? 50;
+      const pattern = params.pattern.replace(/^@/, "");
+      const results: { dir: string; label: string; files: string[] }[] = [];
+      let totalFound = 0;
+
+      for (const dir of addedDirs) {
+        if (signal?.aborted) break;
+        if (!dirExists(dir.absolutePath)) continue;
+
+        const remaining = maxResults - totalFound;
+        if (remaining <= 0) break;
+
+        const hasSlash = pattern.includes("/");
+        const findFlag = hasSlash ? "-path" : "-name";
+        const findArgs = [
+          dir.absolutePath,
+          "-not",
+          "-path",
+          "*/node_modules/*",
+          "-not",
+          "-path",
+          "*/.git/*",
+          findFlag,
+          pattern,
+          "-type",
+          "f",
+        ];
+        const result = childProcess.spawnSync("find", findArgs, {
+          encoding: "utf-8",
+          timeout: 10_000,
+        });
+        const output = (result.stdout ?? "").trim();
+        const files = (output ? output.split("\n").filter(Boolean) : []).slice(0, remaining);
+        if (files.length > 0) {
+          results.push({ dir: dir.absolutePath, label: dir.label, files });
+          totalFound += files.length;
+        }
+      }
+
+      if (totalFound === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No files matching "${pattern}" found in ${addedDirs.length} external director${addedDirs.length === 1 ? "y" : "ies"}.`,
+            },
+          ],
+          details: { totalFound: 0, pattern },
+        };
+      }
+
+      const lines: string[] = [`Found ${totalFound} file(s) matching "${pattern}":\n`];
+      for (const r of results) {
+        lines.push(`📂 ${r.label} (${r.dir}):`);
+        for (const f of r.files) lines.push(`  ${f}`);
+        lines.push("");
+      }
+
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: { totalFound, pattern, dirCount: results.length },
+      };
+    },
+
+    renderCall(args, theme, _context) {
+      const pattern = args.pattern?.replace(/^@/, "") ?? "";
+      let text = theme.fg("toolTitle", theme.bold("search_external_files "));
+      text += theme.fg("accent", `"${pattern}"`);
+      text += theme.fg("dim", ` across ${addedDirs.length} dir(s)`);
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme, _context) {
+      const details = result.details as
+        | { totalFound?: number; pattern?: string; dirCount?: number }
+        | undefined;
+
+      if (!details || !details.totalFound) {
+        const content = result.content?.[0];
+        const text = content && "text" in content ? content.text : "No results";
+        return new Text(theme.fg("muted", text), 0, 0);
+      }
+
+      let text = theme.fg("success", `✓ ${details.totalFound} file(s)`);
+      text += theme.fg("dim", ` matching "${details.pattern}" in ${details.dirCount} dir(s)`);
+      if (expanded) {
+        const content = result.content?.[0];
+        if (content && "text" in content) {
+          text += "\n" + theme.fg("muted", content.text);
+        }
+      }
+      return new Text(text, 0, 0);
+    },
+  });
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@shelken/pi-add-dir",
+  "version": "1.4.0",
+  "description": "Add external directories to a pi session - loads AGENTS.md, CLAUDE.md, and skills into context.",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "helpers.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shelken/pi-extensions.git",
+    "directory": "extensions/pi-add-dir"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "external-directory",
+    "context"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  }
+}