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

version
0.2.10

Install

/plugin install canvas@claude-canvas

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

Contents

Discovered from source

Skills 5

Agent Monitor Canvas

Displays real-time sub-agent activity with:

  • Tabbed interface (one tab per agent)
  • Scrollable output streams
  • Tool call display with results
  • Git diff visualization

Auto-Spawn Behavior

The monitor automatically spawns as soon as Claude Code dispatches any sub-agent using the Task tool. It uses Claude Code hooks to detect agent lifecycle events:

  • PreToolUse hook: Detects when Task tool is invoked
  • SubagentStop hook: Tracks when agents complete

Manual Usage

# Show agent monitor in current terminal
bun run src/cli.ts show agent-monitor --scenario monitor

# Spawn agent monitor in a new WezTerm/tmux pane
bun run src/cli.ts spawn agent-monitor --scenario monitor

# With initial configuration
bun run src/cli.ts spawn agent-monitor --scenario monitor --config '{
  "parentSessionId": "session-123",
  "agents": {}
}'

Keyboard Controls

KeyAction
TabSwitch to next agent tab
1-9Jump to agent by number
↑/↓Scroll content up/down
PgUp/PgDnFast scroll (10 lines)
gJump to top
GJump to bottom
q/EscClose monitor

Status Indicators

Each tab shows a status indicator:

  • 🟡 Yellow: Agent is running
  • 🟢 Green: Agent completed successfully
  • 🔴 Red: Agent encountered an error

Content Display

For each agent, the monitor displays:

  1. Output Stream: Text output from the agent's thinking and responses
  2. Tool Calls: Each tool invocation with:
    • Tool name (highlighted in cyan)
    • Input parameters (truncated preview)
    • Status icon (✓ success, ✗ error, ⋯ pending)
    • Result (if available)
  3. Git Diffs: File changes with syntax highlighting:
    • Green for additions (+)
    • Red for deletions (-)
    • Cyan for hunk headers (@@)

Configuration

interface AgentMonitorConfig {
  parentSessionId: string;
  agents: Record<string, AgentState>;
}

interface AgentState {
  id: string;                    // Unique agent identifier
  description: string;           // Task description
  status: "running" | "completed" | "error";
  startTime: number;             // Unix timestamp
  endTime: number | null;
  toolCalls: ToolCallRecord[];
  gitDiffs: DiffRecord[];
  output: string[];
}

Hook Configuration

The plugin uses the following hooks (defined in hooks/hooks.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/src/hooks/pre-tool-use.ts\""
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/src/hooks/subagent-stop.ts\""
          }
        ]
      }
    ]
  }
}

Tracking File

Agent state is stored in /tmp/claude-agents-{session}.json and includes:

  • Parent session ID
  • Canvas pane ID (when spawned)
  • Socket path for IPC
  • All tracked agents with their current state

Example Prompts

  • "Run these three tasks in parallel and show me the monitor"
  • "I want to see what the sub-agents are doing"
  • "Open the agent activity viewer"

Calendar Canvas

Display calendar views and enable interactive meeting time selection.

Example Prompts

Try asking Claude:

  • "Schedule a 30-minute meeting with Alice and Bob sometime next week"
  • "Find a time when the engineering team is all free on Tuesday"
  • "Show me my calendar for this week"
  • "When is everyone available for a 1-hour planning session?"
  • "Block off 2-4pm on Friday for focused work"

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.

Example Prompts

Try asking Claude things like:

Calendar:

  • "Schedule a meeting with the team next week"
  • "Find a time when Alice and Bob are both free"

Document:

  • "Draft an email to the sales team about the new feature"
  • "Help me edit this document — let me select what to change"

Flight:

  • "Find flights from SFO to Denver next Friday"
  • "Book me a window seat on the morning flight"

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

  • tmux: Canvas spawning requires a tmux session
  • Terminal with mouse support: For click-based interactions
  • Bun: Runtime for executing canvas commands

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.

Example Prompts

Try asking Claude:

  • "Draft an email to the marketing team about the Q1 product launch"
  • "Help me edit this blog post — show it so I can highlight the parts to revise"
  • "Write a project proposal and let me review it"
  • "Show me the README so I can select sections to update"
  • "Compose a response to this customer complaint"

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.

Example Prompts

Try asking Claude:

  • "Find flights from San Francisco to Denver on January 15th"
  • "Book me a window seat on the cheapest nonstop to NYC"
  • "Compare morning flights from LAX to Seattle next Monday"
  • "I need a business class seat to Chicago with extra legroom"
  • "Show me United flights to Boston under $300"

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
victorstein/claude-canvas
Source
canvas
Category
Community