@kamiazya/whiteboard

A collaborative whiteboard 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 canvas.

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. Kept in your browser: 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

Related MCP server: Excalidraw MCP App Server

How whiteboard works

You and your agent both reach the same whiteboard — 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.

@kamiazya/whiteboard-mcp runs a spatial canvas editor 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 are stored as OKF Markdown or JSON Canvas 1.0 — both round-trip losslessly through the same codec that exports the PNG/SVG images on this page.

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, drop the exported PNG into the doc, and keep the canvas itself around to reopen and update later.

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

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

Starts the MCP server only — the /drawing-visuals, /coauthoring-visuals, and /auditing-workspaces skills are not installed this way, and there is no manual step that adds them: they are carried by the plugin, not by the npm package. Use the plugin install above if you want them.

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.

Add to ~/.codex/config.toml:

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

Starts the MCP server only — the /drawing-visuals, /coauthoring-visuals, and /auditing-workspaces skills are not installed this way, and there is no manual step that adds them: they are carried by the plugin, not by the npm package. Use the plugin install above if you want them.

Gemini CLI

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

Add to ~/.gemini/settings.json:

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

Starts the MCP server only — the /drawing-visuals, /coauthoring-visuals, and /auditing-workspaces skills are not installed this way, and there is no manual step that adds them: they are carried by the plugin, not by the npm package. Use the plugin install above if you want them.

Verify

In your agent session, ask it to call wb_workspace_edit({ workspaceId: "default", ops: [{ op: "document.create", path: "smoke", kind: "spatial" }] }). The call creates ~/.whiteboard/{workspaceId}/; open http://127.0.0.1:<port>/w/{workspaceId}/d/smoke in a browser tab to see it.

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 wb_pairing_link_create MCP tool. It mints a #wb= link that carries the daemon's bootstrap token — the same full-authority credential that authenticates every /api/* request, valid until it is rotated, not a short-lived or single-use token — open it in your browser to connect that tab to the daemon's workspaces — with live sync over WebSocket, automatic version checkpoints and thumbnails on top of the manual version history the browser keeps on its own.

• Loopback web origins (http://127.0.0.1:...) need no extra configuration.

• The official hosted web app (https://kamiazya-whiteboard.pages.dev) can pair out of the box; other HTTPS hosted origins must be added to WHITEBOARD_ALLOWED_WEB_ORIGINS (which, when set, replaces that default). 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 moving a workspace this browser keeps — history, identity, and images intact — into the daemon.

Bundled skills

Three opinionated SKILL.md packs ship with the plugin, which wires them up automatically. They are not part of the @kamiazya/whiteboard-mcp npm package, so the MCP-only routes above (claude mcp add, the Codex CLI snippet, npx, the Gemini mcpServers entry) start the server without them.

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  { results: [{ documentId }] } = wb_workspace_edit({ workspaceId: "default",
         ops: [{ op: "document.create", path: "auth-flow", kind: "spatial" }] })
       wb_canvas_edit({ canvasId, ops: [
         /* 4 service boxes, the arrows between them, and: */
         { op: "node.add", node: { id: "cache-note", type: "text",
                                   text: "cache lives here" } },
         { op: "tidy" },
       ] })
       wb_scene_render({ canvasId })

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

The agent returns the wb_scene_render result so the next turn can reason about what was actually drawn — closing the loop between prompt and pixels.

Documentation

Limitations

• No MCP tool currently returns a raster (PNG) image or ImageContent — wb_scene_render is the closest equivalent for handing a rendered canvas back to an LLM.

• 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

Apache-2.0.

The whole codebase lives in this public monorepo. Today every package is Apache-2.0. The relicense applies to this source tree and to releases made from it going forward; npm versions published before the switch remain MIT-licensed. When the managed-hosting (SaaS) composition layer lands, only that layer — the Cloudflare Workers app and its Cloudflare-specific storage adapters — will be published under the Fair Source License (FSL-1.1-Apache-2.0): free to self-host and use internally, not usable to offer a competing hosted service, and automatically becoming Apache-2.0 two years after each release. Everything else stays Apache-2.0.

The project name and logo are not licensed for use in third-party commercial hosting offerings.