Spawn and control interactive terminal displays (calendars, documents, flights) with real-time IPC communication

version
0.1.0
GitHub stars
50

Install

/plugin install canvas@claude-canvas

Run it inside Claude Code after adding the marketplace with /plugin marketplace add BhalPunia/claude-canvas.

Contents

Discovered from source

Skills 4

Calendar Canvas

Display calendar views and enable interactive meeting time selection.

Scenarios

display (default)

View-only calendar display. User can navigate weeks but cannot select times.

bun run src/cli.ts show calendar --scenario display --config '{
  "title": "My Week",
  "events": [
    {"id": "1", "title": "Meeting", "startTime": "2025-01-06T09:00:00", "endTime": "2025-01-06T10:00:00"}
  ]
}'

meeting-picker

Interactive scenario for selecting a free time slot when viewing multiple people's calendars.

  • Shows multiple calendars overlaid with different colors
  • User can click on free slots to select a meeting time
  • Selection is sent back via IPC
  • Supports configurable time slot granularity (15/30/60 min)
bun run src/cli.ts spawn calendar --scenario meeting-picker --config '{
  "calendars": [
    {
      "name": "Alice",
      "color": "blue",
      "events": [
        {"id": "1", "title": "Standup", "startTime": "2025-01-06T09:00:00", "endTime": "2025-01-06T09:30:00"}
      ]
    },
    {
      "name": "Bob",
      "color": "green",
      "events": [
        {"id": "2", "title": "Call", "startTime": "2025-01-06T14:00:00", "endTime": "2025-01-06T15:00:00"}
      ]
    }
  ],
  "slotGranularity": 30,
  "minDuration": 30,
  "maxDuration": 120
}'

Configuration

Display Config

interface CalendarConfig {
  title?: string;
  events: CalendarEvent[];
}

interface CalendarEvent {
  id: string;
  title: string;
  startTime: string;  // ISO datetime
  endTime: string;    // ISO datetime
  color?: string;     // blue, green, red, yellow, magenta, cyan
}

Meeting Picker Config

interface MeetingPickerConfig {
  calendars: Calendar[];
  slotGranularity?: number;  // 15, 30, or 60 minutes (default: 30)
  minDuration?: number;      // Minimum meeting duration in minutes
  maxDuration?: number;      // Maximum meeting duration in minutes
}

interface Calendar {
  name: string;              // Person's name
  color: string;             // Calendar color
  events: CalendarEvent[];   // Their busy times
}

Controls

Display scenario:

  • ←/→ or h/l: Navigate between days
  • n or PageDown: Next week
  • p or PageUp: Previous week
  • t: Jump to today
  • q or Esc: Quit

Meeting picker scenario:

  • Mouse click: Select a free time slot
  • ←/→: Navigate weeks
  • t: Jump to today
  • q or Esc: Cancel selection

Selection Result

interface MeetingSelection {
  startTime: string;  // ISO datetime
  endTime: string;    // ISO datetime
  duration: number;   // Minutes
}

API Usage

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

const result = await pickMeetingTime({
  calendars: [
    { name: "Alice", color: "blue", events: [...] },
    { name: "Bob", color: "green", events: [...] },
  ],
  slotGranularity: 30,
});

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

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

CanvasPurposeScenarios
calendarDisplay calendars, pick meeting timesdisplay, meeting-picker
documentView/edit markdown documentsdisplay, edit, email-preview
flightFlight comparison and seat selectionbooking

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

SkillPurpose
calendarCalendar display and meeting picker details
documentDocument rendering and text selection
flightFlight comparison and seat map details

Document Canvas

Display markdown documents with optional text selection and diff highlighting.

Scenarios

display (default)

Read-only document view with markdown rendering. User can scroll but cannot select text.

bun run src/cli.ts show document --scenario display --config '{
  "content": "# Hello World\n\nThis is **markdown** content.",
  "title": "My Document"
}'

edit

Interactive document view with text selection. User can click and drag to select text, which is sent via IPC in real-time.

  • Renders markdown with syntax highlighting (headers, bold, italic, code, links, lists, blockquotes)
  • Diff highlighting: green background for additions, red for deletions
  • Click and drag to select text
  • Selection automatically sent via IPC
