OpenBoard

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.

Why

Related MCP server: The Room

Quick start

You need Node.js 22 or newer. OpenBoard is not on a package registry yet, so run it from a clone:

git clone https://github.com/asasemahmed/openboard.git
cd openboard
corepack enable
pnpm install
pnpm build
alias openboard="node $PWD/packages/cli/dist/bin.js"

Then, in any project:

cd /path/to/your/project
openboard start

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

Connect your agent

Let your agent do it

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 does not exist, run `git clone https://github.com/asasemahmed/openboard.git ~/openboard`.
   Then, inside ~/openboard, run `corepack pnpm install` and `corepack pnpm build`.
3. Back in this project, run `node ~/openboard/packages/cli/dist/bin.js 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 ~/openboard/integrations has a folder for your
   client, follow its README instead.
5. Copy the guide between the openboard:guide markers in ~/openboard/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
   `node ~/openboard/packages/cli/dist/bin.js 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.

Or set it up yourself

After the quick start, run this in your project:

openboard connect

It 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 -- node /path/to/openboard/packages/cli/dist/bin.js mcp

OpenCode — opencode.json in the project:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "openboard": {
        "type": "local",
        "command": ["node", "/path/to/openboard/packages/cli/dist/bin.js", "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": "node",
      "args": ["/path/to/openboard/packages/cli/dist/bin.js", "mcp", "--root", "/path/to/your/project"]
    }
  }
}

Other clients take the same command and args:

If node is not on the path your client starts servers with, use the absolute Node.js path 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, 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."

What you get

For your agent

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

Full reference: docs/tools.md.

For you

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

• A conversation in context. Comment threads on cards, mentions, and question cards from agents with one-click answers.

For your repository

• 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 setup installs a merge driver that merges at field level, never writes conflict markers, and never drops an edit.

• Reviewable. openboard diff shows 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, and SVG. Import Mermaid flowcharts and JSON Canvas files.

For your team

• Shared mode. openboard start --share lets 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.

Make it yours

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

How it works

Three ideas carry the design:

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

2. Budgeted reads, intent writes. An agent never receives more of the board than it asked for, and never writes half an idea.

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

Measured, not assumed

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.

Token counts are estimates of board input and output at four characters per token. Run it yourself with pnpm evals run --runner scripted.

Security

• Local by default. The server binds to loopback, checks Host and Origin, 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.

Documentation

Project layout

Status

OpenBoard is pre-release software.

• It runs from a source checkout; it is not published to a package registry.

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

Contributing

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.

See CONTRIBUTING.md for the development setup, commands, and ground rules.

pnpm test        # every package
pnpm lint
pnpm typecheck

License

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