# canvas

> Launch and manage interactive terminal canvases (document, calendar, flight) in tmux split panes. Use when the user wants to display markdown documents, calendars, or flight booking interfaces in a side panel. Supports real-time updates via IPC.

- Author: mark-a-12
- Repository: mark-a-12/panels
- Version: 20260126021713
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/mark-a-12/panels
- Web: https://mule.run/skillshub/@@mark-a-12/panels~canvas:20260126021713

---

---
name: canvas
description: Launch and manage interactive terminal canvases (document, calendar, flight) in tmux split panes. Use when the user wants to display markdown documents, calendars, or flight booking interfaces in a side panel. Supports real-time updates via IPC.
---

# Canvas Skill

Spawn and control interactive terminal displays (TUIs) in tmux split panes with IPC support for real-time updates.

## Quick Reference

### Canvas Types
- **document** - Markdown viewer/editor
- **calendar** - Event display or meeting picker
- **flight** - Flight comparison and seat selection

## Workflow

### Step 1: Determine Canvas Type

If not specified, ask what kind of canvas the user needs:
- Document for markdown content
- Calendar for events/meetings
- Flight for travel booking

### Step 2: Launch Canvas with IPC

**Always use this pattern for editable canvases:**

```bash
# 1. Write config to temp file (avoids JSON escaping issues)
cat > /tmp/canvas-config-<id>.json << 'EOF'
{"content": "# Your Markdown\n\nContent here.", "title": "Title"}
EOF

# 2. Launch with --id and --socket (REQUIRED for updates)
tmux split-window -d -h "cd ~/.claude/plugins/cache/claude-canvas/canvas/0.1.0 && bun run src/cli.ts show document --id <id> --socket /tmp/canvas-<id>.sock --config \"\$(cat /tmp/canvas-config-<id>.json)\""
```

**Critical flags:**
- `-d` - Don't steal focus from Claude Code
- `-h` - Horizontal split (canvas on right)
- `--id <name>` - Unique identifier (required for IPC)
- `--socket /tmp/canvas-<name>.sock` - Unix socket path (required for IPC)

### Step 3: Update Canvas Content

To modify a running canvas:

```bash
# 1. Write new config
cat > /tmp/canvas-update-<id>.json << 'EOF'
{"content": "# Updated Content\n\nNew markdown here."}
EOF

# 2. Send update via IPC
cd ~/.claude/plugins/cache/claude-canvas/canvas/0.1.0
bun run src/cli.ts update <id> --config "$(cat /tmp/canvas-update-<id>.json)"
```

### Step 4: Query Canvas State

```bash
cd ~/.claude/plugins/cache/claude-canvas/canvas/0.1.0

# Get current content
bun run src/cli.ts content <id>

# Get current selection
bun run src/cli.ts selection <id>
```

## Canvas Configurations

### Document Canvas
```json
{
  "content": "# Markdown Content\n\nWith **formatting**.",
  "title": "Document Title"
}
```

### Calendar Canvas
```json
{
  "events": [
    {
      "title": "Meeting",
      "start": "2026-01-11T10:00",
      "end": "2026-01-11T11:00"
    }
  ]
}
```

### Flight Canvas
```json
{
  "flights": [
    {
      "airline": "UA",
      "departure": "SFO",
      "arrival": "JFK",
      "price": 350
    }
  ]
}
```

## Prerequisites Check

Before launching, verify:

1. **In tmux session:**
   ```bash
   echo $TMUX  # Should show tmux socket path
   ```

2. **Dependencies installed:**
   ```bash
   cd ~/.claude/plugins/cache/claude-canvas/canvas/0.1.0
   bun install  # Run once if "Cannot find package" errors
   ```

## Common Issues

### Canvas exits immediately
- Check for "Raw mode not supported" - must use tmux split, not background `&`
- Run `bun install` in canvas directory if missing dependencies

### Update doesn't change canvas
- Canvas must be launched with `--id` and `--socket` flags
- Socket path must match: `/tmp/canvas-<id>.sock`

### Focus stolen from Claude Code
- Add `-d` flag to `tmux split-window`

### JSON parse errors
- Use temp files instead of inline JSON
- Escape properly: `\n` for newlines in JSON strings

## Controls

- **Arrow keys** - Scroll content
- **q** or **Escape** - Close canvas

## Example: Full Workflow

```bash
# Launch editable document
cat > /tmp/canvas-config-notes.json << 'EOF'
{"content": "# Meeting Notes\n\n- Item 1\n- Item 2", "title": "Notes"}
EOF

tmux split-window -d -h "cd ~/.claude/plugins/cache/claude-canvas/canvas/0.1.0 && bun run src/cli.ts show document --id notes --socket /tmp/canvas-notes.sock --config \"\$(cat /tmp/canvas-config-notes.json)\""

# Wait for socket
sleep 1

# Update content
cat > /tmp/canvas-update-notes.json << 'EOF'
{"content": "# Meeting Notes - Updated\n\n- Item 1\n- Item 2\n- Item 3 (new)"}
EOF

cd ~/.claude/plugins/cache/claude-canvas/canvas/0.1.0
bun run src/cli.ts update notes --config "$(cat /tmp/canvas-update-notes.json)"
```

## Architecture

- Canvas runs as IPC **server** on Unix socket
- `update` command connects as **client**, sends config, disconnects
- Socket convention: `/tmp/canvas-<id>.sock`
- The `--id` flag links spawn and update commands