bun run src/cli.ts spawn document --scenario edit --config '{
  "content": "# My Blog Post\n\nThis is the **introduction** to my post.\n\n## Section One\n\n- Point one\n- Point two",
  "title": "Blog Post Draft",
  "diffs": [
    {"startOffset": 50, "endOffset": 62, "type": "add"}
  ]
}'

email-preview

Specialized view for email content display.

bun run src/cli.ts show document --scenario email-preview --config '{
  "content": "Dear Team,\n\nPlease review the attached document.\n\nBest regards,\nAlice",
  "title": "RE: Project Update"
}'

Configuration

interface DocumentConfig {
  content: string;        // Markdown content
  title?: string;         // Document title (shown in header)
  diffs?: DocumentDiff[]; // Optional diff markers for highlighting
  readOnly?: boolean;     // Disable selection (default: false for edit)
}

interface DocumentDiff {
  startOffset: number;    // Character offset in content
  endOffset: number;
  type: "add" | "delete";
}

Markdown Rendering

Supported markdown features:

  • Headers (# H1, ## H2, etc.)
  • Bold (**text**)
  • Italic (*text*)
  • Code (`inline` and fenced blocks)
  • Links ([text](url))
  • Lists (- or * bullets)
  • Blockquotes (>)

Selection Result

interface DocumentSelection {
  selectedText: string;   // The selected text
  startOffset: number;    // Start character offset
  endOffset: number;      // End character offset
  startLine: number;      // Line number (1-based)
  endLine: number;
  startColumn: number;    // Column in start line
  endColumn: number;
}

Controls

  • Mouse click and drag: Select text (edit scenario)
  • ↑/↓ or scroll: Navigate document
  • q or Esc: Close/cancel

API Usage

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

// Display read-only document
await displayDocument({
  content: "# My Document\n\nContent here.",
  title: "View Mode",
});

// Interactive editing with selection
const result = await editDocument({
  content: "# My Document\n\nSelect some **text** here.",
  title: "Edit Mode",
  diffs: [{ startOffset: 20, endOffset: 30, type: "add" }],
});

if (result.success && result.data) {
  console.log(`Selected: "${result.data.selectedText}"`);
  console.log(`Position: ${result.data.startOffset}-${result.data.endOffset}`);
}

Flight Canvas

Cyberpunk-themed flight comparison and seat selection interface.

Scenarios

booking (default)

Interactive flight comparison and seat selection.

  • Shows flight options with airline, times, duration, and price
  • Interactive seat map for seat selection
  • Keyboard navigation between flights and seats
  • Returns selected flight and seat via IPC
bun run src/cli.ts spawn flight --scenario booking --config '{
  "title": "// FLIGHT_BOOKING_TERMINAL //",
  "flights": [
    {
      "id": "ua123",
      "airline": "United Airlines",
      "flightNumber": "UA 123",
      "origin": {
        "code": "SFO",
        "name": "San Francisco International",
        "city": "San Francisco",
        "timezone": "PST"
      },
      "destination": {
        "code": "DEN",
        "name": "Denver International",
        "city": "Denver",
        "timezone": "MST"
      },
      "departureTime": "2026-01-08T12:55:00-08:00",
      "arrivalTime": "2026-01-08T16:37:00-07:00",
      "duration": 162,
      "price": 34500,
      "currency": "USD",
      "cabinClass": "economy",
      "aircraft": "Boeing 737-800",
      "stops": 0,
      "seatmap": {
        "rows": 30,
        "seatsPerRow": ["A", "B", "C", "D", "E", "F"],
        "aisleAfter": ["C"],
        "unavailable": ["1A", "1B", "1C", "1D", "1E", "1F"],
        "premium": ["2A", "2B", "2C", "2D", "2E", "2F"],
        "occupied": ["3A", "3C", "4B", "5D"]
      }
    }
  ]
}'

Configuration

interface FlightConfig {
  flights: Flight[];
  title?: string;           // Header title
  showSeatmap?: boolean;    // Enable seat selection
  selectedFlightId?: string; // Pre-select a flight
}

interface Flight {
  id: string;
  airline: string;          // e.g., "United Airlines"
  flightNumber: string;     // e.g., "UA 123"
  origin: Airport;
  destination: Airport;
  departureTime: string;    // ISO datetime
  arrivalTime: string;      // ISO datetime
  duration: number;         // Minutes
  price: number;            // Cents
  currency: string;         // e.g., "USD"
  cabinClass: "economy" | "premium" | "business" | "first";
  aircraft?: string;        // e.g., "Boeing 737-800"
  stops: number;            // 0 = nonstop
  seatmap?: Seatmap;        // Optional seat selection
}

