DOCSEARCHbyAlgolia
Submit Docs

Claude Canvas

repository·main·Indexed 23 days ago

https://github.com/dvdsgl/claude-canvas

A TUI toolkit for Claude Code that enables the spawning of interactive terminal interfaces in tmux split panes. It provides components for calendars (display and meeting picking), markdown documents (viewing and editing), and flight booking (comparison and seat selection) using a JSON-based IPC communication protocol. Requires Bun, tmux, and a terminal with mouse support.

Tokens
13.8K
Snippets
32
Records
77
Agent score
80%

What's inside claude-canvas

  1. Use the Document Canvas for markdown content

    main
    The document canvas is used for displaying and editing markdown content. It is ideal for showing documents, emails, or when users need to select text for editing. It supports markdown rendering (headers, bold, italic, code, links, lists, blockquotes) and can include diff highlighting for additions and deletions.

  2. Handle Canvas interaction results

    main

    After spawning a canvas, the system waits for user interaction. You should handle the following result states:

    • Selected: The user successfully made a selection (e.g., a specific time slot, a text selection, or a flight and seat).
    • Cancelled: The user exited the canvas (e.g., by pressing Escape or quitting).
    • Error: An error occurred during the canvas session.

  3. Choose a Document Canvas scenario

    main

    The Document Canvas operates in three distinct scenarios depending on the desired user interaction:

    • display (default): A read-only view with markdown rendering. Users can scroll but cannot select text.
    • edit: An interactive view with text selection. Users can click and drag to select text, which is sent via IPC in real-time. It supports diff highlighting (green for additions, red for deletions).
    • email-preview: A specialized view optimized for displaying email content.

  4. Use the Calendar Canvas for displaying events and picking meetings

    main

    The calendar skill provides a canvas for displaying calendar views and enabling interactive meeting time selection. It supports two primary scenarios:

    1. display (default): A view-only mode where users can navigate weeks but cannot select time slots. Use this for showing a single person's schedule.
    2. meeting-picker: An interactive mode designed for scheduling. It overlays multiple calendars with different colors, allowing users to click on free slots to select a meeting time. The selection is returned via IPC.

    Common use cases include scheduling meetings, finding free time across multiple team members, or viewing personal weekly schedules.

    # Example: Show a view-only calendar
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"}
  ]
}'

# Example: Spawn an interactive meeting picker
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"}
      ]
    }
  ],
  "slotGranularity": 30
}'

  5. Install the Claude Canvas plugin

    main

    You can install the Claude Canvas plugin for Claude Code using two methods:

    1. Directly via plugin directory: Point Claude Code to the plugin directory using the --plugin-dir flag.
    2. Via the Claude Code marketplace: Use the /plugin commands to add and install the package.

    Requirements:

    • tmux: Required for spawning canvas displays in split panes.
    • Bun: Required runtime for executing CLI commands.
    • Terminal with mouse support: Necessary for interactive TUI scenarios.
    # Add as Claude Code plugin
claude --plugin-dir /path/to/claude-canvas/canvas

# Or via marketplace
/plugin marketplace add djsiegel/claude-canvas
/plugin install claude-canvas@canvas

  6. Use Canvas TUI components

    main

    Canvas provides spawnable terminal user interface (TUI) components that support real-time IPC communication. Claude can spawn these components in tmux split panes to allow users to interact with data and make selections.

    Available Canvas Types

    • calendar: Display events and pick meeting times.
    • document: View or edit markdown documents.
    • flight: Compare flights and select seats.

    CLI Usage Examples

    Use the bun run src/cli.ts command to interact with the components:

    • Show calendar in current terminal: bun run src/cli.ts show calendar
    • Spawn meeting picker in tmux split: bun run src/cli.ts spawn calendar --scenario meeting-picker --config '{"calendars": [...]}'
    • Spawn document editor: bun run src/cli.ts spawn document --scenario edit --config '{"content": "# Hello"}'
    # Show calendar in current terminal
bun run src/cli.ts show calendar

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

# Spawn document editor
bun run src/cli.ts spawn document --scenario edit --config '{"content": "# Hello"}'

  7. Install Claude Canvas in Claude Code

    main

    Claude Canvas is a TUI (Terminal User Interface) toolkit that allows Claude Code to spawn interactive terminal interfaces (e.g., for emails, calendars, or flight bookings) in split panes.

    To use Claude Canvas, you must first add the repository as a marketplace in Claude Code and then install the specific canvas plugin.

  8. Use the Flight Canvas for flight comparison and seat selection

    main

    The flight skill provides a cyberpunk-themed interface for browsing flight options and selecting seats. It is designed for scenarios where users need to compare airline details, prices, and durations, or interactively pick a seat from a map.

    Example Prompts

    • "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"

  9. Spawn a Canvas via the CLI

    main

    To spawn an interactive terminal canvas (TUI) in a tmux split pane, use the spawn command from the src/cli.ts entrypoint. You must first change directory to ${CLAUDE_PLUGIN_ROOT}. The command requires a [type] (e.g., calendar, document, flight) and accepts optional --scenario and --config flags. The --config flag must be a JSON string containing the specific configuration for that canvas type.

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

  11. Quick Start with Canvas TUI Toolkit

    main

    The Canvas TUI Toolkit allows Claude to spawn and control interactive terminal displays (TUIs). You can run a canvas directly in your current terminal for viewing, or spawn it in a new tmux split for interactive scenarios.

    Run in current terminal

    Use this to simply display a canvas without interactive control via the main terminal:

    bun run src/cli.ts show [kind]

    Spawn in a new tmux split

    Always use spawn for interactive scenarios to keep the conversation terminal available while the canvas runs in a separate pane:

    bun run src/cli.ts spawn [kind] --scenario [name] --config '[json]'
    # 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 '{...}'

  12. Requirements for running Canvas

    main

    For the Canvas TUI to function correctly, the following environment conditions must be met:

    • tmux: The command must be executed within an active tmux session (it spawns in split panes).
    • Mouse Support: The terminal must support mouse input to enable interactive scenarios.