@knightcodeai/cli 0.17.3 → 0.18.0

package/examples/extensions/minimal-mode.ts

@@ -0,0 +1,353 @@
+/**
+ * Minimal Mode Example - Demonstrates a "minimal" tool display mode
+ *
+ * This extension overrides built-in tools to provide custom rendering:
+ * - Collapsed mode: Only shows the tool call (command/path), no output
+ * - Expanded mode: Shows full output like the built-in renderers
+ *
+ * This demonstrates how a "minimal mode" could work, where ctrl+o cycles through:
+ * - Standard: Shows truncated output (current default)
+ * - Expanded: Shows full output (current expanded)
+ * - Minimal: Shows only tool call, no output (this extension's collapsed mode)
+ *
+ * Usage:
+ *   knightcode -e ./minimal-mode.ts
+ *
+ * Then use ctrl+o to toggle between minimal (collapsed) and full (expanded) views.
+ */
+
+import type { ExtensionAPI } from "@knightcodeai/cli";
+import {
+	createBashToolDefinition,
+	createEditToolDefinition,
+	createFindToolDefinition,
+	createGrepToolDefinition,
+	createLsToolDefinition,
+	createReadToolDefinition,
+	createWriteToolDefinition,
+	formatReadLineRange,
+} from "@knightcodeai/cli";
+import { Text } from "@knightcode/tui";
+import { homedir } from "os";
+
+/**
+ * Shorten a path by replacing home directory with ~
+ */
+function shortenPath(path: string): string {
+	const home = homedir();
+	if (path.startsWith(home)) {
+		return `~${path.slice(home.length)}`;
+	}
+	return path;
+}
+
+function createBuiltInTools(cwd: string) {
+	return {
+		read: createReadToolDefinition(cwd),
+		bash: createBashToolDefinition(cwd),
+		edit: createEditToolDefinition(cwd),
+		write: createWriteToolDefinition(cwd),
+		find: createFindToolDefinition(cwd),
+		grep: createGrepToolDefinition(cwd),
+		ls: createLsToolDefinition(cwd),
+	};
+}
+
+export default function (knightcode: ExtensionAPI) {
+	const tools = createBuiltInTools(process.cwd());
+
+	// =========================================================================
+	// Read Tool
+	// =========================================================================
+	knightcode.registerTool({
+		...tools.read,
+
+		renderCall(args, theme, _context) {
+			const path = shortenPath(args.path || "");
+			let pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
+
+			const lineRange = formatReadLineRange(args.offset, args.limit);
+			if (lineRange) {
+				pathDisplay += theme.fg("warning", lineRange);
+			}
+
+			return new Text(`${theme.fg("toolTitle", theme.bold("read"))} ${pathDisplay}`, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			// Minimal mode: show nothing in collapsed state
+			if (!expanded) {
+				return new Text("", 0, 0);
+			}
+
+			// Expanded mode: show full output
+			const textContent = result.content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") {
+				return new Text("", 0, 0);
+			}
+
+			const lines = textContent.text.split("\n");
+			const output = lines.map((line) => theme.fg("toolOutput", line)).join("\n");
+			return new Text(`\n${output}`, 0, 0);
+		},
+	});
+
+	// =========================================================================
+	// Bash Tool
+	// =========================================================================
+	knightcode.registerTool({
+		...tools.bash,
+
+		renderCall(args, theme, _context) {
+			const command = args.command || "...";
+			const timeout = args.timeout as number | undefined;
+			const timeoutSuffix = timeout ? theme.fg("muted", ` (timeout ${timeout}s)`) : "";
+
+			return new Text(theme.fg("toolTitle", theme.bold(`$ ${command}`)) + timeoutSuffix, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			// Minimal mode: show nothing in collapsed state
+			if (!expanded) {
+				return new Text("", 0, 0);
+			}
+
+			// Expanded mode: show full output
+			const textContent = result.content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") {
+				return new Text("", 0, 0);
+			}
+
+			const output = textContent.text
+				.trim()
+				.split("\n")
+				.map((line) => theme.fg("toolOutput", line))
+				.join("\n");
+
+			if (!output) {
+				return new Text("", 0, 0);
+			}
+
+			return new Text(`\n${output}`, 0, 0);
+		},
+	});
+
+	// =========================================================================
+	// Write Tool
+	// =========================================================================
+	knightcode.registerTool({
+		...tools.write,
+
+		renderCall(args, theme, _context) {
+			const path = shortenPath(args.path || "");
+			const pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
+			const lineCount = args.content ? args.content.split("\n").length : 0;
+			const lineInfo = lineCount > 0 ? theme.fg("muted", ` (${lineCount} lines)`) : "";
+
+			return new Text(`${theme.fg("toolTitle", theme.bold("write"))} ${pathDisplay}${lineInfo}`, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			// Minimal mode: show nothing (file was written)
+			if (!expanded) {
+				return new Text("", 0, 0);
+			}
+
+			// Expanded mode: show error if any
+			if (result.content.some((c) => c.type === "text" && c.text)) {
+				const textContent = result.content.find((c) => c.type === "text");
+				if (textContent?.type === "text" && textContent.text) {
+					return new Text(`\n${theme.fg("error", textContent.text)}`, 0, 0);
+				}
+			}
+
+			return new Text("", 0, 0);
+		},
+	});
+
+	// =========================================================================
+	// Edit Tool
+	// =========================================================================
+	knightcode.registerTool({
+		...tools.edit,
+		renderShell: "default",
+
+		renderCall(args, theme, _context) {
+			const path = shortenPath(args.path || "");
+			const pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
+
+			return new Text(`${theme.fg("toolTitle", theme.bold("edit"))} ${pathDisplay}`, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			// Minimal mode: show nothing in collapsed state
+			if (!expanded) {
+				return new Text("", 0, 0);
+			}
+
+			// Expanded mode: show diff or error
+			const textContent = result.content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") {
+				return new Text("", 0, 0);
+			}
+
+			// For errors, show the error message
+			const text = textContent.text;
+			if (text.includes("Error") || text.includes("error")) {
+				return new Text(`\n${theme.fg("error", text)}`, 0, 0);
+			}
+
+			// Otherwise show the text (would be nice to show actual diff here)
+			return new Text(`\n${theme.fg("toolOutput", text)}`, 0, 0);
+		},
+	});
+
+	// =========================================================================
+	// Find Tool
+	// =========================================================================
+	knightcode.registerTool({
+		...tools.find,
+
+		renderCall(args, theme, _context) {
+			const pattern = args.pattern || "";
+			const path = shortenPath(args.path || ".");
+			const limit = args.limit;
+
+			let text = `${theme.fg("toolTitle", theme.bold("find"))} ${theme.fg("accent", pattern)}`;
+			text += theme.fg("toolOutput", ` in ${path}`);
+			if (limit !== undefined) {
+				text += theme.fg("toolOutput", ` (limit ${limit})`);
+			}
+
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			if (!expanded) {
+				// Minimal: just show count
+				const textContent = result.content.find((c) => c.type === "text");
+				if (textContent?.type === "text") {
+					const count = textContent.text.trim().split("\n").filter(Boolean).length;
+					if (count > 0) {
+						return new Text(theme.fg("muted", ` → ${count} files`), 0, 0);
+					}
+				}
+				return new Text("", 0, 0);
+			}
+
+			// Expanded: show full results
+			const textContent = result.content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") {
+				return new Text("", 0, 0);
+			}
+
+			const output = textContent.text
+				.trim()
+				.split("\n")
+				.map((line) => theme.fg("toolOutput", line))
+				.join("\n");
+
+			return new Text(`\n${output}`, 0, 0);
+		},
+	});
+
+	// =========================================================================
+	// Grep Tool
+	// =========================================================================
+	knightcode.registerTool({
+		...tools.grep,
+
+		renderCall(args, theme, _context) {
+			const pattern = args.pattern || "";
+			const path = shortenPath(args.path || ".");
+			const glob = args.glob;
+			const limit = args.limit;
+
+			let text = `${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("accent", `/${pattern}/`)}`;
+			text += theme.fg("toolOutput", ` in ${path}`);
+			if (glob) {
+				text += theme.fg("toolOutput", ` (${glob})`);
+			}
+			if (limit !== undefined) {
+				text += theme.fg("toolOutput", ` limit ${limit}`);
+			}
+
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			if (!expanded) {
+				// Minimal: just show match count
+				const textContent = result.content.find((c) => c.type === "text");
+				if (textContent?.type === "text") {
+					const count = textContent.text.trim().split("\n").filter(Boolean).length;
+					if (count > 0) {
+						return new Text(theme.fg("muted", ` → ${count} matches`), 0, 0);
+					}
+				}
+				return new Text("", 0, 0);
+			}
+
+			// Expanded: show full results
+			const textContent = result.content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") {
+				return new Text("", 0, 0);
+			}
+
+			const output = textContent.text
+				.trim()
+				.split("\n")
+				.map((line) => theme.fg("toolOutput", line))
+				.join("\n");
+
+			return new Text(`\n${output}`, 0, 0);
+		},
+	});
+
+	// =========================================================================
+	// Ls Tool
+	// =========================================================================
+	knightcode.registerTool({
+		...tools.ls,
+
+		renderCall(args, theme, _context) {
+			const path = shortenPath(args.path || ".");
+			const limit = args.limit;
+
+			let text = `${theme.fg("toolTitle", theme.bold("ls"))} ${theme.fg("accent", path)}`;
+			if (limit !== undefined) {
+				text += theme.fg("toolOutput", ` (limit ${limit})`);
+			}
+
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			if (!expanded) {
+				// Minimal: just show entry count
+				const textContent = result.content.find((c) => c.type === "text");
+				if (textContent?.type === "text") {
+					const count = textContent.text.trim().split("\n").filter(Boolean).length;
+					if (count > 0) {
+						return new Text(theme.fg("muted", ` → ${count} entries`), 0, 0);
+					}
+				}
+				return new Text("", 0, 0);
+			}
+
+			// Expanded: show full listing
+			const textContent = result.content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") {
+				return new Text("", 0, 0);
+			}
+
+			const output = textContent.text
+				.trim()
+				.split("\n")
+				.map((line) => theme.fg("toolOutput", line))
+				.join("\n");
+
+			return new Text(`\n${output}`, 0, 0);
+		},
+	});
+}

