pi-md-tree 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Bianchi
+
+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,122 @@
+# pi-md-tree
+
+Save assistant responses as Markdown, then browse, search, open, load, or preview them from a keyboard-driven tree inside [Pi](https://pi.dev).
+
+`pi-md-tree` keeps temporary notes out of your working tree by default while making project documentation and saved notes available from one picker.
+
+## Features
+
+- Save the latest assistant response without thinking or tool-call content.
+- Keep default saves under the repository's private `.git` metadata.
+- Browse configured notes, hidden saves, and repository documentation together.
+- Find Markdown with an incremental, case-insensitive path search.
+- Load a document into Pi's editor as context.
+- Open a document in its system application or editor.
+- Preview through [`pi-markdown-preview`](https://github.com/omaclaren/pi-markdown-preview) in the browser or inline in a supported terminal.
+- Navigate with arrows or Vim-style keys.
+
+## Install
+
+```bash
+pi install npm:pi-md-tree
+```
+
+Reload an existing Pi session after installation:
+
+```text
+/reload
+```
+
+### Preview prerequisites
+
+Previewing requires [Pandoc](https://pandoc.org/installing.html):
+
+```bash
+brew install pandoc
+```
+
+Inline terminal previews also require a Chromium-based browser and an image-capable terminal such as Ghostty, Kitty, iTerm2, or WezTerm. Browser preview works without terminal image support.
+
+## Commands
+
+### Save a response
+
+```text
+/save-md <name> [directory]
+```
+
+The `.md` suffix is optional. Existing files are never overwritten.
+
+Inside a Git repository, the default destination is:
+
+```text
+.git/pi-save-md/<session-working-directory>/
+```
+
+The path is scoped to Pi's working directory within the repository. Outside Git, the fallback is `saved-md/` beneath the current directory.
+
+Examples:
+
+```text
+/save-md query-plan
+/save-md design ./notes
+/save-md design "~/Documents/project notes"
+```
+
+### Browse documents
+
+```text
+/md [directory]
+/md-tree [directory]
+```
+
+`/md-tree` is an alias for `/md`. The picker combines these sources when they contain matching files:
+
+1. A directory passed to `/md`, or the configured `PI_SAVE_MD_DIR`.
+2. The hidden `.git/pi-save-md/<session-working-directory>/` directory, even when another save directory is configured.
+3. Tracked and unignored, untracked `.md` and `.AGENTS` files from the current Git repository, including `AGENTS.md`.
+
+## Picker keys
+
+| Key | Action |
+| --- | --- |
+| `j` / `k`, `↓` / `↑` | Move down or up |
+| `Ctrl+D` / `Ctrl+U` | Move down or up half a page |
+| `h` / `l` | Collapse or expand a directory |
+| `Enter` | Toggle a directory or load a file into Pi's editor |
+| `/` | Enter or edit path search |
+| `Enter` while searching | Apply the current filter |
+| `Esc` while searching | Clear the filter |
+| `o` or `e` | Open the selected file |
+| `p`, then `b` | Preview the selected file in a browser |
+| `p`, then `t` | Preview the selected file inline in the terminal |
+| `Esc` | Cancel the current action or close the picker |
+
+Search is case-insensitive and matches both labels and full paths. Matching files retain their parent directories in the filtered tree.
+
+## Configuration
+
+Set `PI_SAVE_MD_DIR` before starting Pi to choose the default save directory:
+
+```bash
+export PI_SAVE_MD_DIR="$HOME/Documents/pi-notes"
+```
+
+A directory supplied directly to `/save-md` or `/md` overrides this value for that command. The hidden repository save location remains visible in `/md` either way.
+
+## Opening files
+
+On macOS, `o` uses `open`; on Linux, it uses `xdg-open`.
+
+When `HERDR_ENV=1`, `o` opens a focused sibling Herdr pane and starts `$VISUAL`, `$EDITOR`, or `nvim` with the selected file.
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+## License
+
+[MIT](LICENSE)

package/index.ts

@@ -0,0 +1,605 @@
+import { mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { basename, dirname, join, relative, resolve } from "node:path";
+
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	closeSharedPreviewBrowser,
+	openPreview,
+	openPreviewInBrowser,
+} from "pi-markdown-preview";
+
+interface MarkdownNode {
+	kind: "directory" | "file";
+	depth: number;
+	key: string;
+	label: string;
+	parentKey?: string;
+	path: string;
+}
+
+interface MarkdownSource {
+	files: string[];
+	id: string;
+	label: string;
+	root: string;
+}
+
+interface PickerResult {
+	action: "load" | "open" | "preview-browser" | "preview-terminal";
+	path: string;
+}
+
+function textContent(content: unknown): string {
+	if (!Array.isArray(content)) return "";
+
+	return content
+		.filter(
+			(block): block is { type: "text"; text: string } =>
+				typeof block === "object" &&
+				block !== null &&
+				"type" in block &&
+				block.type === "text" &&
+				"text" in block &&
+				typeof block.text === "string",
+		)
+		.map((block) => block.text)
+		.join("\n\n");
+}
+
+// Command arguments are shell-like so paths containing spaces can be quoted.
+export function parseArguments(input: string): string[] {
+	const values: string[] = [];
+	let value = "";
+	let quote: "'" | '"' | undefined;
+	let escaping = false;
+
+	for (const character of input.trim()) {
+		if (escaping) {
+			value += character;
+			escaping = false;
+		} else if (character === "\\" && quote !== "'") {
+			escaping = true;
+		} else if (quote) {
+			if (character === quote) quote = undefined;
+			else value += character;
+		} else if (character === "'" || character === '"') {
+			quote = character;
+		} else if (/\s/.test(character)) {
+			if (value) {
+				values.push(value);
+				value = "";
+			}
+		} else {
+			value += character;
+		}
+	}
+	if (escaping) value += "\\";
+	if (quote) throw new Error("Unclosed quote in command arguments");
+	if (value) values.push(value);
+	return values;
+}
+
+async function defaultMarkdownDirectory(pi: ExtensionAPI, cwd: string): Promise<string> {
+	const repository = await pi.exec("git", [
+		"-C",
+		cwd,
+		"rev-parse",
+		"--show-toplevel",
+		"--absolute-git-dir",
+	]);
+	if (repository.code !== 0) {
+		return join(cwd, "saved-md");
+	}
+
+	const [repositoryRoot, gitDirectory] = repository.stdout.trim().split("\n");
+	if (!repositoryRoot || !gitDirectory) {
+		throw new Error("Could not locate the Git repository metadata");
+	}
+	const canonicalCwd = await realpath(cwd);
+	return join(gitDirectory, "pi-save-md", relative(repositoryRoot, canonicalCwd));
+}
+
+function shellQuote(value: string): string {
+	return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+function expandDirectory(path: string, cwd: string): string {
+	if (path === "~") return homedir();
+	if (path.startsWith("~/")) return resolve(homedir(), path.slice(2));
+	return resolve(cwd, path);
+}
+
+async function markdownDirectory(
+	pi: ExtensionAPI,
+	cwd: string,
+	directory?: string,
+): Promise<string> {
+	const configuredDirectory = directory ?? process.env.PI_SAVE_MD_DIR;
+	return configuredDirectory
+		? expandDirectory(configuredDirectory, cwd)
+		: defaultMarkdownDirectory(pi, cwd);
+}
+
+function isMarkdownOrAgentsFile(path: string): boolean {
+	const name = basename(path).toLowerCase();
+	return name.endsWith(".md") || name === ".agents";
+}
+
+async function collectMarkdownFiles(root: string): Promise<string[]> {
+	const files: string[] = [];
+
+	async function visit(directory: string): Promise<void> {
+		for (const entry of await readdir(directory, { withFileTypes: true })) {
+			const path = join(directory, entry.name);
+			if (entry.isDirectory()) await visit(path);
+			else if (entry.isFile() && isMarkdownOrAgentsFile(path)) files.push(path);
+		}
+	}
+
+	try {
+		await visit(root);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	return files;
+}
+
+async function repositoryMarkdownSource(
+	pi: ExtensionAPI,
+	cwd: string,
+): Promise<MarkdownSource | undefined> {
+	const repository = await pi.exec("git", ["-C", cwd, "rev-parse", "--show-toplevel"]);
+	if (repository.code !== 0) return undefined;
+	const root = repository.stdout.trim();
+	if (!root) return undefined;
+
+	const listed = await pi.exec("git", [
+		"-C",
+		root,
+		"ls-files",
+		"--cached",
+		"--others",
+		"--exclude-standard",
+		"-z",
+	]);
+	if (listed.code !== 0) {
+		throw new Error(listed.stderr.trim() || "Could not list repository files");
+	}
+	const files = listed.stdout
+		.split("\0")
+		.filter(isMarkdownOrAgentsFile)
+		.map((path) => join(root, path));
+	return { files, id: "repository", label: `Repository — ${root}`, root };
+}
+
+function collectMarkdownNodes(sources: MarkdownSource[]): MarkdownNode[] {
+	const nodes: MarkdownNode[] = [];
+	for (const source of sources) {
+		const rootKey = `${source.id}:`;
+		nodes.push({
+			kind: "directory",
+			depth: 0,
+			key: rootKey,
+			label: source.label,
+			path: source.root,
+		});
+		const directories = new Set<string>();
+		for (const file of source.files) {
+			let directory = dirname(relative(source.root, file));
+			while (directory !== ".") {
+				directories.add(directory);
+				const parent = dirname(directory);
+				if (parent === directory) break;
+				directory = parent;
+			}
+		}
+		for (const directory of [...directories].sort((a, b) => {
+			const depthDifference = a.split("/").length - b.split("/").length;
+			return depthDifference || a.localeCompare(b);
+		})) {
+			const parent = dirname(directory);
+			nodes.push({
+				kind: "directory",
+				depth: directory.split("/").length,
+				key: `${source.id}:${directory}`,
+				label: basename(directory),
+				parentKey: parent === "." ? rootKey : `${source.id}:${parent}`,
+				path: join(source.root, directory),
+			});
+		}
+		for (const file of source.files.sort((a, b) => a.localeCompare(b))) {
+			const filePath = relative(source.root, file);
+			const parent = dirname(filePath);
+			nodes.push({
+				kind: "file",
+				depth: filePath.split("/").length,
+				key: `${source.id}:${filePath}`,
+				label: basename(file),
+				parentKey: parent === "." ? rootKey : `${source.id}:${parent}`,
+				path: file,
+			});
+		}
+	}
+
+	const byParent = new Map<string, MarkdownNode[]>();
+	for (const node of nodes) {
+		if (!node.parentKey) continue;
+		const siblings = byParent.get(node.parentKey) ?? [];
+		siblings.push(node);
+		byParent.set(node.parentKey, siblings);
+	}
+	const ordered: MarkdownNode[] = [];
+	const append = (node: MarkdownNode) => {
+		ordered.push(node);
+		const children = (byParent.get(node.key) ?? []).sort((a, b) => {
+			if (a.kind !== b.kind) return a.kind === "directory" ? -1 : 1;
+			return a.label.localeCompare(b.label);
+		});
+		for (const child of children) append(child);
+	};
+	for (const source of sources) {
+		const root = nodes.find((node) => node.key === `${source.id}:`);
+		if (root) append(root);
+	}
+	return ordered;
+}
+
+async function pickMarkdown(
+	ctx: ExtensionCommandContext,
+	nodes: MarkdownNode[],
+): Promise<PickerResult | null> {
+	if (ctx.mode !== "tui") return null;
+	let selectedKey = nodes[0]?.key;
+	if (!selectedKey) return null;
+	const collapsed = new Set<string>();
+	const nodesByKey = new Map(nodes.map((node) => [node.key, node]));
+	let choosingPreviewTarget = false;
+	let query = "";
+	let searching = false;
+	const visibleNodes = () => {
+		const normalizedQuery = query.toLowerCase();
+		let matchingKeys: Set<string> | undefined;
+		if (normalizedQuery) {
+			matchingKeys = new Set<string>();
+			for (const node of nodes) {
+				if (!`${node.label} ${node.path}`.toLowerCase().includes(normalizedQuery)) continue;
+				let current: MarkdownNode | undefined = node;
+				while (current) {
+					matchingKeys.add(current.key);
+					current = current.parentKey ? nodesByKey.get(current.parentKey) : undefined;
+				}
+			}
+		}
+		return nodes.filter((node) => {
+			if (matchingKeys && !matchingKeys.has(node.key)) return false;
+			if (normalizedQuery) return true;
+			let parentKey = node.parentKey;
+			while (parentKey) {
+				if (collapsed.has(parentKey)) return false;
+				parentKey = nodesByKey.get(parentKey)?.parentKey;
+			}
+			return true;
+		});
+	};
+
+	return ctx.ui.custom<PickerResult | null>((tui, theme, _keybindings, done) => ({
+		render(width: number): string[] {
+			const allVisible = visibleNodes();
+			let selected = allVisible.findIndex((node) => node.key === selectedKey);
+			if (selected < 0) {
+				selected = 0;
+				if (allVisible[0]) selectedKey = allVisible[0].key;
+			}
+			const height = 18;
+			const start = Math.max(
+				0,
+				Math.min(selected - Math.floor(height / 2), allVisible.length - height),
+			);
+			const visible = allVisible.slice(start, start + height).map((node) => {
+				const prefix = node.key === selectedKey ? theme.fg("accent", "> ") : "  ";
+				const marker =
+					node.kind === "directory" ? (collapsed.has(node.key) ? "▸" : "▾") : "└─";
+				const label = `${"  ".repeat(node.depth)}${marker} ${node.label}`;
+				const text = node.kind === "directory" ? theme.fg("muted", label) : label;
+				return truncateToWidth(prefix + text, width);
+			});
+			const help = choosingPreviewTarget
+				? "Preview selected file: b browser • t terminal • esc back"
+				: searching
+					? "Type to search • enter apply • esc clear"
+					: "j/k move • ctrl+u/d half-page • / search • enter load/toggle • o open • p preview • esc cancel";
+			const title = searching
+				? `Search: ${query}▌`
+				: query
+					? `Markdown files — filter: ${query}`
+					: "Markdown files";
+			return [
+				truncateToWidth(theme.fg("accent", theme.bold(title)), width),
+				...(visible.length > 0 ? visible : [theme.fg("muted", "  No matches")]),
+				truncateToWidth(theme.fg("dim", help), width),
+			];
+		},
+		handleInput(data: string): void {
+			if (searching) {
+				if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+					query = "";
+					searching = false;
+				} else if (matchesKey(data, Key.enter)) {
+					searching = false;
+				} else if (matchesKey(data, Key.backspace)) {
+					query = query.slice(0, -1);
+				} else if (data.length === 1 && data >= " ") {
+					query += data;
+				}
+				tui.requestRender();
+				return;
+			}
+
+			const allVisible = visibleNodes();
+			let selected = allVisible.findIndex((node) => node.key === selectedKey);
+			if (selected < 0) {
+				selected = 0;
+				if (allVisible[0]) selectedKey = allVisible[0].key;
+			}
+			const node = allVisible[selected];
+			const move = (step: number) => {
+				if (allVisible.length > 0) {
+					const nextIndex = Math.max(0, Math.min(selected + step, allVisible.length - 1));
+					selectedKey = allVisible[nextIndex]!.key;
+				}
+				tui.requestRender();
+			};
+			const loadOrToggle = () => {
+				if (!node) return;
+				if (node.kind === "file") done({ action: "load", path: node.path });
+				else {
+					if (collapsed.has(node.key)) collapsed.delete(node.key);
+					else collapsed.add(node.key);
+					tui.requestRender();
+				}
+			};
+			if (choosingPreviewTarget) {
+				if (data === "b" && node) done({ action: "preview-browser", path: node.path });
+				else if (data === "t" && node) done({ action: "preview-terminal", path: node.path });
+				else if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+					choosingPreviewTarget = false;
+					tui.requestRender();
+				}
+				return;
+			}
+			if (data === "/") {
+				searching = true;
+				tui.requestRender();
+			} else if (matchesKey(data, Key.ctrl("u"))) move(-9);
+			else if (matchesKey(data, Key.ctrl("d"))) move(9);
+			else if (matchesKey(data, Key.up) || data === "k") move(-1);
+			else if (matchesKey(data, Key.down) || data === "j") move(1);
+			else if (data === "h" && node) {
+				if (node.kind === "directory" && !collapsed.has(node.key)) collapsed.add(node.key);
+				else if (node.parentKey) selectedKey = node.parentKey;
+				tui.requestRender();
+			} else if (data === "l" && node) {
+				if (node.kind === "directory") {
+					collapsed.delete(node.key);
+					tui.requestRender();
+				} else done({ action: "load", path: node.path });
+			} else if (matchesKey(data, Key.enter)) loadOrToggle();
+			else if ((data === "o" || data === "e") && node?.kind === "file") {
+				done({ action: "open", path: node.path });
+			} else if (data === "p" && node?.kind === "file") {
+				choosingPreviewTarget = true;
+				tui.requestRender();
+			} else if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) done(null);
+		},
+		invalidate() {},
+	}));
+}
+
+async function previewMarkdown(
+	ctx: ExtensionCommandContext,
+	path: string,
+	target: "browser" | "terminal",
+): Promise<void> {
+	const markdown = await readFile(path, "utf8");
+	if (target === "browser") {
+		await openPreviewInBrowser(ctx, markdown, dirname(path));
+	} else {
+		await openPreview(ctx, markdown, dirname(path));
+	}
+}
+
+async function openMarkdown(pi: ExtensionAPI, path: string): Promise<void> {
+	if (process.env.HERDR_ENV === "1") {
+		const split = await pi.exec("herdr", [
+			"pane",
+			"split",
+			"--current",
+			"--direction",
+			"right",
+			"--cwd",
+			dirname(path),
+			"--focus",
+		]);
+		if (split.code !== 0) throw new Error(split.stderr.trim() || "Could not open a Herdr pane");
+		const response = JSON.parse(split.stdout) as { result?: { pane?: { pane_id?: string } } };
+		const pane = response.result?.pane?.pane_id;
+		if (!pane) throw new Error("Herdr did not return the new pane ID");
+		const editor = process.env.VISUAL || process.env.EDITOR || "nvim";
+		const opened = await pi.exec("herdr", [
+			"pane",
+			"run",
+			pane,
+			`${editor} ${shellQuote(path)}`,
+		]);
+		if (opened.code !== 0) throw new Error(opened.stderr.trim() || "Could not start the editor");
+		return;
+	}
+
+	const command = platform() === "darwin" ? "open" : "xdg-open";
+	const opened = await pi.exec(command, [path]);
+	if (opened.code !== 0) throw new Error(opened.stderr.trim() || `Could not open ${path}`);
+}
+
+export default function saveMarkdownExtension(pi: ExtensionAPI) {
+	pi.registerCommand("save-md", {
+		description: "Save the latest assistant response as Markdown",
+		getArgumentCompletions: () => null,
+		handler: async (args, ctx) => {
+			await ctx.waitForIdle();
+
+			let parsed: string[];
+			try {
+				parsed = parseArguments(args);
+			} catch (error) {
+				ctx.ui.notify((error as Error).message, "warning");
+				return;
+			}
+			if (parsed.length < 1 || parsed.length > 2) {
+				ctx.ui.notify("Usage: /save-md <name> [directory]", "warning");
+				return;
+			}
+			const [name, requestedDirectory] = parsed as [string, string?];
+			if (basename(name) !== name || name === "." || name === "..") {
+				ctx.ui.notify("The name must be a file name, not a path", "warning");
+				return;
+			}
+
+			const branch = ctx.sessionManager.getBranch();
+			let assistantMessage: AssistantMessage | undefined;
+			for (let index = branch.length - 1; index >= 0; index--) {
+				const entry = branch[index];
+				if (entry?.type === "message" && entry.message.role === "assistant") {
+					assistantMessage = entry.message;
+					break;
+				}
+			}
+			if (!assistantMessage) {
+				ctx.ui.notify("No assistant response to save", "warning");
+				return;
+			}
+			const markdown = textContent(assistantMessage.content);
+			if (!markdown.trim()) {
+				ctx.ui.notify("The latest assistant response has no Markdown text", "warning");
+				return;
+			}
+
+			let saveDirectory: string;
+			try {
+				saveDirectory = await markdownDirectory(pi, ctx.cwd, requestedDirectory);
+			} catch (error) {
+				ctx.ui.notify((error as Error).message, "error");
+				return;
+			}
+			const fileName = name.endsWith(".md") ? name : `${name}.md`;
+			const path = join(saveDirectory, fileName);
+			try {
+				await mkdir(saveDirectory, { recursive: true });
+				await writeFile(path, markdown.endsWith("\n") ? markdown : `${markdown}\n`, {
+					encoding: "utf8",
+					flag: "wx",
+				});
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+					ctx.ui.notify(`File already exists: ${path}`, "error");
+					return;
+				}
+				throw error;
+			}
+			ctx.ui.notify(`Saved Markdown to ${path}`, "info");
+		},
+	});
+
+	const browse = async (args: string, ctx: ExtensionCommandContext) => {
+		let requestedDirectory: string | undefined;
+		try {
+			const parsed = parseArguments(args);
+			if (parsed.length > 1) throw new Error("Usage: /md [directory]");
+			requestedDirectory = parsed[0];
+		} catch (error) {
+			ctx.ui.notify((error as Error).message, "warning");
+			return;
+		}
+		let sources: MarkdownSource[];
+		try {
+			const hiddenRoot = await defaultMarkdownDirectory(pi, ctx.cwd);
+			const configuredDirectory = requestedDirectory ?? process.env.PI_SAVE_MD_DIR;
+			const configuredRoot = configuredDirectory
+				? expandDirectory(configuredDirectory, ctx.cwd)
+				: undefined;
+			sources = [];
+			if (configuredRoot && configuredRoot !== hiddenRoot) {
+				const files = await collectMarkdownFiles(configuredRoot);
+				if (files.length > 0) {
+					sources.push({
+						files,
+						id: "configured",
+						label: `Saved Markdown (configured) — ${configuredRoot}`,
+						root: configuredRoot,
+					});
+				}
+			}
+			const hiddenFiles = await collectMarkdownFiles(hiddenRoot);
+			if (hiddenFiles.length > 0) {
+				sources.push({
+					files: hiddenFiles,
+					id: "hidden",
+					label: `Saved Markdown (hidden) — ${hiddenRoot}`,
+					root: hiddenRoot,
+				});
+			}
+			const repository = await repositoryMarkdownSource(pi, ctx.cwd);
+			if (repository && repository.files.length > 0) sources.push(repository);
+		} catch (error) {
+			ctx.ui.notify((error as Error).message, "error");
+			return;
+		}
+		if (sources.length === 0) {
+			ctx.ui.notify("No Markdown or .AGENTS files found", "warning");
+			return;
+		}
+		const nodes = collectMarkdownNodes(sources);
+		const choice = await pickMarkdown(ctx, nodes);
+		if (!choice) return;
+		if (choice.action === "open") {
+			try {
+				await openMarkdown(pi, choice.path);
+				ctx.ui.notify(`Opened ${choice.path}`, "info");
+			} catch (error) {
+				ctx.ui.notify((error as Error).message, "error");
+			}
+			return;
+		}
+		if (choice.action === "preview-browser" || choice.action === "preview-terminal") {
+			try {
+				await previewMarkdown(
+					ctx,
+					choice.path,
+					choice.action === "preview-browser" ? "browser" : "terminal",
+				);
+			} catch (error) {
+				ctx.ui.notify((error as Error).message, "error");
+			}
+			return;
+		}
+		const markdown = await readFile(choice.path, "utf8");
+		ctx.ui.pasteToEditor(markdown);
+		ctx.ui.notify(`Loaded ${choice.path} into the editor`, "info");
+	};
+
+	pi.on("session_shutdown", closeSharedPreviewBrowser);
+
+	pi.registerCommand("md", {
+		description: "Browse saved and repository Markdown; Enter loads, o opens, p previews",
+		handler: browse,
+	});
+	pi.registerCommand("md-tree", {
+		description: "Alias for /md",
+		handler: browse,
+	});
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "pi-md-tree",
+  "version": "0.1.0",
+  "description": "Save, browse, search, open, and preview Markdown from Pi",
+  "type": "module",
+  "exports": "./index.ts",
+  "files": [
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "npm run typecheck && npm test",
+    "test": "node --test test/*.test.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-coding-agent",
+    "markdown",
+    "terminal",
+    "tui"
+  ],
+  "author": "Alexander Bianchi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexanderbianchi/pi-md-tree.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alexanderbianchi/pi-md-tree/issues"
+  },
+  "homepage": "https://github.com/alexanderbianchi/pi-md-tree#readme",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "pi-markdown-preview": "0.16.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "jiti": "2.6.1",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}