Quick start · Connect your agent · What you get · How it works · Docs
Note
OpenBoard is free to use, change and share for personal and other noncommercial purposes under the PolyForm Noncommercial License. Commercial use needs a separate license. It is pre-release: nothing is published to a package registry yet.
A shared canvas that your AI agent can read, edit, and be steered from.
Run OpenBoard in a project and the agent you already use — Claude Code, Cursor, Codex, or any other MCP client — can map your code, lay out a plan, and keep it current on a board you both see. You steer by pointing: select cards, comment, accept or reject what the agent proposes, and answer its questions right on the canvas.
OpenBoard does not build agents. It is the surface between you and yours.
A real board, exported with openboard export --format svg. The file behind it is a few kilobytes of readable JSON.
| Without a shared board | With OpenBoard |
|---|---|
| An agent's plan scrolls away in the chat | The plan lives on a board that persists and stays current |
| You steer by typing long instructions | You select cards and say "these" |
| An agent edits your work and you find out later | Changes to your work wait as proposals you accept or reject |
| You cannot tell what five subagents are doing | Every agent shows what it is reading, writing, or running |
| Diagrams rot the moment the code changes | Cards linked to code are flagged when that code changes |
| Whiteboards are tied to one vendor's assistant | Any agent that speaks MCP works |
You need Node.js 22 or newer. Install the openboard command from npm:
npm install -g @openboard-dev/cliThen, in any project:
cd /path/to/your/project
openboard startThe board opens in your browser. Press N for a note, T for a task, Cmd/Ctrl+K to search and run commands, or start from a template. Getting started walks through the rest.
Open your project in any coding agent that can run commands — OpenCode, Cline, Claude Code, Cursor, Codex, Gemini CLI, Windsurf, GitHub Copilot, Zed — and paste this prompt. The agent installs OpenBoard, connects itself, and checks that it works.
Set up OpenBoard (https://github.com/asasemahmed/openboard) for this project and connect yourself to it.
1. Run `node --version`. If Node.js is missing or older than 22, stop and tell me.
2. If `openboard --version` fails, run `npm install -g @openboard-dev/cli`.
3. In this project, run `openboard connect generic`.
It prints a stdio command with absolute paths. Use that exact command; do not change the paths.
4. Add an MCP server named "openboard" that runs that command to your own MCP configuration,
in the file and format your client uses (the project's configuration if your client has one).
Keep every server that is already there. If https://github.com/asasemahmed/openboard/tree/main/integrations
has a folder for your client, follow its README instead.
5. Copy the guide between the openboard:guide markers in
https://github.com/asasemahmed/openboard/blob/main/integrations/generic/AGENT_GUIDE.md
into the instructions file you read for this project (for example AGENTS.md or .clinerules).
6. Tell me what you changed, and whether I need to restart or reload you to load the new server.
7. When the board_ tools are available, call board_outline and show me the result. Then run
`openboard status` and give me the board's URL to open.
The MCP server starts the board server for the project on first use, so there is nothing else to keep running.
After the quick start, run this in your project:
openboard connectIt prints the exact command for your project, with absolute paths. Put it in your client's configuration.
Claude Code — one line:
claude mcp add openboard -- openboard mcpOpenCode — opencode.json in the project:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"openboard": {
"type": "local",
"command": ["openboard", "mcp", "--root", "/path/to/your/project"]
}
}
}
}Older OpenCode versions put the server directly under mcp, without servers.
Cline — open the MCP Servers panel, choose Configure MCP Servers, and add to cline_mcp_settings.json:
{
"mcpServers": {
"openboard": {
"command": "openboard",
"args": ["mcp", "--root", "/path/to/your/project"]
}
}
}Other clients take the same command and args:
| Client | File | Where the server goes |
|---|---|---|
| Cursor | .cursor/mcp.json |
mcpServers |
| Codex | ~/.codex/config.toml |
[mcp_servers.openboard] |
| Gemini CLI | .gemini/settings.json |
mcpServers |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
mcpServers |
| GitHub Copilot | .vscode/mcp.json |
servers, with "type": "stdio" |
| Zed | Zed's settings.json |
context_servers |
| Anything else | Your client's MCP settings | stdio, or http://127.0.0.1:4747/mcp |
If your client cannot find openboard (it may start servers with a shorter path than your shell's), use the command with absolute paths that openboard connect prints. Setups that also teach the agent how to work on a board — a plugin with a skill for Claude Code, a rule for Cursor, a snippet for Codex, a GEMINI.md snippet for Gemini CLI, and a generic guide for everything else — are in integrations/.
Then try:
- "Map this repository's architecture on the board."
- "Plan the CSV export feature on the board, with risks and open questions."
- Select a few cards, then: "Group these into a frame and add what is missing."
- Budgeted reads. An agent looks at an outline first, then reads a frame, your selection, a search result, or only what changed since it last looked. Every read takes a token budget and says when it left something out.
- Intent writes. One batch creates a connected structure, with references between the nodes it adds. The batch is validated as a whole and applied atomically; errors name the operation and say what would be valid.
- No coordinates. Agents edit meaning. The layout engine places what they add and never moves what you placed.
- Feedback. An inbox carries your mentions, replies, answers, and review decisions with your note. An agent can ask you a question on the canvas and wait for the answer.
- A small tool surface. Sixteen tools whose names, descriptions and schemas fit in about 3,500 tokens. A test fails if they grow past a ceiling.
The sixteen tools
| Tool | What it is for |
|---|---|
board_list, board_create |
Find or create a board, optionally from a template |
board_outline |
The cheap first look: frames and counts |
board_read |
A slice: by ids, frame, selection, type, status, tags, text, neighbours |
board_changes |
What happened since the agent last looked, and who did it |
board_selection |
What you are pointing at right now |
board_apply |
A validated, atomic batch of operations |
board_layout |
Tidy a board or a frame |
board_inbox |
Mentions, replies, answers, review decisions; can wait for one |
board_comment |
Comment, reply, or resolve a thread |
board_ask |
Put a question or approval request on the canvas and wait |
board_undo |
Take back the agent's own change, or withdraw a proposal |
board_claim |
Mark nodes as being worked on so other agents stay off them |
board_links |
Which cards describe code that has changed |
board_schema |
The node and edge types available, including your own |
board_template |
Start a structure from a template |
Full reference: docs/tools.md.
- Review on the canvas. By default an agent adds freely and edits its own work freely, while changes to anyone else's content arrive as proposals: dashed ghosts with Accept and Reject, decided as a whole or item by item, with an optional note back to the agent. Four policy modes per agent, and a frame can be opened up, protected, or locked.
- Exact undo. Every change is a batch with an author and a reason. Undo restores exactly what was there and never overwrites later work.
- See agents at work. Agents appear among the participants with what they are reading, writing, or running. A recorder hook shows the whole session tree, subagents included. Replay scrubs through how the board came to be.
- Since your last visit. Open a board again and a short notice says what others changed while you were away, and who, with the cards outlined on request.
- A conversation in context. Comment threads on cards, mentions, and question cards from agents with one-click answers.
- What needs attention. With nothing selected, the inspector lists open questions, risks with no task or decision, cards still marked blocked after what held them up is done, and stray cards. Click one to go to it.
- Boards are files. Each board is deterministic JSON in
.openboard/: a small change to the board is a small diff. - Merged by meaning.
openboard git setupinstalls a merge driver that merges at field level, never writes conflict markers, and never drops an edit. - Reviewable.
openboard diffshows what changed between revisions as text, markdown, or an SVG that draws what was added, changed, and removed. The canvas can compare the live board with any revision. - Code-aware. A card linked to a file or a line range follows the code when it moves and is flagged when it changes.
- In and out. Export to JSON, Markdown, Mermaid, JSON Canvas, SVG, and a self-contained HTML page. Import Mermaid flowcharts and JSON Canvas files.
- Shared mode.
openboard start --sharelets people and agents on other machines join with invite links and tokens. Roles — owner, editor, commenter, viewer — are enforced on every request and on the sync connection, and access can be revoked at once. It stays opt-in; the default is local only. - Claims. On a board shared by several agents, a claim keeps them out of each other's way and expires on its own.
- Your own types. Declare node and edge types with typed fields in
.openboard/config.json. They get proper cards and forms, validation, and a description agents can read. - Templates. Eight built in — feature plan, architecture map, release plan, incident review, decision record, research map, kanban, agent team — plus any board you save as a project template.
- Plugins. Add types, templates, exporters, importers, and a hook after each change. Plugins are loaded only when you name them with
--plugin; nothing is ever loaded from a project on its own.
Three ideas carry the design:
- Structure over pixels. The board is a typed graph of nodes, edges, and frames. Agents edit meaning; the layout engine places things and leaves alone what you placed.
- Budgeted reads, intent writes. An agent never receives more of the board than it asked for, and never writes half an idea.
- The board is shared ground. People and agents edit one document. Every change is attributed, everyone sees it as it happens, and text on the board is treated as data, not as instructions.
The details, including the contracts between packages, are in docs/ARCHITECTURE.md.
OpenBoard ships an evaluation harness that gives an agent a task through the real MCP server and scores the board it leaves behind and what it cost.
| Measure | Result |
|---|---|
| Tool list an agent loads once per connection | about 3,500 tokens for 16 tools |
| Find and update one card on a 500-card board | about 220 tokens of board output; reading the whole board would be about 41,000 |
| Scenarios in the suite | 12, each with a scripted reference that must score 1.0 |
| A small model on four scenarios (mapping a repo, a large board, review, untrusted content) | 1.00 on each, at 0.9× the reference's board tokens |
| Layout | 500 cards in about 0.2 s; 2,000 in about 0.5 s |
| Recorder hook | under 50 ms per agent tool call |
Token counts are estimates of board input and output at four characters per token. Run it yourself with pnpm evals run --runner scripted.
- Local by default. The server binds to loopback, checks
HostandOrigin, and has no remote access unless you start shared mode. - Board text is untrusted input. Reads label who wrote what, and the agent guides say to treat it as content.
- Shared mode authenticates every request, takes identity from the access grant rather than from request headers, and syncs viewers and commenters read-only. It was reviewed independently; the findings and the known limits are in docs/sharing.md.
- No implicit code loading. Plugins run only when named on the command line.
To report a vulnerability, see SECURITY.md.
| Guide | What it covers |
|---|---|
| Getting started | Build, start, connect, first prompts |
| How agents work with a board | Reads, writes, selection, review, undo, comments, questions, identity, trust |
| Tool reference | Every tool, operation, validation error, and type |
| CLI reference | Every command and flag |
| Board file format | The .board.json file and config.json |
| Boards in git | Merging, readable diffs, reviewing board changes |
| Templates | The built-in templates and how to use them |
| Extending OpenBoard | Declared types, project templates, plugins |
| Sharing boards | Shared mode, invites, roles, running it safely |
| Evaluating agents | The harness, its baseline, and what it shows |
| Integrations | Claude Code, Cursor, Codex, and generic MCP setups |
| Architecture | How the packages fit together |
| Path | What it is |
|---|---|
packages/core |
Schema, operations, the board document, queries, rendering, formats, merge. Runs in Node and in the browser. |
packages/server |
The local server: sync, persistence, layout, policy, history, code links, shared mode |
packages/mcp |
The MCP tools, over stdio and Streamable HTTP |
packages/sdk |
A typed HTTP client |
packages/cli |
The openboard command |
packages/app |
The web canvas |
packages/evals |
The evaluation harness |
integrations/ |
Ready-made agent setups |
examples/ |
A sample plugin and a sample board |
OpenBoard is pre-release software.
- The first version on npm is 0.1.0; expect changes between versions until 1.0.
- The Claude Code setup is exercised end to end. The setups for the other clients were written from their documentation and not run inside those tools.
- Shared mode has not been run behind a real TLS proxy or tunnel yet.
- There is no PNG export (the SVG export is self-contained) and no board view inside chat clients.
Contributions are welcome. The open issues range from an afternoon's work to a new subsystem: good first issue marks the small, well-scoped ones and help wanted the ones nobody is working on. Comment on an issue before you start so two people do not build the same thing.
For ideas, questions and boards you made, use Discussions.
See CONTRIBUTING.md for the development setup, commands, ground rules, and the terms your contribution is made under.
pnpm test # every package
pnpm lint
pnpm typecheckOpenBoard is licensed under the PolyForm Noncommercial License 1.0.0.
- You may use, change, and share it for personal use, research, hobby projects, education, and other noncommercial purposes, including inside charities, schools, and public institutions.
- You may not use it for commercial purposes without a separate license. To ask about one, open an issue.
This is a source-available license, not an open-source license as the Open Source Initiative defines the term.