package/examples/extensions/modal-editor.ts

@@ -0,0 +1,85 @@
+/**
+ * Modal Editor - vim-like modal editing example
+ *
+ * Usage: knightcode --extension ./examples/extensions/modal-editor.ts
+ *
+ * - Escape: insert → normal mode (in normal mode, aborts agent)
+ * - i: normal → insert mode
+ * - hjkl: navigation in normal mode
+ * - ctrl+c, ctrl+d, etc. work in both modes
+ */
+
+import { CustomEditor, type ExtensionAPI } from "@knightcodeai/cli";
+import { matchesKey, truncateToWidth, visibleWidth } from "@knightcode/tui";
+
+// Normal mode key mappings: key -> escape sequence (or null for mode switch)
+const NORMAL_KEYS: Record<string, string | null> = {
+	h: "\x1b[D", // left
+	j: "\x1b[B", // down
+	k: "\x1b[A", // up
+	l: "\x1b[C", // right
+	"0": "\x01", // line start
+	$: "\x05", // line end
+	x: "\x1b[3~", // delete char
+	i: null, // insert mode
+	a: null, // append (insert + right)
+};
+
+class ModalEditor extends CustomEditor {
+	private mode: "normal" | "insert" = "insert";
+
+	handleInput(data: string): void {
+		// Escape toggles to normal mode, or passes through for app handling
+		if (matchesKey(data, "escape")) {
+			if (this.mode === "insert") {
+				this.mode = "normal";
+			} else {
+				super.handleInput(data); // abort agent, etc.
+			}
+			return;
+		}
+
+		// Insert mode: pass everything through
+		if (this.mode === "insert") {
+			super.handleInput(data);
+			return;
+		}
+
+		// Normal mode: check mapped keys
+		if (data in NORMAL_KEYS) {
+			const seq = NORMAL_KEYS[data];
+			if (data === "i") {
+				this.mode = "insert";
+			} else if (data === "a") {
+				this.mode = "insert";
+				super.handleInput("\x1b[C"); // move right first
+			} else if (seq) {
+				super.handleInput(seq);
+			}
+			return;
+		}
+
+		// Pass control sequences (ctrl+c, etc.) to super, ignore printable chars
+		if (data.length === 1 && data.charCodeAt(0) >= 32) return;
+		super.handleInput(data);
+	}
+
+	render(width: number): string[] {
+		const lines = super.render(width);
+		if (lines.length === 0) return lines;
+
+		// Add mode indicator to bottom border
+		const label = this.mode === "normal" ? " NORMAL " : " INSERT ";
+		const last = lines.length - 1;
+		if (visibleWidth(lines[last]!) >= label.length) {
+			lines[last] = truncateToWidth(lines[last]!, width - label.length, "") + label;
+		}
+		return lines;
+	}
+}
+
+export default function (knightcode: ExtensionAPI) {
+	knightcode.on("session_start", (_event, ctx) => {
+		ctx.ui.setEditorComponent((tui, theme, kb) => new ModalEditor(tui, theme, kb));
+	});
+}