interface Airport {
  code: string;             // 3-letter code
  name: string;             // Full airport name
  city: string;
  timezone: string;
}

interface Seatmap {
  rows: number;
  seatsPerRow: string[];    // e.g., ["A", "B", "C", "D", "E", "F"]
  aisleAfter: string[];     // e.g., ["C"] = aisle after seat C
  unavailable: string[];    // Blocked seats
  premium: string[];        // Extra legroom/exit row
  occupied: string[];       // Already booked
}

Controls

  • ↑/↓: Navigate between flights
  • Tab: Switch focus between flight list and seatmap
  • ←/→/↑/↓ (in seatmap): Move seat cursor
  • Space: Select/deselect seat
  • Enter: Confirm selection
  • Shift+Enter: Confirm immediately (skip countdown)
  • q or Esc: Cancel

Selection Result

interface FlightResult {
  selectedFlight: Flight;
  selectedSeat?: string;    // e.g., "12A"
}

Seat Legend

  • [ ] - Available seat
  • [X] - Occupied seat
  • [/] - Unavailable/blocked
  • [+] - Premium seat (extra legroom)
  • [*] - Currently selected

API Usage

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

const result = await bookFlight({
  flights: [
    {
      id: "ua123",
      airline: "United Airlines",
      flightNumber: "UA 123",
      origin: { code: "SFO", name: "San Francisco", city: "SF", timezone: "PST" },
      destination: { code: "DEN", name: "Denver", city: "Denver", timezone: "MST" },
      departureTime: "2026-01-08T12:55:00-08:00",
      arrivalTime: "2026-01-08T16:37:00-07:00",
      duration: 162,
      price: 34500,
      currency: "USD",
      cabinClass: "economy",
      stops: 0,
      seatmap: { ... }
    }
  ]
});

if (result.success && result.data) {
  console.log(`Booked: ${result.data.selectedFlight.flightNumber}`);
  console.log(`Seat: ${result.data.selectedSeat}`);
}

Commands 1

Canvas Command

Spawn and control interactive terminal displays (TUIs) in tmux split panes.

Usage

When the user invokes /canvas, help them spawn the appropriate canvas type based on their needs.

Workflow

Step 1: Determine Canvas Type

Ask what kind of canvas the user needs:

  • Calendar - Display events or pick meeting times
  • Document - View or edit markdown content
  • Flight - Compare flights and select seats

Step 2: Gather Configuration

Based on the canvas type, collect the necessary configuration:

Calendar:

  • Events to display (title, start/end times)
  • For meeting picker: multiple calendars with busy times
  • Slot granularity (15/30/60 minutes)

Document:

  • Markdown content to display
  • Document title
  • Edit mode or display-only
  • Optional diff highlighting

Flight:

  • Flight options (airline, times, prices)
  • Seatmap configuration
  • Origin/destination airports

Step 3: Spawn Canvas

Use the CLI to spawn the canvas:

cd ${CLAUDE_PLUGIN_ROOT}
bun run src/cli.ts spawn [type] --scenario [scenario] --config '[json]'

Examples:

# Calendar display
bun run src/cli.ts spawn calendar --config '{"events": [...]}'

# Meeting picker
bun run src/cli.ts spawn calendar --scenario meeting-picker --config '{"calendars": [...]}'

# Document editor
bun run src/cli.ts spawn document --scenario edit --config '{"content": "# Title", "title": "Doc"}'

# Flight booking
bun run src/cli.ts spawn flight --config '{"flights": [...]}'

Step 4: Handle Results

Wait for user interaction and handle the result:

  • Selected: User made a selection (time slot, text, flight+seat)
  • Cancelled: User pressed Escape or quit
  • Error: Something went wrong

Requirements

  • Must be running inside a tmux session
  • Terminal should support mouse input for interactive scenarios

Skills Reference

Read these skills for detailed configuration options:

  • canvas - Overview and IPC communication
  • calendar - Calendar events and meeting picker
  • document - Markdown rendering and text selection
  • flight - Flight comparison and seatmaps

Sponsors

Details

Marketplace
BhalPunia/claude-canvas
Source
canvas
Category
Community