# @kamiazya/whiteboard

<p align="center">
  <img src="docs/assets/readme-mark.svg" alt="Whiteboard — a hand sketches nodes and edges, AI tidies them into a diagram, and the mark returns" width="264" height="222" />
</p>

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

[![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>*Kept in your browser: 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 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 through the whiteboard extension, picking up what the agent wrote within about half a second.

<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 syncs the Browser Canvas through the whiteboard extension." width="780" />
  <br />
  <sub><i>Diagram drawn with whiteboard itself — its source is <a href="docs/assets/architecture.canvas">architecture.canvas</a>, a JSON Canvas 1.0 document any JSON Canvas-compatible tool can open.</i></sub>
</p>

`@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. Documents live locally in the daemon's data directory (`~/.whiteboard/` by default), reach the browser within about half a second while the daemon runs, and read back 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/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.

</details>

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

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

Add to `~/.codex/config.toml`:

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

</details>

### Gemini CLI

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

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

Add to `~/.gemini/settings.json`:

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

</details>

### 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 the document in the daemon's data directory (`~/.whiteboard` by default); with the web app connected to the daemon (below), open `smoke` in it to see it.

`default` is the segment of the first workspace a data directory gets: it is created the first time anything opens the directory, and it is the workspace the web app opens first. An agent can use it as `workspaceId` without being told anything else; a workspace you create later is addressed by its own id or the segment it was given.

## Connect the web app to your local daemon

Already have the browser canvas open (see [Get started](docs/tutorials/getting-started.md))
and a local daemon running? The hosted app reaches it through the
**whiteboard browser extension** and a native messaging host that
`whiteboard native-host install --json` registers with your browser (run it
from a global install, not `npx`; see
[Get the `whiteboard` command](docs/how-to/connect-to-local-daemon.md#get-the-whiteboard-command)).
The daemon listens on an owner-only local socket and no network port, so no
web page can reach it directly, and nothing needs pasting or approving: once
connected, the tab works on the daemon's workspaces with live sync,
automatic version checkpoints on top of the manual version history the
browser keeps on its own.

- Chrome, Edge, Brave and Firefox are supported; Safari keeps its data in
  the browser for now.
- While releases are `0.0.x` the extension is loaded by hand from a build
  of this repository.
- Prefer a config file over exporting env vars by hand? See
  [Configuration → Config file](docs/reference/configuration.md#config-file-local-daemon)
  for the `.whiteboardrc` / `.whiteboard/config.yaml` auto-load and
  precedence rules.

See [Connect to a local daemon](docs/how-to/connect-to-local-daemon.md) 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.

| Skill | When to use |
|---|---|
| `/drawing-visuals` | When screen layout, structure, flow, or comparison still feels too ambiguous in text alone — start drawing on the canvas together. |
| `/coauthoring-visuals` | A structured loop for evolving visuals with the agent: gather context, structure frame by frame, run fresh-viewer tests on what you draw. |
| `/auditing-workspaces` | Audit a workspace's documents — find empty spatial canvases, near-duplicate paths, and documents with no recorded kind; report cleanup candidates. |

## Example transcript

```text
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({ workspaceId: "default", documentId, mode: "apply", 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({ workspaceId: "default", documentId })

       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

| Topic | Where |
|---|---|
| Local checkout, HTTP MCP development loop, repo-local config override | [docs/contributing/development.md](docs/contributing/development.md) |
| Environment variables, storage layout, Codex sandbox quirks | [docs/reference/configuration.md](docs/reference/configuration.md) |
| Components, data flow, MCP tool surface, design boundaries | [docs/explanation/architecture.md](docs/explanation/architecture.md) |
| Export formats (SVG, OKF Markdown, JSON Canvas) and their tools | [docs/reference/export-formats.md](docs/reference/export-formats.md) |
| MCP debugging workflow (Inspector, `MCP_HTTP_DEBUG`, transport checks) | [docs/contributing/mcp-debugging.md](docs/contributing/mcp-debugging.md) |
| Trust model for all three runtimes (browser, local daemon, server mode) | [docs/explanation/security-model.md](docs/explanation/security-model.md) |
| Connecting a browser tab to a local daemon, moving a browser workspace into it | [docs/how-to/connect-to-local-daemon.md](docs/how-to/connect-to-local-daemon.md) |
| Live-sync message shapes between daemon and browser | [docs/contributing/architecture/wire-protocol.md](docs/contributing/architecture/wire-protocol.md) |
| Test layers, commit conventions, release process | [CONTRIBUTING.md](CONTRIBUTING.md) |

## 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.
- The published `stdio` entry opens the store in its own process: it takes the same automatic History checkpoints and compaction as the daemon. It has no direct path to the browser — `wb_viewport_set` answers `delivered: false`, and the agent-activity highlight and version overlays need the daemon's process — but what it writes still reaches an open tab: the daemon follows the shared record every 500 ms for the workspaces a page is subscribed to (`WHITEBOARD_WORKSPACE_TAIL_MS`), and each process reads through to the record on every access, so the agent also sees what you drew or created.

See [docs/reference/configuration.md](docs/reference/configuration.md#codex-sandbox-constraints) for sandbox quirks.

## License

[Apache-2.0](LICENSE).

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)](https://fsl.software/): 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.