@Kamiazya/Whiteboard

A collaborative Excalidraw canvas for Claude Code, Codex, and Gemini CLI. Draw with your AI agent to align on specs, architecture, and workflows — directly on a shared real-time whiteboard.

npm version License: MIT CI

Start here

whiteboard is a browser-first whiteboard that grows with you: open a canvas in your browser, run it locally for durable private storage, and self-host it for a team when you're ready.

Try it in your browser — no account; your canvas data stays in your own browser. _{Browser-local: runs in your browser, data stays on your machine.} Get started → — runs locally from a checkout today.

▶ Draw with your AI agent

The fastest way to get value today. Claude Code, Codex, or Gemini draw on the canvas alongside you over MCP. _{Local daemon: a server on your own machine.}

→ Get started: Quick install

Self-host for your team — run whiteboard as a shared server behind your own identity provider and TLS. _{Server mode: a shared server you operate.} → Self-host with Docker

How whiteboard works

You and your agent both reach the same Excalidraw canvas — they talk, the agent acts, skills shape the prompts. The kamiazya/whiteboard plugin packages three skills and a Whiteboard MCP server together; the agent calls MCP tools via stdio and the daemon syncs the canvas to your browser over WebSocket.

_{Diagram drawn with whiteboard itself — see architecture.excalidraw to open it in Excalidraw and remix.}

@kamiazya/whiteboard-mcp runs a live Excalidraw canvas in your browser and exposes MCP tools so Claude Code, Codex, Gemini CLI, or any MCP-capable agent can draw, annotate, and refine diagrams alongside you. Canvases live locally under ~/.whiteboard/, sync over WebSocket, and round-trip with stock .excalidraw JSON.

Reach for whiteboard when…

• You're aligning with your agent on a design and text alone keeps drifting. Sketch the request flow once, ask the agent to fill in the missing edges, point at the diagram instead of re-explaining.
• You're reviewing a change and want to mark up the architecture together. Open an existing workspace, ask the agent to add the new path, compare against the previous frame, export a PNG for the PR description.
• You're writing docs or onboarding material and want a reusable diagram. Drive the agent to produce the diagram, save the .excalidraw, drop the PNG into the doc — open it again later in excalidraw.com when something needs updating.

Aligning on a design	Reviewing and marking up	Presenting or sharing
Agent drew it — you guided the layout	You annotated it — review notes on the canvas	Fullscreen mode — clean export for docs

The same workflow works across any scenario — the agent draws boxes, arrows, and labels on a fresh canvas:

_{Auth service flow drawn by the agent — numbered steps, cache callout, color-coded components.}

Quick install

Claude Code

In a Claude Code session, run:

/plugin marketplace add kamiazya/whiteboard
/plugin install whiteboard@whiteboard-marketplace

This installs the MCP server and the bundled /drawing-visuals, /coauthoring-visuals, and /auditing-workspaces skills in one step.

claude mcp add whiteboard -- npx -y @kamiazya/whiteboard-mcp@latest

Codex

In a Codex session, run:

codex plugin marketplace add kamiazya/whiteboard@stable

The @stable pin tracks the latest release instead of the development branch.

Then open /plugins, choose kamiazya Whiteboard → whiteboard → Install plugin, and restart Codex. This installs the MCP server and the bundled skills in one step.

[mcp_servers.whiteboard]
command = "npx"
args = ["-y", "@kamiazya/whiteboard-mcp@latest"]

Gemini CLI

gemini extensions install https://github.com/kamiazya/whiteboard

{
  "mcpServers": {
    "whiteboard": {
      "command": "npx",
      "args": ["-y", "@kamiazya/whiteboard-mcp@latest"]
    }
  }
}

Verify

In your agent session, ask it to call canvas_create({ slug: "smoke" }). The first call opens a Chromium tab pointed at the canvas and creates ~/.whiteboard/{workspaceId}/.

Pair with your local daemon

Already have the browser canvas open (see Get started) and a local daemon running? Ask your AI agent to call the create_pairing_link MCP tool. It mints a #wb= link that carries a short-lived bootstrap token — open it in your browser to connect that tab to the daemon's workspaces, version history, branches, and merge, with live sync over WebSocket.

• Loopback web origins (http://127.0.0.1:...) need no extra configuration.
• HTTPS hosted origins must be added to WHITEBOARD_ALLOWED_WEB_ORIGINS (exact-match, no wildcards) before they can pair. This setting governs local-daemon pairing only; server mode reads the separate WHITEBOARD_SERVER_ALLOWED_ORIGINS variable instead.
• Treat the pairing link like a credential: anyone who has it can pair with your daemon until the token is rotated.
• Prefer a config file over exporting env vars by hand? See Configuration → Config file for the .whiteboardrc / .whiteboard/config.yaml auto-load and precedence rules.

See Connect to a local daemon for the full flow, including copy-first import of browser-local canvases.

Bundled skills

Three opinionated SKILL.md packs ship inside the npm package. The recommended plugin install above wires them up automatically — no manual linking. If you instead used claude mcp add, the Codex CLI snippet, or npx, link them yourself per docs/contributing/development.md#bundled-skills-install.

Example transcript

You    Use whiteboard to sketch the request flow for our auth service:
       client → API gateway → token service → DB. Highlight where caching lives.

Agent  cid = canvas_create({ slug: "auth-flow" }).id
       annotate_batch({ canvasId: cid, annotations: [ /* 4 service boxes + arrows */ ] })
       annotate({ canvasId: cid, type: "text",
                  target: { x: 240, y: 360 },
                  text: "cache lives here" })
       export_canvas({ canvasId: cid, format: "png" })

       Drew a 4-stage flow on the auth-flow canvas. Cache callout placed
       between API gateway and token service. PNG attached.

The agent returns the export_canvas PNG result as an MCP ImageContent, so the next turn can reason about what was actually drawn — closing the loop between prompt and pixels.

Documentation

Limitations

• Live drawing and PNG export require a Chromium browser tab connected over WebSocket.
• The published transport is stdio. The HTTP MCP endpoint (pnpm mcp:http:dev) is for local development.

See docs/reference/configuration.md for sandbox quirks.

License

MIT