shortcutxl 0.2.0

package/agent-docs/examples/extensions/minimal-mode.ts

@@ -0,0 +1,430 @@
+/**
+ * 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:
+ *   shortcut -e ./minimal-mode.ts
+ *
+ * Then use ctrl+o to toggle between minimal (collapsed) and full (expanded) views.
+ */
+
+import { homedir } from 'os';
+import type { ExtensionAPI } from 'shortcutxl';
+import {
+  createBashTool,
+  createEditTool,
+  createFindTool,
+  createGrepTool,
+  createLsTool,
+  createReadTool,
+  createWriteTool,
+  Text
+} from 'shortcutxl';
+
+/**
+ * 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;
+}
+
+// Cache for built-in tools by cwd
+const toolCache = new Map<string, ReturnType<typeof createBuiltInTools>>();
+
+function createBuiltInTools(cwd: string) {
+  return {
+    read: createReadTool(cwd),
+    bash: createBashTool(cwd),
+    edit: createEditTool(cwd),
+    write: createWriteTool(cwd),
+    find: createFindTool(cwd),
+    grep: createGrepTool(cwd),
+    ls: createLsTool(cwd)
+  };
+}
+
+function getBuiltInTools(cwd: string) {
+  let tools = toolCache.get(cwd);
+  if (!tools) {
+    tools = createBuiltInTools(cwd);
+    toolCache.set(cwd, tools);
+  }
+  return tools;
+}
+
+export default function (shortcut: ExtensionAPI) {
+  // =========================================================================
+  // Read Tool
+  // =========================================================================
+  shortcut.registerTool({
+    name: 'read',
+    label: 'read',
+    description:
+      'Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to 2000 lines or 50KB (whichever is hit first). Use offset/limit for large files.',
+    parameters: getBuiltInTools(process.cwd()).read.parameters,
+
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const tools = getBuiltInTools(ctx.cwd);
+      return tools.read.execute(toolCallId, params, signal, onUpdate);
+    },
+
+    renderCall(args, theme) {
+      const path = shortenPath(args.path || '');
+      let pathDisplay = path ? theme.fg('accent', path) : theme.fg('toolOutput', '...');
+
+      // Show line range if specified
+      if (args.offset !== undefined || args.limit !== undefined) {
+        const startLine = args.offset ?? 1;
+        const endLine = args.limit !== undefined ? startLine + args.limit - 1 : '';
+        pathDisplay += theme.fg('warning', `:${startLine}${endLine ? `-${endLine}` : ''}`);
+      }
+
+      return new Text(`${theme.fg('toolTitle', theme.bold('read'))} ${pathDisplay}`, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme) {
+      // 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
+  // =========================================================================
+  shortcut.registerTool({
+    name: 'bash',
+    label: 'bash',
+    description:
+      'Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last 2000 lines or 50KB (whichever is hit first).',
+    parameters: getBuiltInTools(process.cwd()).bash.parameters,
+
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const tools = getBuiltInTools(ctx.cwd);
+      return tools.bash.execute(toolCallId, params, signal, onUpdate);
+    },
+
+    renderCall(args, theme) {
+      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) {
+      // 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
+  // =========================================================================
+  shortcut.registerTool({
+    name: 'write',
+    label: 'write',
+    description:
+      "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+    parameters: getBuiltInTools(process.cwd()).write.parameters,
+
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const tools = getBuiltInTools(ctx.cwd);
+      return tools.write.execute(toolCallId, params, signal, onUpdate);
+    },
+
+    renderCall(args, theme) {
+      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) {
+      // 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
+  // =========================================================================
+  shortcut.registerTool({
+    name: 'edit',
+    label: 'edit',
+    description:
+      'Edit a file by replacing exact text. The oldText must match exactly (including whitespace). Use this for precise, surgical edits.',
+    parameters: getBuiltInTools(process.cwd()).edit.parameters,
+
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const tools = getBuiltInTools(ctx.cwd);
+      return tools.edit.execute(toolCallId, params, signal, onUpdate);
+    },
+
+    renderCall(args, theme) {
+      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) {
+      // 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
+  // =========================================================================
+  shortcut.registerTool({
+    name: 'find',
+    label: 'find',
+    description:
+      'Find files by name pattern (glob). Searches recursively from the specified path. Output limited to 200 results.',
+    parameters: getBuiltInTools(process.cwd()).find.parameters,
+
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const tools = getBuiltInTools(ctx.cwd);
+      return tools.find.execute(toolCallId, params, signal, onUpdate);
+    },
+
+    renderCall(args, theme) {
+      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) {
+      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
+  // =========================================================================
+  shortcut.registerTool({
+    name: 'grep',
+    label: 'grep',
+    description:
+      'Search file contents by regex pattern. Uses ripgrep for fast searching. Output limited to 200 matches.',
+    parameters: getBuiltInTools(process.cwd()).grep.parameters,
+
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const tools = getBuiltInTools(ctx.cwd);
+      return tools.grep.execute(toolCallId, params, signal, onUpdate);
+    },
+
+    renderCall(args, theme) {
+      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) {
+      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
+  // =========================================================================
+  shortcut.registerTool({
+    name: 'ls',
+    label: 'ls',
+    description:
+      'List directory contents with file sizes. Shows files and directories with their sizes. Output limited to 500 entries.',
+    parameters: getBuiltInTools(process.cwd()).ls.parameters,
+
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const tools = getBuiltInTools(ctx.cwd);
+      return tools.ls.execute(toolCallId, params, signal, onUpdate);
+    },
+
+    renderCall(args, theme) {
+      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) {
+      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/agent-docs/examples/extensions/modal-editor.ts

@@ -0,0 +1,90 @@
+/**
+ * Modal Editor - vim-like modal editing example
+ *
+ * Usage: shortcut --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,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  type ExtensionAPI
+} from 'shortcutxl';
+
+// 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 (shortcut: ExtensionAPI) {
+  shortcut.on('session_start', (_event, ctx) => {
+    ctx.ui.setEditorComponent((tui, theme, kb) => new ModalEditor(tui, theme, kb));
+  });
+}

package/agent-docs/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: shortcut -e ./model-status.ts
+ */
+
+import type { ExtensionAPI } from 'shortcutxl';
+
+export default function (shortcut: ExtensionAPI) {
+  shortcut.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/agent-docs/examples/extensions/notify.ts

@@ -0,0 +1,55 @@
+/**
+ * Pi Notify Extension
+ *
+ * Sends a native terminal notification when Pi 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 'shortcutxl';
+
+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 (shortcut: ExtensionAPI) {
+  shortcut.on('agent_end', async () => {
+    notify('Pi', 'Ready for input');
+  });
+}