{ "markdown": "# @kamiazya/whiteboard\n\n

\n \"Whiteboard\n

\n\n> 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.\n\n[![npm version](https://img.shields.io/npm/v/@kamiazya/whiteboard-mcp.svg)](https://www.npmjs.com/package/@kamiazya/whiteboard-mcp)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)\n[![CI](https://github.com/kamiazya/whiteboard/actions/workflows/ci.yml/badge.svg)](https://github.com/kamiazya/whiteboard/actions/workflows/ci.yml)\n\n## Start here\n\nwhiteboard is a **browser-first whiteboard that grows with you**: open a canvas in\nyour browser, run it locally for durable private storage, and self-host it for a\nteam when you're ready.\n\n**Try it in your browser** — no account; your canvas data stays in your own\nbrowser. *Kept in your browser: runs in your browser, data stays on your machine.*\n*[Get started →](docs/tutorials/getting-started.md) — runs locally from a checkout today.*\n\n### ▶ Draw with your AI agent\n\nThe fastest way to get value today. Claude Code, Codex, or Gemini draw on the\ncanvas alongside you over MCP. *Local daemon: a server on your own machine.*\n\n**→ [Get started: Quick install](#quick-install)**\n\n---\n\n**Self-host for your team** — run whiteboard as a shared server behind your own\nidentity provider and TLS. *Server mode: a shared server you operate.*\n→ [Self-host with Docker](docs/how-to/self-host-with-docker.md)\n\n## How whiteboard works\n\nYou 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.\n\n

\n \"Architecture\n
\n Diagram drawn with whiteboard itself — see architecture.canvas to open it as a JSON Canvas document and remix.\n

\n\n`@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.\n\n

\n \"The\n

\n\n## Reach for whiteboard when…\n\n- **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.\n- **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.\n- **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.\n\n| Aligning on a design | Reviewing and marking up | Presenting or sharing |\n|:---:|:---:|:---:|\n| ![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) |\n| **Agent drew it** — you guided the layout | **You annotated it** — review notes on the canvas | **Chrome-free render** — clean export for docs |\n\nThe same workflow works across any scenario — the agent draws boxes, arrows, and labels on a fresh canvas:\n\n

\n \"Auth\n
\n Auth service flow drawn by the agent — numbered steps, cache callout, color-coded components.\n

\n\n## Quick install\n\n### Claude Code\n\nIn a Claude Code session, run:\n\n```\n/plugin marketplace add kamiazya/whiteboard\n/plugin install whiteboard@whiteboard-marketplace\n```\n\nThis installs the MCP server **and** the bundled `/drawing-visuals`, `/coauthoring-visuals`, and `/auditing-workspaces` skills in one step.\n\n
\nMCP only (no skills)\n\n```bash\nclaude mcp add whiteboard -- npx -y @kamiazya/whiteboard-mcp@latest\n```\n\n> 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.\n\n
\n\n### Codex\n\nIn a Codex session, run:\n\n```\ncodex plugin marketplace add kamiazya/whiteboard@stable\n```\n\nThe `@stable` pin tracks the latest release instead of the development branch.\n\nThen open `/plugins`, choose **kamiazya Whiteboard → whiteboard → Install plugin**, and restart Codex. This installs the MCP server **and** the bundled skills in one step.\n\n
\nMCP only (no skills)\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.whiteboard]\ncommand = \"npx\"\nargs = [\"-y\", \"@kamiazya/whiteboard-mcp@latest\"]\n```\n\n> 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.\n\n
\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/kamiazya/whiteboard\n```\n\n
\nMCP only (no extension)\n\nAdd to `~/.gemini/settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"whiteboard\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@kamiazya/whiteboard-mcp@latest\"]\n }\n }\n}\n```\n\n> 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.\n\n
\n\n### Verify\n\nIn 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:/w/{workspaceId}/d/smoke` in a browser tab to see it.\n\n## Pair with your local daemon\n\nAlready have the browser canvas open (see [Get started](docs/tutorials/getting-started.md))\nand a local daemon running? Ask your AI agent to call the `wb_pairing_link_create`\nMCP tool. It mints a `#wb=` link that carries the daemon's bootstrap token —\nthe same full-authority credential that authenticates every `/api/*` request,\nvalid until it is rotated, not a short-lived or single-use token — open it in\nyour browser to connect that tab to the daemon's workspaces — with live sync\nover WebSocket, automatic version checkpoints and thumbnails on top of the\nmanual version history the browser keeps on its own.\n\n- Loopback web origins (`http://127.0.0.1:...`) need no extra configuration.\n- The official hosted web app (`https://kamiazya-whiteboard.pages.dev`) can\n pair out of the box; other HTTPS hosted origins must be added to\n `WHITEBOARD_ALLOWED_WEB_ORIGINS` (which, when set, replaces that default). This setting governs\n local-daemon pairing only; [server mode](docs/how-to/self-host-with-docker.md)\n reads the separate `WHITEBOARD_SERVER_ALLOWED_ORIGINS` variable instead.\n- Treat the pairing link like a credential: anyone who has it can pair with\n your daemon until the token is rotated.\n- Prefer a config file over exporting env vars by hand? See\n [Configuration → Config file](docs/reference/configuration.md#config-file-local-daemon)\n for the `.whiteboardrc` / `.whiteboard/config.yaml` auto-load and\n precedence rules.\n\nSee [Connect to a local daemon](docs/how-to/connect-to-local-daemon.md) for\nthe full flow, including moving a workspace this browser keeps — history,\nidentity, and images intact — into the daemon.\n\n## Bundled skills\n\nThree 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.\n\n| Skill | When to use |\n|---|---|\n| `/drawing-visuals` | When screen layout, structure, flow, or comparison still feels too ambiguous in text alone — start drawing on the canvas together. |\n| `/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. |\n| `/auditing-workspaces` | Audit existing workspaces — detect orphaned workspaces, tombstone-heavy canvases, and cache/disk mismatches; report cleanup candidates. |\n\n## Example transcript\n\n```text\nYou Use whiteboard to sketch the request flow for our auth service:\n client → API gateway → token service → DB. Highlight where caching lives.\n\nAgent { canvasId } = wb_document_create({ workspaceId: \"default\",\n path: \"auth-flow\", kind: \"spatial\" })\n wb_canvas_edit({ canvasId, ops: [\n /* 4 service boxes, the arrows between them, and: */\n { op: \"node.add\", node: { id: \"cache-note\", type: \"text\",\n text: \"cache lives here\" } },\n { op: \"tidy\" },\n ] })\n wb_scene_render({ canvasId })\n\n Drew a 4-stage flow on the auth-flow canvas. Cache callout placed\n between API gateway and token service. SVG attached.\n```\n\nThe 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.\n\n## Documentation\n\n| Topic | Where |\n|---|---|\n| Local checkout, HTTP MCP development loop, repo-local config override, skill linking | [docs/contributing/development.md](docs/contributing/development.md) |\n| Environment variables, storage layout, Codex sandbox quirks | [docs/reference/configuration.md](docs/reference/configuration.md) |\n| Components, data flow, MCP tool surface, design boundaries | [docs/explanation/architecture.md](docs/explanation/architecture.md) |\n| Export formats (SVG, OKF Markdown, JSON Canvas) and their tools | [docs/reference/export-formats.md](docs/reference/export-formats.md) |\n| MCP debugging workflow (Inspector, `MCP_HTTP_DEBUG`, transport checks) | [docs/contributing/mcp-debugging.md](docs/contributing/mcp-debugging.md) |\n| Trust model for all three runtimes (browser, local daemon, server mode) | [docs/explanation/security-model.md](docs/explanation/security-model.md) |\n| 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) |\n| WebSocket message shapes between daemon and browser | [docs/contributing/architecture/wire-protocol.md](docs/contributing/architecture/wire-protocol.md) |\n| Test layers, commit conventions, release process | [CONTRIBUTING.md](CONTRIBUTING.md) |\n\n## Limitations\n\n- 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.\n- The published transport is `stdio`. The HTTP MCP endpoint (`pnpm mcp:http:dev`) is for local development.\n\nSee [docs/reference/configuration.md](docs/reference/configuration.md#codex-sandbox-constraints) for sandbox quirks.\n\n## License\n\n[Apache-2.0](LICENSE).\n\nThe 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.\n\nThe project name and logo are not licensed for use in third-party commercial hosting offerings.\n", "bytes": 13228, "sha": "9689ecf27946993247f4a09ade184a8dd1d6cb3c51bae07ab76223149c75a03e", "repo_slug": "kamiazya/whiteboard", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_kamiazya_whiteboard_f39f7187/readme" }