Spawn and control interactive terminal displays (calendars, documents, flights) with real-time IPC communication
- version
- 0.2.10
Install
/plugin install canvas@claude-canvasRun it inside Claude Code after adding the marketplace with /plugin marketplace add victorstein/claude-canvas.
Contents
Discovered from sourceSkills 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
| Key | Action |
|---|---|
| Tab | Switch to next agent tab |
| 1-9 | Jump to agent by number |
| ↑/↓ | Scroll content up/down |
| PgUp/PgDn | Fast scroll (10 lines) |
| g | Jump to top |
| G | Jump to bottom |
| q/Esc | Close 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:
- Output Stream: Text output from the agent's thinking and responses
- Tool Calls: Each tool invocation with:
- Tool name (highlighted in cyan)
- Input parameters (truncated preview)
- Status icon (✓ success, ✗ error, ⋯ pending)
- Result (if available)
- 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:
←/→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.
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
| 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
- tmux: Canvas spawning requires a tmux session
- Terminal with mouse support: For click-based interactions
- Bun: Runtime for executing canvas commands
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.
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 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.
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 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
- victorstein/claude-canvas
- Source
- canvas
- Category
- Community