package/examples/extensions/model-status.ts

@@ -0,0 +1,31 @@
+/**
+ * Model status extension - shows model changes in the status bar.
+ *
+ * Demonstrates the `model_select` hook which fires when the model changes
+ * via /model command, Ctrl+P cycling, or session restore.
+ *
+ * Usage: knightcode -e ./model-status.ts
+ */
+
+import type { ExtensionAPI } from "@knightcodeai/cli";
+
+export default function (knightcode: ExtensionAPI) {
+	knightcode.on("model_select", async (event, ctx) => {
+		const { model, previousModel, source } = event;
+
+		// Format model identifiers
+		const next = `${model.provider}/${model.id}`;
+		const prev = previousModel ? `${previousModel.provider}/${previousModel.id}` : "none";
+
+		// Show notification on change
+		if (source !== "restore") {
+			ctx.ui.notify(`Model: ${next}`, "info");
+		}
+
+		// Update status bar with current model
+		ctx.ui.setStatus("model", `🤖 ${model.id}`);
+
+		// Log change details (visible in debug output)
+		console.log(`[model_select] ${prev} → ${next} (${source})`);
+	});
+}

package/examples/extensions/notify.ts

@@ -0,0 +1,57 @@
+/**
+ * KnightCode Notify Extension
+ *
+ * Sends a native terminal notification when KnightCode agent is done and waiting for input.
+ * Supports multiple terminal protocols:
+ * - OSC 777: Ghostty, iTerm2, WezTerm, rxvt-unicode
+ * - OSC 99: Kitty
+ * - Windows toast: Windows Terminal (WSL)
+ */
+
+import type { ExtensionAPI } from "@knightcodeai/cli";
+
+function windowsToastScript(title: string, body: string): string {
+	const type = "Windows.UI.Notifications";
+	const mgr = `[${type}.ToastNotificationManager, ${type}, ContentType = WindowsRuntime]`;
+	const template = `[${type}.ToastTemplateType]::ToastText01`;
+	const toast = `[${type}.ToastNotification]::new($xml)`;
+	return [
+		`${mgr} > $null`,
+		`$xml = [${type}.ToastNotificationManager]::GetTemplateContent(${template})`,
+		`$xml.GetElementsByTagName('text')[0].AppendChild($xml.CreateTextNode('${body}')) > $null`,
+		`[${type}.ToastNotificationManager]::CreateToastNotifier('${title}').Show(${toast})`,
+	].join("; ");
+}
+
+function notifyOSC777(title: string, body: string): void {
+	process.stdout.write(`\x1b]777;notify;${title};${body}\x07`);
+}
+
+function notifyOSC99(title: string, body: string): void {
+	// Kitty OSC 99: i=notification id, d=0 means not done yet, p=body for second part
+	process.stdout.write(`\x1b]99;i=1:d=0;${title}\x1b\\`);
+	process.stdout.write(`\x1b]99;i=1:p=body;${body}\x1b\\`);
+}
+
+function notifyWindows(title: string, body: string): void {
+	const { execFile } = require("child_process");
+	execFile("powershell.exe", ["-NoProfile", "-Command", windowsToastScript(title, body)]);
+}
+
+function notify(title: string, body: string): void {
+	if (process.env.WT_SESSION) {
+		notifyWindows(title, body);
+	} else if (process.env.KITTY_WINDOW_ID) {
+		notifyOSC99(title, body);
+	} else {
+		notifyOSC777(title, body);
+	}
+}
+
+export default function (knightcode: ExtensionAPI) {
+	// `agent_end` fires after each low-level run; KnightCode may still retry, compact,
+	// or continue with queued follow-ups. Notify only after the full run settles.
+	knightcode.on("agent_settled", async () => {
+		notify("KnightCode", "Ready for input");
+	});
+}