whiteboard
Collaborative whiteboard for Gemini CLI. Runs a live whiteboard in your browser and exposes MCP tools so Gemini can draw, annotate, and refi
Open source Open in the app JSON README (API)
About
Collaborative whiteboard for Gemini CLI. Runs a live whiteboard in your browser and exposes MCP tools so Gemini can draw, annotate, and refine diagrams alongside you.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- kamiazya
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.0.19
- Stars
- 6
- Forks
- 1
- Open pull requests
- 7
- Last push
- 2026-09-07T17:39:33Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
kamiazya/whiteboard
README
# @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.
[](https://www.npmjs.com/package/@kamiazya/whiteboard-mcp)
[](LICENSE)
[](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 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 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.
<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 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_document_create({ workspaceId: "default", 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](docs/tutorials/getting-started.md))
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](docs/how-to/self-host-with-docker.md)
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](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 existing workspaces — detect orphaned workspaces, tombstone-heavy canvases, and cache/disk mismatches; 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 { canvasId } = wb_document_create({ workspaceId: "default",
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
| Topic | Where |
|---|---|
| Local checkout, HTTP MCP development loop, repo-local config override, skill linking | [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) |
| Pairing 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) |
| WebSocket 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.
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.