# Brainstorm Canvas

A live brainstorming canvas you share with your AI agent. Map out features, user flows, open questions, decisions and risks as cards, connect them, group them, and keep a running list of notes. You edit in the browser; your agent edits through MCP tools. Every change shows up live on the other side, with the cards the agent touched briefly highlighted.

It ships as a **Claude Code plugin**: an MCP server, a companion skill that teaches the agent how to brainstorm on the board, and a `/brainstorm-canvas:canvas` command. The MCP server also works on its own in any MCP client.

- No dependencies. No build step. Node 18 or newer.
- Boards are plain JSON files in your project (`.canvas/`), so they live in git next to your code.
- Light and dark themes, works at phone width.

## What's on a board

| | |
| --- | --- |
| **Cards** | Seven types: idea, feature, flow step, question, decision, risk, note. Each has a status (open, planned, building, done, parked), a short description, tags, and key/value facts like `Priority: P1`. |
| **Connections** | `flow` (leads to), `depends` (needs this first), `relates` (loose link). Optional labels. |
| **Groups** | Colored frames around related cards, sized automatically. Drag a group's name to move all of its cards. |
| **Notes** | The board's discussion log: decisions, open questions, meeting takeaways. Link notes to cards, pin the important ones. |

In the browser: double-click to add a card, drag from the dot on a card's edge to connect, click anything to edit it in the side panel. Scroll to pan, Cmd/Ctrl + scroll to zoom, `F` to fit, `M` for notes, Cmd/Ctrl + Z to undo.

## Install in Claude Code

```
/plugin marketplace add maulikatwork/brainstorm-canvas
/plugin install brainstorm-canvas@brainstorm-canvas
```

Or from a terminal:

```bash
claude plugin marketplace add maulikatwork/brainstorm-canvas
claude plugin install brainstorm-canvas@brainstorm-canvas
```

Start a new session, then try:

- *"Sketch our onboarding flow on the canvas."*
- *"Add a question card about pricing tiers and link it to the checkout feature."*
- *"We decided to ship CSV import first. Record that on the board."*
- `/brainstorm-canvas:canvas` to open the board and get its link.

## Use with other MCP clients

Point any stdio MCP client (Claude Desktop, Cursor, and others) at `bin/mcp.mjs`:

```json
{
  "mcpServers": {
    "canvas": {
      "command": "node",
      "args": ["/absolute/path/to/brainstorm-canvas/bin/mcp.mjs"],
      "env": { "CANVAS_DIR": "/absolute/path/to/your/project/.canvas" }
    }
  }
}
```

Set `CANVAS_DIR` when the client doesn't start servers from inside your project folder.

## MCP tools

| Tool | What it does |
| --- | --- |
| `list_boards` | Boards in this project, with counts |
| `get_board` | Read a board as a compact summary or full JSON |
| `create_board` | Start a new board |
| `add_node` | Add a card. `from` connects it in the same call and puts it in the same group |
| `update_node` | Change any field. `values` are merged, `null` removes a key, `rename` changes the id everywhere |
| `delete` | Remove cards (with their connections), connections, groups or notes by id |
| `connect` / `disconnect` | Link or unlink two cards |
| `set_group` | Create or update a group and move cards into it |
| `add_note` / `update_note` | Board notes, linked to cards, pinnable |
| `batch` | Many changes in one call, all or nothing |
| `open_canvas` | Start the web UI if needed and return its link |

Cards added without `x`/`y` are placed automatically: inside their group, or next to the card they connect from.

## Try the demo board

```bash
node bin/cli.mjs serve --dir examples
```

Open http://localhost:4317/?board=demo to see a small habit-tracker plan with every card type, groups and notes.

## Command line

The CLI has the same operations as the MCP tools, for scripts or agents without MCP.

```bash
node bin/cli.mjs serve                                  # web UI at http://localhost:4317
node bin/cli.mjs show                                   # read the board
node bin/cli.mjs add --title "CSV import" --type feature --value Priority=P1 --from sign-up
node bin/cli.mjs connect csv-import check-in --kind depends
node bin/cli.mjs note add "Decided: CSV first." --node csv-import --pin
node bin/cli.mjs help                                   # everything else
```

## Where boards live

`<project>/.canvas/<board>.json`. Commit them: they're your planning docs. The format is documented in the [skill](skills/brainstorm-canvas/SKILL.md) and validated by [`public/schema.js`](public/schema.js). Editing a board file by hand also works; open browsers pick up the change.

| Setting | Default | Purpose |
| --- | --- | --- |
| `CANVAS_DIR` (or `--dir`) | `<project>/.canvas` | Where boards are stored |
| `CANVAS_PORT` (or `--port`) | `4317` | First port to try for the web UI; the next free one is used if it's taken |
| `CANVAS_NO_WEB` | unset | Set to `1` to run the MCP tools without the web UI |

## How it works

```
 agent ──MCP tools──▶ bin/mcp.mjs ──┐
                                    ├──▶ .canvas/<board>.json ◀── fs.watch ──▶ lib/web.mjs ──SSE──▶ browser
 you   ──CLI───────▶ bin/cli.mjs ───┘                                              ▲
 you   ──browser edits─────────────────────────────── PUT /api/boards/<name> ──────┘
```

- `lib/ops.mjs` holds every board operation, shared by the MCP server and the CLI.
- `lib/store.mjs` reads and writes boards atomically (temp file + rename).
- `lib/web.mjs` serves the UI on `127.0.0.1` and pushes changes to browsers with server-sent events.
- `public/` is the canvas itself: plain HTML, CSS and ES modules.

## Development

```bash
npm test          # drives the MCP server over stdio against a copy of the demo board
claude plugin validate .
```

## License

[MIT](LICENSE)