Terminal UI Development Assistant

Workflow for developing and testing terminal-based user interfaces (TUIs) using Peekaboo for visual inspection and interaction.

When to Use This Skill

Invoke /tui-dev-assist when:

• Testing terminal UI applications (ncurses, blessed, ink, etc.)
• Debugging CLI tool output formatting
• Automating terminal application interactions
• Visual regression testing for TUI components
• Testing keyboard navigation in terminal apps

Quick Start

import { tui } from "./agent-scripts";

// Capture terminal for review
const capture = await tui.captureTerminal();
// Review capture.path to see terminal state
await capture.cleanup();

// Capture specific terminal app
const capture = await tui.captureTerminal({ app: "ghostty" });

// Interactive TUI testing
await tui.testTUI({ app: "ghostty" }, async (session) => {
  await session.type("vim test.txt");
  await session.press("Return");
  await session.sleep(500);
  await session.screenshot("/tmp/vim.png");
  await session.hotkey(["Escape"]);
  await session.type(":q!");
  await session.press("Return");
});

Tool Selection Guide

Workflows

1. Capture Terminal for Review

import { tui } from "./agent-scripts";

// Capture the frontmost terminal
const capture = await tui.captureTerminal();
// Review capture.path to see terminal state
await capture.cleanup();

// Capture specific terminal emulator
const capture = await tui.captureTerminal({ app: "iTerm2" });

2. Test TUI Application

import { tui } from "./agent-scripts";

await tui.testTUI({ app: "ghostty" }, async (session) => {
  // Launch a TUI app
  await session.type("htop");
  await session.press("Return");
  await session.sleep(1000);

  // Take screenshot
  await session.screenshot("/tmp/htop.png");

  // Navigate with keyboard
  await session.press("Down");
  await session.press("Down");

  // Quit
  await session.type("q");
});

3. Test Vim/Neovim

import { tui } from "./agent-scripts";

await tui.testTUI({ app: "ghostty" }, async (session) => {
  // Open vim
  await session.type("vim test.txt");
  await session.press("Return");
  await session.sleep(500);

  // Enter insert mode
  await session.type("i");
  await session.type("Hello, World!");

  // Exit insert mode
  await session.press("Escape");

  // Save and quit
  await session.type(":wq");
  await session.press("Return");

  // Verify file was created
  await session.type("cat test.txt");
  await session.press("Return");
  await session.screenshot("/tmp/vim-result.png");
});

4. Test Interactive CLI

import { tui } from "./agent-scripts";

await tui.testTUI({ app: "ghostty" }, async (session) => {
  // Run interactive CLI
  await session.type("npm init");
  await session.press("Return");
  await session.sleep(500);

  // Answer prompts
  await session.type("my-package"); // package name
  await session.press("Return");
  await session.press("Return"); // version (default)
  await session.type("A test package"); // description
  await session.press("Return");

  // Screenshot the prompts
  await session.screenshot("/tmp/npm-init.png");

  // Cancel
  await session.hotkey(["Control", "c"]);
});

5. Test Mouse-Enabled TUI

import { tui } from "./agent-scripts";

await tui.testTUI({ app: "ghostty" }, async (session) => {
  // Launch mouse-enabled TUI
  await session.type("lazygit");
  await session.press("Return");
  await session.sleep(1000);

  // Detect clickable elements
  const elements = await session.detectElements();
  console.log("Found elements:", elements.elementCount);

  // Find and click a button
  const stageBtn = elements.elements.find((e) =>
    e.label?.toLowerCase().includes("stage"),
  );
  if (stageBtn) {
    await session.clickElement(stageBtn.id);
  }

  await session.screenshot("/tmp/lazygit.png");

  // Quit
  await session.type("q");
});

6. Visual Regression Testing

import { tui } from "./agent-scripts";

// Take baseline screenshots at different states
await tui.testTUI({ app: "ghostty" }, async (session) => {
  await session.type("./my-tui-app");
  await session.press("Return");
  await session.sleep(500);

  // Capture different states
  await session.screenshot("/tmp/tui-initial.png");

  await session.press("Tab");
  await session.screenshot("/tmp/tui-tab1.png");

  await session.press("Tab");
  await session.screenshot("/tmp/tui-tab2.png");

  await session.hotkey(["Control", "c"]);
});

Terminal Emulator Support

Common Key Names

For session.press() and session.hotkey():

Source Files

• agent-scripts/lib/tui/index.ts - TUI convenience functions
• agent-scripts/lib/peekaboo/ - Peekaboo macOS functions

Related Skills

• /peekaboo-macos - Full Peekaboo API reference