Canvas TUI Toolkit

Start here when using terminal canvases. This skill covers the overall workflow, canvas types, and IPC communication.

Overview

Canvas provides interactive terminal displays (TUIs) that Claude can spawn and control. Each canvas type supports multiple scenarios for different interaction modes.

Available Canvas Types

Quick Start

cd ${CLAUDE_PLUGIN_ROOT}

# Run canvas in current terminal
bun run src/cli.ts show calendar

# Spawn canvas in new tmux split
bun run src/cli.ts spawn calendar --scenario meeting-picker --config '{...}'

Spawning Canvases

Always use spawn for interactive scenarios - this opens the canvas in a tmux split pane while keeping the conversation terminal available.

bun run src/cli.ts spawn [kind] --scenario [name] --config '[json]'

Parameters:

• kind: Canvas type (calendar, document, flight)
• --scenario: Interaction mode (e.g., display, meeting-picker, edit)
• --config: JSON configuration for the canvas
• --id: Optional canvas instance ID for IPC

IPC Communication

Interactive canvases communicate via Unix domain sockets.

Canvas → Controller:

{ type: "ready", scenario }        // Canvas is ready
{ type: "selected", data }         // User made a selection
{ type: "cancelled", reason? }     // User cancelled
{ type: "error", message }         // Error occurred

Controller → Canvas:

{
  type: ("update", config);
} // Update canvas configuration
{
  type: "close";
} // Request canvas to close
{
  type: "ping";
} // Health check

High-Level API

For programmatic use, import the API module:

import { pickMeetingTime, editDocument, bookFlight } from "${CLAUDE_PLUGIN_ROOT}/src/api";

// Spawn meeting picker and wait for selection
const result = await pickMeetingTime({
  calendars: [...],
  slotGranularity: 30,
});

if (result.success && result.data) {
  console.log(`Selected: ${result.data.startTime}`);
}

Requirements

• iTerm2 or tmux: Canvas spawning requires one of:
  • iTerm2 (recommended for macOS) - just run Claude Code inside iTerm2
  • tmux session - for cross-platform or remote use
• Terminal with mouse support: For click-based interactions
• Bun: Runtime for executing canvas commands

Terminal Detection

Check your environment with:

bun run src/cli.ts env

The canvas auto-detects iTerm2 or tmux and uses the appropriate split method.

Skills Reference