agent-canvas

agent-canvas

A Claude Code channel plugin that gives a running session a live browser UI. The agent drives it via the canvas CLI; the browser updates instantly via SSE.

Requirements

Runtime tools (assumed present, not auto-installed):

• bun — channel server runtime
• jq — used by the canvas CLI for JSON manipulation
• curl — used by the canvas CLI to ping the server
• Tailscale — for the FQDN URL (optional; falls back to localhost)

Single-user infrastructure: not bundled with install scripts.

Install

claude plugin marketplace add frankjoshua/agent-canvas
claude plugin install agent-canvas

This installs the channel plugin, MCP server, and /canvas skill. No other setup needed.

Optionally create .canvas/ui-default.json in your project to define a starting layout.

Updating after pulling new code

The plugin runtime loads from a versioned cache (~/.claude/plugins/cache/agent-canvas/agent-canvas/<version>/), not directly from this repo. After pulling changes (git pull in ~/.claude/plugins/marketplaces/agent-canvas/), refresh the cache so live sessions see the new code:

claude plugin update agent-canvas

Or, if that doesn't pick up local changes, sync manually:

rsync -a --delete \
  --exclude=node_modules --exclude='.git' --exclude='.worktrees' --exclude='.canvas' \
  ~/.claude/plugins/marketplaces/agent-canvas/ \
  ~/.claude/plugins/cache/agent-canvas/agent-canvas/0.0.1/

Then restart your Claude Code session (cl) — the new code attaches at session startup.

Agent usage

Agents update the UI via scripts/canvas.sh. See skills/canvas/SKILL.md for the full command reference. Quick example:

CANVAS="$HOME/.claude/plugins/marketplaces/agent-canvas/scripts/canvas.sh"
bash "$CANVAS" init --title "My Page"
bash "$CANVAS" html status "<span class='badge'>Running</span>"

The channel attaches automatically when you start Claude Code with --channels plugin:agent-canvas@agent-canvas-marketplace --dangerously-load-development-channels (channels are in research preview).

Network access

The server binds to 0.0.0.0 by default — accessible from any device on the same network (phones, tablets, other machines via Tailscale, etc.). Override with CANVAS_HOST if needed.

State file

Create .canvas/ui-state.json in your project:

{
  "version": 1,
  "title": "My Dashboard",
  "theme": "dark",
  "layout": "stack",
  "components": [
    {
      "id": "greeting",
      "type": "html",
      "content": "<div class='card bg-base-200'><div class='card-body'><h2 class='card-title'>Hello</h2><p>Edit this file to update the UI.</p></div></div>"
    }
  ]
}

Component types

• html -- raw HTML with full DaisyUI + Tailwind classes
• markdown -- renders markdown to HTML, supports raw HTML passthrough
• form -- structured input form, submissions flow back as channel events
• log -- scrolling append-only log panel

User interaction

Add data-input-event to any element in an html component to make it interactive:

<button class="btn btn-primary" data-input-event="confirm">Confirm</button>

Clicks send a channel event to Claude with the event name and parent component ID.

Multiple instances

Each session gets its own port. The URL is printed to stderr and injected into the Claude Code session on startup.