@henryqw/pi-add-dir 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 itisbryan
+Modifications Copyright (c) 2026 shelken
+Modifications Copyright (c) 2026 Henry Wang
+
+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,36 @@
+# `@henryqw/pi-add-dir`
+
+Pi extension for adding external directories to current session, based on [shelken's pi-add-dir](https://github.com/shelken/pi-extensions/tree/main/extensions/pi-add-dir). It injects `AGENTS.md` / `CLAUDE.md`, discovers skills, persists directory state in session history, and searches external files.
+
+## Install
+
+```bash
+pi install npm:@henryqw/pi-add-dir
+```
+
+## Use
+
+| Surface | Purpose |
+| --- | --- |
+| `/dir-add [path]` | Add directory; no path opens input. Supports `~`. |
+| `/dir-ls` | List directories; select one to remove. |
+| `add_directory` | Agent tool for adding directory. |
+| `search_external_files` | Agent tool for glob-searching external files. |
+
+Added directories return root `AGENTS.md`, `CLAUDE.md`, `.pi/AGENTS.md`, and `.pi/CLAUDE.md` in `add_directory` results and inject them into future prompts. Skills load from `.pi/skills`, `.agents/skills`, and `.claude/skills`, then register as `/skill:<name>` after reload. `/dir-add` reloads automatically when it finds skills; `add_directory` reports when `/reload` is needed.
+
+Search uses native Node filesystem traversal, skips `.git` and `node_modules`, supports basename and relative-path globs, and caps results at 1,000 per call. No config file or runtime dependency.
+
+## Remove
+
+```bash
+pi remove npm:@henryqw/pi-add-dir
+```
+
+## Development
+
+```bash
+npm test
+npm run typecheck
+npm run pack:check
+```

package/extensions/add-dir-helpers.ts

@@ -0,0 +1,214 @@
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { homedir } 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;
+const SKIPPED_SEARCH_DIRS = new Set([".git", "node_modules"]);
+
+export function expandUserPath(input: string): string {
+	if (input === "~") return homedir();
+	if (input.startsWith("~/") || input.startsWith(`~${path.sep}`)) return path.join(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 realpathSync(resolved);
+	} catch {
+		return path.resolve(resolved);
+	}
+}
+
+export function dirExists(dir: string): boolean {
+	try {
+		return statSync(dir).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+export function readFileSafe(filePath: string): string | null {
+	try {
+		return readFileSync(filePath, "utf8");
+	} catch {
+		return null;
+	}
+}
+
+function readContextFile(dir: string, name: (typeof CONTEXT_FILES)[number]): string | null {
+	const contents = [readFileSafe(path.join(dir, name)), readFileSafe(path.join(dir, ".pi", name))].filter(
+		(content): content is string => content !== null,
+	);
+	return contents.length > 0 ? contents.join("\n\n") : null;
+}
+
+function skillFiles(dir: string): Array<{ name: string; path: string }> {
+	const files: Array<{ name: string; path: string }> = [];
+	const names = new Set<string>();
+
+	for (const skillDir of SKILL_DIRS) {
+		const fullSkillDir = path.join(dir, skillDir);
+		if (!dirExists(fullSkillDir)) continue;
+		try {
+			for (const entry of readdirSync(fullSkillDir, { withFileTypes: true })) {
+				if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+				const skillPath = path.join(fullSkillDir, entry.name, "SKILL.md");
+				try {
+					if (statSync(skillPath).isFile() && !names.has(entry.name)) {
+						names.add(entry.name);
+						files.push({ name: entry.name, path: skillPath });
+					}
+				} catch {
+					// Skill may disappear while resources are being discovered.
+				}
+			}
+		} catch {
+			// Skip unreadable skill directories.
+		}
+	}
+
+	return files;
+}
+
+export function scanDirContext(dir: string): DirContext {
+	const ctx: DirContext = {
+		dir,
+		agentsMd: readContextFile(dir, "AGENTS.md"),
+		claudeMd: readContextFile(dir, "CLAUDE.md"),
+		skillPaths: new Map(),
+		skills: new Map(),
+	};
+
+	for (const skill of skillFiles(dir)) {
+		const content = readFileSafe(skill.path);
+		if (content === null) continue;
+		ctx.skillPaths.set(skill.name, skill.path);
+		ctx.skills.set(skill.name, content);
+	}
+
+	return ctx;
+}
+
+export function collectSkillPaths(dirs: AddedDir[]): string[] {
+	const paths: string[] = [];
+	const names = new Set<string>();
+	for (const dir of dirs) {
+		if (!dirExists(dir.absolutePath)) continue;
+		for (const skill of skillFiles(dir.absolutePath)) {
+			if (names.has(skill.name)) continue;
+			names.add(skill.name);
+			paths.push(skill.path);
+		}
+	}
+	return paths;
+}
+
+function skillDescription(content: string): string {
+	const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+	const value = frontmatter?.match(/^description:\s*(.*?)\s*$/m)?.[1];
+	if (!value || value === ">" || value === "|") return "No description";
+	return value.replace(/^("|')|("|')$/g, "").trim() || "No description";
+}
+
+export function buildContextInjection(dirs: AddedDir[]): string {
+	if (dirs.length === 0) return "";
+
+	const sections = [
+		"\n\n## External Directories (added via pi-add-dir)",
+		`\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`,
+	];
+
+	const registeredSkills = new Set<string>();
+	for (const dir of dirs) {
+		const ctx = scanDirContext(dir.absolutePath);
+		const skills = [...ctx.skills].filter(([name]) => {
+			if (registeredSkills.has(name)) return false;
+			registeredSkills.add(name);
+			return true;
+		});
+		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 (skills.length > 0) {
+			sections.push(`\n#### Skills from ${dir.label} (registered as /skill:name commands):`);
+			for (const [name, content] of skills) {
+				sections.push(
+					`- **${name}**: ${skillDescription(content)} - use \`/skill:${name}\` or read \`${ctx.skillPaths.get(name)}\``,
+				);
+			}
+		}
+	}
+
+	return sections.join("\n");
+}
+
+function normalizePattern(pattern: string): string {
+	let normalized = pattern.trim();
+	if (path.sep === "\\") normalized = normalized.replaceAll("/", "\\");
+	const prefix = `.${path.sep}`;
+	if (normalized.startsWith(prefix)) normalized = normalized.slice(prefix.length);
+	return normalized;
+}
+
+export async function findFiles(
+	root: string,
+	pattern: string,
+	maxResults: number,
+	signal?: AbortSignal,
+): Promise<string[]> {
+	const normalizedPattern = normalizePattern(pattern);
+	if (!normalizedPattern) throw new Error("File pattern must not be blank.");
+
+	const matchPath = normalizedPattern.includes(path.sep);
+	const results: string[] = [];
+	const pending = [root];
+
+	signal?.throwIfAborted();
+	while (pending.length > 0) {
+		signal?.throwIfAborted();
+		const current = pending.pop()!;
+		let entries;
+		try {
+			entries = await readdir(current, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+
+		for (const entry of entries) {
+			signal?.throwIfAborted();
+			const fullPath = path.join(current, entry.name);
+			if (entry.isDirectory()) {
+				if (!SKIPPED_SEARCH_DIRS.has(entry.name)) pending.push(fullPath);
+				continue;
+			}
+			if (!entry.isFile()) continue;
+
+			const candidate = matchPath ? path.relative(root, fullPath) : entry.name;
+			if (!path.matchesGlob(candidate, normalizedPattern)) continue;
+			results.push(fullPath);
+			if (results.length >= maxResults) return results;
+		}
+	}
+
+	return results;
+}

package/extensions/add-dir.ts

@@ -0,0 +1,406 @@
+import { basename, isAbsolute, relative, sep } from "node:path";
+import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+	buildContextInjection,
+	collectSkillPaths,
+	dirExists,
+	findFiles,
+	resolveDir,
+	scanDirContext,
+	type AddedDir,
+	type DirContext,
+} from "./add-dir-helpers.ts";
+
+const STATE_TYPE = "add-dir:state";
+const DEFAULT_MAX_RESULTS = 50;
+const MAX_RESULTS = 1_000;
+
+const AddDirectoryParams = Type.Object({
+	path: Type.String({ description: "Absolute or relative path to the directory to add", minLength: 1 }),
+	reason: Type.Optional(Type.String({ description: "Why this directory is being added (shown to user)" })),
+});
+
+const SearchExternalFilesParams = Type.Object({
+	pattern: Type.String({
+		description: "File name or glob pattern to search for (for example, '*.ts' or 'src/**/*.test.ts')",
+		minLength: 1,
+	}),
+	maxResults: Type.Optional(
+		Type.Integer({
+			description: `Maximum number of results (default: ${DEFAULT_MAX_RESULTS}, maximum: ${MAX_RESULTS})`,
+			minimum: 1,
+			maximum: MAX_RESULTS,
+		}),
+	),
+});
+
+interface AddDirectoryDetails {
+	directory: string;
+	hasAgentsMd: boolean;
+	hasClaudeMd: boolean;
+	skillCount: number;
+	skillNames: string[];
+}
+
+interface SearchDetails {
+	totalFound: number;
+	pattern: string;
+	dirCount: number;
+}
+
+function isAddedDir(value: unknown): value is AddedDir {
+	if (!value || typeof value !== "object") return false;
+	const dir = value as Partial<AddedDir>;
+	return (
+		typeof dir.absolutePath === "string" &&
+		isAbsolute(dir.absolutePath) &&
+		typeof dir.label === "string" &&
+		typeof dir.addedAt === "number" &&
+		Number.isFinite(dir.addedAt)
+	);
+}
+
+function readState(data: unknown): AddedDir[] {
+	if (!data || typeof data !== "object") return [];
+	const dirs = (data as { dirs?: unknown }).dirs;
+	return Array.isArray(dirs) ? dirs.filter(isAddedDir) : [];
+}
+
+function cleanPath(input: string): string {
+	return input.trim();
+}
+
+function isWithinDir(dir: string, candidate: string): boolean {
+	const relativePath = relative(dir, candidate);
+	return relativePath === "" || (!relativePath.startsWith(`..${sep}`) && relativePath !== ".." && !isAbsolute(relativePath));
+}
+
+function maxResults(value: number | undefined): number {
+	const limit = value ?? DEFAULT_MAX_RESULTS;
+	if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_RESULTS) {
+		throw new Error(`maxResults must be an integer from 1 to ${MAX_RESULTS}.`);
+	}
+	return limit;
+}
+
+function contextDetails(dirCtx: DirContext, absolutePath: string): AddDirectoryDetails {
+	return {
+		directory: absolutePath,
+		hasAgentsMd: dirCtx.agentsMd !== null,
+		hasClaudeMd: dirCtx.claudeMd !== null,
+		skillCount: dirCtx.skills.size,
+		skillNames: [...dirCtx.skills.keys()],
+	};
+}
+
+function contextSummary(dirCtx: DirContext): string {
+	const found: string[] = [];
+	if (dirCtx.agentsMd !== null) found.push("AGENTS.md");
+	if (dirCtx.claudeMd !== null) found.push("CLAUDE.md");
+	if (dirCtx.skills.size > 0) found.push(`${dirCtx.skills.size} skill(s)`);
+	return found.length > 0 ? ` Found: ${found.join(", ")}.` : " No context files found.";
+}
+
+export default function addDirExtension(pi: ExtensionAPI): void {
+	let addedDirs: AddedDir[] = [];
+	let currentCwd = "";
+
+	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) => ({
+			dispose() {},
+			invalidate() {},
+			render(width: number): string[] {
+				const renderWidth = Math.max(1, width);
+				const prefix = theme.fg("accent", "📂");
+				const count = theme.fg("muted", ` ${addedDirs.length} external dir${addedDirs.length === 1 ? "" : "s"}`);
+				const separator = theme.fg("dim", " | ");
+				const suffix = theme.fg("dim", "  (/dir-ls to manage)");
+				const labels = addedDirs.map((dir) => theme.fg("text", dir.label)).join(theme.fg("dim", ", "));
+				const fullLine = ` ${prefix}${count}${separator}${labels}${suffix}`;
+
+				if (visibleWidth(fullLine) <= renderWidth) return [fullLine];
+				const withoutLabels = ` ${prefix}${count}${separator}`;
+				const available = renderWidth - visibleWidth(withoutLabels) - visibleWidth(suffix);
+				if (available > 5) return [`${withoutLabels}${truncateToWidth(labels, available, "…")}${suffix}`];
+				return [truncateToWidth(` ${prefix}${count}`, renderWidth, "…")];
+			},
+		}));
+	}
+
+	function reconstructState(ctx: ExtensionContext): void {
+		currentCwd = ctx.cwd;
+		const stateEntry = [...ctx.sessionManager.getBranch()]
+			.reverse()
+			.find((entry) => entry.type === "custom" && entry.customType === STATE_TYPE);
+		addedDirs = stateEntry?.type === "custom" ? readState(stateEntry.data) : [];
+		updateWidget(ctx);
+	}
+
+	function persistState(): void {
+		pi.appendEntry(STATE_TYPE, { dirs: addedDirs.map((dir) => ({ ...dir })) });
+	}
+
+	function addDir(
+		dirPath: string,
+		cwd: string,
+		ctx: ExtensionContext,
+	): { ok: boolean; message: string; hasNewSkills: boolean; absolutePath?: string; context?: DirContext } {
+		const input = cleanPath(dirPath);
+		if (!input) return { ok: false, message: "Directory path must not be blank.", hasNewSkills: false };
+
+		const absolutePath = resolveDir(input, cwd);
+		if (!dirExists(absolutePath)) {
+			return { ok: false, message: `Directory does not exist: ${absolutePath}`, hasNewSkills: false };
+		}
+		if (addedDirs.some((dir) => dir.absolutePath === absolutePath)) {
+			return { ok: false, message: `Already added: ${absolutePath}`, hasNewSkills: false };
+		}
+		if (isWithinDir(resolveDir(cwd, cwd), absolutePath)) {
+			return {
+				ok: false,
+				message: "Directory is already in current working directory scope.",
+				hasNewSkills: false,
+			};
+		}
+
+		const context = scanDirContext(absolutePath);
+		const label = basename(absolutePath) || absolutePath;
+		addedDirs.push({ absolutePath, label, addedAt: Date.now() });
+		persistState();
+		updateWidget(ctx);
+
+		const hasNewSkills = context.skills.size > 0;
+		return {
+			ok: true,
+			message: `Added ${label} (${absolutePath}).${contextSummary(context)}`,
+			hasNewSkills,
+			absolutePath,
+			context,
+		};
+	}
+
+	function removeDir(absolutePath: string, ctx: ExtensionContext): { ok: boolean; message: string } {
+		const index = addedDirs.findIndex((dir) => dir.absolutePath === absolutePath);
+		if (index < 0) return { ok: false, message: `Not found: ${absolutePath}` };
+
+		const [removed] = addedDirs.splice(index, 1);
+		persistState();
+		updateWidget(ctx);
+		return { ok: true, message: `Removed ${removed!.label} (${removed!.absolutePath}). Reloading resources...` };
+	}
+
+	pi.on("resources_discover", (event) => {
+		if (event.cwd !== currentCwd || addedDirs.length === 0) return;
+		const skillPaths = collectSkillPaths(addedDirs);
+		return skillPaths.length > 0 ? { skillPaths } : undefined;
+	});
+
+	pi.on("session_start", async (_event, ctx) => reconstructState(ctx));
+	pi.on("session_tree", async (_event, ctx) => reconstructState(ctx));
+
+	pi.on("before_agent_start", async (event) => {
+		if (addedDirs.length === 0) return;
+		return { systemPrompt: event.systemPrompt + buildContextInjection(addedDirs) };
+	});
+
+	pi.registerCommand("dir-add", {
+		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);
+			const message = result.ok && result.hasNewSkills ? `${result.message} Reloading to register skills...` : result.message;
+			ctx.ui.notify(message, result.ok ? "info" : "error");
+			if (result.ok && result.hasNewSkills) await ctx.reload();
+		},
+	});
+
+	pi.registerCommand("dir-ls", {
+		description: "List external directories and select one to remove",
+		handler: async (_args, ctx) => {
+			if (addedDirs.length === 0) {
+				ctx.ui.notify("No external directories added. Use /dir-add <path> to add one.", "info");
+				return;
+			}
+
+			const choices = addedDirs.map((dir) => `${dir.label} - ${dir.absolutePath}`);
+			const selected = await ctx.ui.select("External directories — select one to remove:", choices);
+			const selectedIndex = selected === undefined ? -1 : choices.indexOf(selected);
+			const absolutePath = selectedIndex >= 0 ? addedDirs[selectedIndex]?.absolutePath : undefined;
+			if (!absolutePath) return;
+
+			const result = removeDir(absolutePath, ctx);
+			ctx.ui.notify(result.message, result.ok ? "info" : "error");
+			if (result.ok) await ctx.reload();
+		},
+	});
+
+	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 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 returned now and injected into future system prompts.",
+			"After adding, you can read/edit/write files in the external directory using absolute paths.",
+		],
+		parameters: AddDirectoryParams,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const inputPath = cleanPath(params.path);
+			const result = addDir(inputPath, ctx.cwd, ctx);
+			if (!result.ok) throw new Error(result.message);
+
+			const absolutePath = result.absolutePath!;
+			const context = result.context!;
+			const response: string[] = [result.message];
+			if (context.agentsMd !== null) {
+				response.push(`\nAGENTS.md instructions from ${absolutePath}:\n${context.agentsMd}`);
+			}
+			if (context.claudeMd !== null) {
+				response.push(`\nCLAUDE.md instructions from ${absolutePath}:\n${context.claudeMd}`);
+			}
+			if (context.skills.size > 0) {
+				response.push(`\nDiscovered skills: ${[...context.skills.keys()].join(", ")}`);
+				response.push("Run /reload to register skills as /skill:name commands.");
+			}
+			response.push(`\nYou can now access files at: ${absolutePath}`);
+
+			return {
+				content: [{ type: "text", text: response.join("\n") }],
+				details: contextDetails(context, absolutePath),
+			};
+		},
+
+		renderCall(args, theme) {
+			let text = theme.fg("toolTitle", theme.bold("add_directory "));
+			text += theme.fg("accent", cleanPath(args.path));
+			if (args.reason) text += theme.fg("dim", ` (${args.reason})`);
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme) {
+			const details = result.details as AddDirectoryDetails | undefined;
+			if (!details) {
+				const content = result.content[0];
+				const text = content?.type === "text" ? content.text : "Done";
+				return new Text(theme.fg("success", `✓ ${text}`), 0, 0);
+			}
+
+			const parts = [theme.fg("success", `✓ Added ${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 > 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.length > 0) {
+				parts.push("\n" + theme.fg("muted", "  Skills: ") + details.skillNames.map((name) => theme.fg("text", name)).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 outside 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 do not know its exact path.",
+			"Supports glob-style patterns like '*.ts', '**/*.test.js', and 'src/**/*.rb'.",
+			"Returns matching file paths with their parent directory labels.",
+		],
+		parameters: SearchExternalFilesParams,
+
+		async execute(_toolCallId, params, signal) {
+			if (addedDirs.length === 0) {
+				throw new Error("No external directories added. Use /dir-add or add_directory first.");
+			}
+
+			const pattern = cleanPath(params.pattern);
+			const limit = maxResults(params.maxResults);
+			const results: Array<{ dir: string; label: string; files: string[] }> = [];
+			let totalFound = 0;
+
+			for (const dir of addedDirs) {
+				signal?.throwIfAborted();
+				if (!dirExists(dir.absolutePath)) continue;
+				const remaining = limit - totalFound;
+				if (remaining <= 0) break;
+
+				const files = await findFiles(dir.absolutePath, pattern, remaining, signal);
+				if (files.length > 0) {
+					results.push({ dir: dir.absolutePath, label: dir.label, files });
+					totalFound += files.length;
+				}
+			}
+
+			signal?.throwIfAborted();
+			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, dirCount: 0 } satisfies SearchDetails,
+				};
+			}
+
+			const lines = [`Found ${totalFound} file(s) matching "${pattern}":\n`];
+			for (const result of results) {
+				lines.push(`📂 ${result.label} (${result.dir}):`);
+				for (const file of result.files) lines.push(`  ${file}`);
+				lines.push("");
+			}
+
+			return {
+				content: [{ type: "text", text: lines.join("\n") }],
+				details: { totalFound, pattern, dirCount: results.length } satisfies SearchDetails,
+			};
+		},
+
+		renderCall(args, theme) {
+			let text = theme.fg("toolTitle", theme.bold("search_external_files "));
+			text += theme.fg("accent", `"${cleanPath(args.pattern)}"`);
+			text += theme.fg("dim", ` across ${addedDirs.length} dir(s)`);
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme) {
+			const details = result.details as SearchDetails | undefined;
+			if (!details || details.totalFound === 0) {
+				const content = result.content[0];
+				const text = content?.type === "text" ? 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?.type === "text") text += `\n${theme.fg("muted", content.text)}`;
+			}
+			return new Text(text, 0, 0);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@henryqw/pi-add-dir",
+  "version": "0.1.0",
+  "description": "Add external directories to a Pi session with context, skills, and file search.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "external-directory",
+    "context",
+    "skills"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/*.ts test/*.test.ts",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.1",
+    "@earendil-works/pi-tui": ">=0.84.1",
+    "typebox": "*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HenryQW/pi-packages.git",
+    "directory": "packages/pi-add-dir"
+  },
+  "bugs": {
+    "url": "https://github.com/HenryQW/pi-packages/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/add-dir.ts"
+    ]
+  }
+}