Spawn and control interactive terminal displays (calendars, documents, flights) with real-time IPC communication
- version
- 0.1.0
- GitHub stars
- 48
Install
/plugin install canvas@claude-canvasRun it inside Claude Code after adding the marketplace with /plugin marketplace add BEARLY-HODLING/claude-canvas.
Contents
Discovered from sourceSkills 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:
←/→orh/l: Navigate between daysnorPageDown: Next weekporPageUp: Previous weekt: Jump to todayqorEsc: Quit
Meeting picker scenario:
- Mouse click: Select a free time slot
←/→: Navigate weekst: Jump to todayqorEsc: 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
| Canvas | Purpose | Scenarios |
|---|---|---|
calendar | Display calendars, pick meeting times | display, meeting-picker |
document | View/edit markdown documents | display, edit, email-preview |
flight | Flight comparison and seat selection | booking |
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
| Skill | Purpose |
|---|---|
calendar | Calendar display and meeting picker details |
document | Document rendering and text selection |
flight | Flight 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 documentqorEsc: 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 flightsTab: Switch focus between flight list and seatmap←/→/↑/↓(in seatmap): Move seat cursorSpace: Select/deselect seatEnter: Confirm selectionShift+Enter: Confirm immediately (skip countdown)qorEsc: 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 communicationcalendar- Calendar events and meeting pickerdocument- Markdown rendering and text selectionflight- Flight comparison and seatmaps
Sponsors
Details
- Marketplace
- BEARLY-HODLING/claude-canvas
- Source
- canvas
- Category
- Community
