/collab-canvas

Collaborator Canvas

Control Collaborator's spatial canvas from the terminal using the `collab-canvas` CLI. The canvas is a pannable, zoomable surface where tiles display terminals, files, images, and graphs.

Coordinate System

All positions and sizes use **grid units**. One grid unit = 20 pixels. Origin (0,0) is the top-left corner. X increases rightward, Y increases downward.

Tile Types

| Type | Use for | Default size (w x h) | |---------|----------------------------------|-----------------------| | `term` | Terminal / shell session | 20 x 25 | | `note` | Markdown files (.md) | 22 x 27 | | `code` | Source code files | 22 x 27 | | `image` | Images (.png, .jpg, .gif, .webp) | 14 x 14 | | `graph` | .graph.json or folder graphs | 30 x 25 |

Type is inferred from the file when `--file` is used:

• `.md`, `.txt` -> `note`
• `.graph.json` -> `graph`
• `.png`, `.jpg`, `.gif`, `.svg`, `.webp` -> `image`
• Directories -> `graph`
• Everything else -> `code`

Commands

collab-canvas tile list

List all tiles on the canvas. Returns JSON array with id, type, position, size, and file path for each tile.

collab-canvas tile list

collab-canvas tile create

Create a new tile on the canvas.

collab-canvas tile create <type> [--file <path>] [--pos x,y] [--size w,h]

• `<type>`: term, note, code, image, or graph
• `--file <path>`: file to display (required for note, code, image, graph; omit for term)
• `--pos x,y`: position in grid units (default: viewport center)
• `--size w,h`: size in grid units (default: per-type default above)

Returns the new tile's ID on stdout.

**Examples:**

# Open a terminal at position (5, 5)
collab-canvas tile create term --pos 5,5

# Open a markdown file with default placement
collab-canvas tile create note --file ./README.md

# Open a graph file at a specific position and size
collab-canvas tile create graph --file ./entities.graph.json --pos 25,0 --size 35,30

collab-canvas tile rm

Remove a tile from the canvas.

collab-canvas tile rm <id>

collab-canvas tile move

Reposition a tile.

collab-canvas tile move <id> --pos x,y

collab-canvas tile resize

Resize a tile.

collab-canvas tile resize <id> --size w,h

collab-canvas tile focus

Pan and zoom the viewport to bring one or more tiles into view, then flash their focus rings.

collab-canvas tile focus <id> [<id>...]

**Examples:**

# Focus a single tile
collab-canvas tile focus tile-abc123

# Focus multiple tiles (viewport zooms to fit all)
collab-canvas tile focus tile-abc123 tile-def456

collab-canvas terminal write

Send input to a terminal tile. The tile must be of type `term` with an active PTY session.

collab-canvas terminal write <id> <input>

**Examples:**

# Run a command in a terminal tile
collab-canvas terminal write tile-abc123 $'ls -la\n'

# Launch Claude Code in headless JSON mode
collab-canvas terminal write tile-abc123 $'claude -p "fix the bug" --output-format json\n'

collab-canvas terminal read

Read recent output from a terminal tile. Returns raw terminal output from the PTY session's ring buffer.

collab-canvas terminal read <id> [--lines N]

• `--lines N`: number of lines to capture (default: 50)

Composition Patterns

Side-by-side comparison

Two files next to each other for comparison.

collab-canvas tile create code --file ./old.ts --pos 0,0
collab-canvas tile create code --file ./new.ts --pos 23,0

Research workspace

Knowledge graph on the left, notes on the right, terminal below.

collab-canvas tile create graph --file ./research.graph.json --pos 0,0 --size 30,25
collab-canvas tile create note --file ./notes.md --pos 31,0
collab-canvas tile create term --pos 0,26

Dashboard layout

Multiple views arranged in a grid.

collab-canvas tile create graph --file ./entities.graph.json --pos 0,0 --size 30,25
collab-canvas tile create note --file ./log.md --pos 31,0
collab-canvas tile create note --file ./report.md --pos 31,14
collab-canvas tile create term --pos 0,26

Focus view

Single tile centered with generous size.

collab-canvas tile create code --file ./main.ts --pos 5,2 --size 40,35

Agent in a terminal

Launch a Claude Code instance in a terminal tile for the human to observe.

# Create terminal, wait for PTY, then launch agent
collab-canvas tile create term --pos 0,0
# (use tile list to get the tile ID, then)
collab-canvas terminal write <id> $'claude -p "summarize this project" --output-format json\n'
# Read the result when done
collab-canvas terminal read <id> --lines 100

Conventions

1. **Always `tile list` first** to see what's already on the canvas before creating tiles. 2. **Use `tile focus` to frame** after arranging tiles so the user can see them. 3. **Clean up when done**: remove tiles you created when they're no longer needed. 4. **Leave 1 grid unit gap** between adjacent tiles for visual clarity. 5. **File tiles auto-refresh**: when you write to a file that has a tile, the tile updates automatically. No need to close and reopen. 6. **Graph tiles support incremental updates**: append nodes to a `.graph.json` file and the graph tile smoothly incorporates them. 7. **Terminal tiles need time to initialize**: after `tile create term`, wait a few seconds before `terminal write` so the PTY session can start.

Setup

The `collab-canvas` CLI is installed to `~/.local/bin/`. If the command is not found, the user needs to add it to their PATH:

export PATH="$HOME/.local/bin:$PATH"

Add this to `~/.zshrc` (macOS) or `~/.bashrc` (Linux) to persist across sessions.

Exit Codes

| Code | Meaning | |------|--------------------------------------------| | 0