@kamiazya/whiteboard

# @kamiazya/whiteboard

> A collaborative OpenCanvas 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.

[![npm version](https://img.shields.io/npm/v/@kamiazya/whiteboard-mcp.svg)](https://www.npmjs.com/package/@kamiazya/whiteboard-mcp)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
[![CI](https://github.com/kamiazya/whiteboard/actions/workflows/ci.yml/badge.svg)](https://github.com/kamiazya/whiteboard/actions/workflows/ci.yml)

## 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. <sub>*Browser-local: runs in your browser, data stays on your machine.*</sub>
*[Get started →](docs/tutorials/getting-started.md) — 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. <sub>*Local daemon: a server on your own machine.*</sub>

**→ [Get started: Quick install](#quick-install)**

---

**Self-host for your team** — run whiteboard as a shared server behind your own
identity provider and TLS. <sub>*Server mode: a shared server you operate.*</sub>
→ [Self-host with Docker](docs/how-to/self-host-with-docker.md)

## How whiteboard works

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

<p align="center">
  <img src="docs/assets/architecture.png" alt="Architecture diagram: Skills and Whiteboard MCP are packaged in the kamiazya/whiteboard Plugin. You and Agent (Claude/Codex/Gemini) interact via prompts/replies; Agent calls Whiteboard MCP via stdio; MCP controls the Browser Canvas via HTTP/WS." width="780" />
  <br />
  <sub><i>Diagram drawn with whiteboard itself — see <a href="docs/assets/architecture.canvas">architecture.canvas</a> to open it as a JSON Canvas document and remix.</i></sub>
</p>

`@kamiazya/whiteboard-mcp` runs an OpenCanvas spatial 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.

<p align="center">
  <img src="docs/assets/canvas-browser-ui.png" alt="The browser canvas: workspace and canvas selector in the top bar, live diagram synced from the agent in real time" width="780" />
</p>

## 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.

| Aligning on a design | Reviewing and marking up | Presenting or sharing |
|:---:|:---:|:---:|
| ![Agent drew the architecture diagram](docs/assets/canvas-agent-drew.png) | ![Review notes added by the user](docs/assets/canvas-user-annotated.png) | ![Chrome-free canvas render](docs/assets/canvas-presentation.png) |
| **Agent drew it** — you guided the layout | **You annotated it** — review notes on the canvas | **Chrome-free render** — clean export for docs |

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

<p align="center">
  <img src="docs/assets/canvas-auth-flow.png" alt="Auth service request flow: client → API Gateway → Token Service → Database, with Redis Cache path shown" width="640" />
  <br />
  <sub><i>Auth service flow drawn by the agent — numbered steps, cache callout, color-coded components.</i></sub>
</p>

## 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.

<details>
<summary>MCP only (no skills)</summary>

```bash
claude mcp add whiteboard -- npx -y @kamiazya/whit

... (truncated)