Collaborator AI Canvas

---
name: collaborator-ai-canvas
description: Skill for using Collaborator, a native macOS desktop app for agentic development on an infinite canvas with terminals, files, and AI agents.
triggers:
  - "set up collaborator for agentic development"
  - "install collaborator on mac"
  - "use collaborator with AI agents"
  - "open workspace in collaborator"
  - "create terminal tile on canvas"
  - "drag files onto collaborator canvas"
  - "configure collaborator workspace"
  - "run coding agent in collaborator"
---

# Collaborator AI Canvas

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Collaborator is a native macOS desktop application (Apple Silicon only) that provides an infinite canvas where you can arrange terminal sessions, markdown notes, code files, and images side-by-side. It is purpose-built for running AI coding agents (Claude Code, Cursor, Codex, etc.) without context switching.

---

## Installation

### One-line install (recommended)

```sh
curl -fsSL https://raw.githubusercontent.com/collaborator-ai/collab-public/main/install.sh | bash

Manual download

Download the latest .dmg from:

https://github.com/collaborator-ai/collab-public/releases/latest

Requirements: macOS, Apple Silicon (arm64). Intel Macs are not supported.

First Launch Quickstart

1. Open Collaborator from Applications or Spotlight.
2. Add a workspace:
   • Click the workspace dropdown in the top-left navigator sidebar.
   • Choose "Add workspace" and select a local project folder.
   • Keyboard shortcut: Cmd+Shift+O
3. Double-click empty canvas space → creates a terminal tile.
4. Your terminal opens in the workspace directory. Start an agent:

# Example: start Claude Code in your workspace
claude

# Example: start Codex
codex

# Example: run any shell command
npm run dev

5. Drag a file from the navigator sidebar onto the canvas to open it as a tile next to your terminal.

Application Layout

┌──────────────────────────────────────────────────┐
│  Navigator (sidebar)  │  Canvas (infinite)        │
│  ┌─────────────────┐  │  ┌──────┐  ┌──────────┐  │
│  │ Workspace        │  │  │ term │  │ note.md  │  │
│  │ dropdown         │  │  └──────┘  └──────────┘  │
│  ├─────────────────┤  │                            │
│  │ File tree        │  │  ┌──────────┐             │
│  │ (expand/collapse)│  │  │ code.ts  │             │
│  └─────────────────┘  │  └──────────┘             │
└──────────────────────────────────────────────────┘

• Navigator — resizable left sidebar with file tree and workspace switcher.
• Canvas — infinite pan/zoom surface; holds all tiles.
• Viewer — opens when you click a file in the navigator; occupies the main area alongside the canvas.

Canvas Controls

• Zoom range: 33%–100% with rubber-band overshoot.
• All tile positions snap to a dot grid.
• Scroll through a tile without panning: hold Shift while scrolling.

Tile Types

Terminal tile

• Created by double-clicking empty canvas space.
• Backed by a tmux session — persists even if you close and reopen the tile.
• Working directory is set to the active workspace path automatically.
• Use this to run agents, build tools, or any shell commands.

Note tile (Markdown)

• Created by dragging a .md, .mdx, .markdown, or .txt file onto the canvas.
• Rich text editor with live rendering, frontmatter support, cover images, and wiki-style [[links]].

Code tile

• Created by dragging any non-markdown, non-image file onto the canvas.
• Monaco Editor with syntax highlighting and language auto-detection.
• Supports inline editing.

Image tile

• Created by dragging .png, .jpg, .jpeg, .gif, .svg, or .webp onto the canvas.
• Read-only display with metadata.

Workspace Management

Workspace dropdown (top of navigator)
├── Switch to any workspace (click to activate)
├── Add workspace      → Cmd+Shift+O → pick a folder
└── Remove workspace   → removes from list, does NOT delete files

• Each workspace has its own independent file tree.
• The canvas and viewer are shared across workspaces.
• Workspaces are stored by absolute path in ~/.collaborator/config.json.

File Tree Operations

View modes:

• Hierarchical tree
• Chronological feed (sorted by date)

Sort options (cycle through):

• Created: newest / oldest
• Modified: newest / oldest
• Name: A–Z / Z–A

Persistent State Files

All state is stored in ~/.collaborator/. You can inspect or back these up manually.

~/.collaborator/canvas-state.json

{
  "version": 1,
  "tiles": [
    {
      "id": "tile-1742024800000-0",
      "type": "term",
      "x": 120,
      "y": 80,
      "width": 440,
      "height": 540,
      "filePath": null,
      "zIndex": 1
    },
    {
      "id": "tile-1742024900000-1",
      "type": "note",
      "x": 600,
      "y": 80,
      "width": 440,
      "height": 540,
      "filePath": "/Users/you/project/README.md",
      "zIndex": 2
    },
    {
      "id": "tile-1742025000000-2",
      "type": "code",
      "x": 1080,
      "y": 80,
      "width": 600,
      "height": 540,
      "filePath": "/Users/you/project/src/index.ts",
      "zIndex": 3
    }
  ],
  "viewport": {
    "panX": -60,
    "panY": -20,
    "zoom": 0.85
  }
}

• Canvas state saves 500ms after each change (debounced).
• Tiles are saved immediately when created or closed.
• type values: "term", "note", "code", "image"

~/.collaborator/config.json

{
  "workspaces": [
    "/Users/you/projects/my-app",
    "/Users/you/projects/another-project"
  ],
  "active_workspace": 0,
  "window_state": {
    "x": 100,
    "y": 50,
    "width": 1440,
    "height": 900,
    "isMaximized": false
  },
  "ui": {}
}

File Tile Binding Behavior

File tiles track their source file on disk:

This means agents editing files in terminals will be reflected live in open tiles.

Common Agentic Workflows

Pattern 1: Agent + context file side by side

Canvas layout:
┌─────────────────┐  ┌──────────────────────┐
│  Terminal        │  │  CLAUDE.md / spec.md │
│  (claude / codex)│  │  (note tile)         │
└─────────────────┘  └──────────────────────┘

1. Double-click canvas → terminal tile.
2. Drag CLAUDE.md or your spec file onto canvas → note tile.
3. Start agent in terminal; reference the spec in the same view.

Pattern 2: Agent + code file being edited

Canvas layout:
┌─────────────────┐  ┌──────────────────────┐
│  Terminal        │  │  src/main.py         │
│  (agent running) │  │  (code tile, live)   │
└─────────────────┘  └──────────────────────┘

Drag src/main.py onto canvas. As the agent edits it, the code tile updates live.

Pattern 3: Multi-agent setup

Canvas layout:
┌───────────┐  ┌───────────┐  ┌──────────────┐
│ Agent 1   │  │ Agent 2   │  │ notes.md     │
│ (frontend)│  │ (backend) │  │ (shared spec)│
└───────────┘  └───────────┘  └──────────────┘

Each terminal tile has its own independent tmux session. Both agents run concurrently. Pan the canvas to monitor both.

Pattern 4: Reset/restore canvas state manually

# Back up current state
cp ~/.collaborator/canvas-state.json ~/.collaborator/canvas-state.backup.json

# Reset canvas (removes all tiles, resets viewport)
cat > ~/.collaborator/canvas-state.json << 'EOF'
{
  "version": 1,
  "tiles": [],
  "viewport": {
    "panX": 0,
    "panY": 0,
    "zoom": 1.0
  }
}
EOF

Pattern 5: Add a workspace via config (without GUI)

# Add a workspace path directly to config
node -e "
const fs = require('fs');
const path = require('os').homedir() + '/.collaborator/config.json';
const cfg = JSON.parse(fs.readFileSync(path, 'utf8'));
cfg.workspaces.push('/Users/you/projects/new-project');
fs.writeFileSync(path, JSON.stringify(cfg, null, 2));
console.log('Workspace added.');
"

Viewer (File Preview Panel)

Clicking a file in the navigator opens it in the Viewer — a full-featured editor/reader in the main area.

• Viewer watches for external disk changes and reloads automatically.
• Press Escape to close the viewer (when not actively editing).
• Viewer and canvas tiles are independent — the same file can be open in both simultaneously.

Troubleshooting

App won't open / "damaged" warning on macOS

# Remove quarantine flag after manual download
xattr -cr /Applications/Collaborator.app

Terminal tile shows wrong working directory

• Ensure the workspace is set before creating the terminal.
• Close and re-create the terminal tile after switching workspaces.

Tile not reloading after external file change

• Collaborator watches files via the OS. On very large directories, watchers may be exhausted.

# macOS: check and raise fs watcher limit if needed
launchctl limit maxfiles
sudo launchctl limit maxfiles 65536 200000

Canvas state corrupted / app won't load canvas

# Reset canvas state
echo '{"version":1,"tiles":[],"viewport":{"panX":0,"panY":0,"zoom":1.0}}' \
  > ~/.collaborator/canvas-state.json

tmux session persists after tile is closed (intended behavior)

• Terminal tiles bind to tmux sessions that live beyond the tile.
• To list and kill stale sessions:

tmux ls
tmux kill-session -t <session-name>

Reinstall cleanly

# Remove app state (workspaces, canvas, config)
rm -rf ~/.collaborator/

# Reinstall
curl -fsSL https://raw.githubusercontent.com/collaborator-ai/collab-public/main/install.sh | bash

Key Facts for AI Agents

• macOS Apple Silicon only — no Linux, no Windows, no Intel Mac.
• No accounts required — fully local, no cloud sync.
• Anonymous analytics via PostHog (non-identifying).
• Source not public — bug reports go to GitHub Issues.
• State location: ~/.collaborator/
• Canvas tile types: term, note, code, image
• Terminal persistence: tmux (sessions survive tile close/reopen)
• Zoom range: 33%–100%
• Grid snap: all tile positions and sizes snap to dot grid