Hosted diagrams and plans

Live whiteboards

A live whiteboard is an organisation's board of diagram tabs that its members edit together and see change as it happens. Each tab is one diagram. You draw on the canvas or type in the source panel, and everyone with the board open sees the change at once, with what was added and changed pulsing for a moment. Boards are part of Enterprise and are in early access: Plotwork turns them on for your organisation when you ask.

TL;DR

Question	Answer
Which plan?	Enterprise. In early access, Plotwork also turns boards on for each organisation; ask your contact.
Who can make one?	Any member but a reader. Owners and admins manage every board; the member who made a board manages it too.
Who can open one?	Every member of the organisation, or only the members and groups the board names. Readers can watch but not change a board. When your owner allows guests, a board can also be shared with anyone signed in to Plotwork, who watches it read only.
Where are boards?	The Boards tab of your organisation in the portal. A board's address is `https://app.plotwork.dev/orgs/<organisation>/boards/<id>`, and a short one is `https://app.plotwork.dev/b/<id>`.
How do changes reach everyone?	Every change is checked and stored by the board, then sent to every open browser. Nobody's screen shows a change the board did not keep.
What is checked on a change?	That the diagram parses, your organisation's secret scanning, the size of a tab, and the number of tabs. A change that fails is refused with the reason and a hint, and nothing is kept.
What happens when nobody is looking?	The board goes quiet. A hidden browser tab closes its live connection after 30 seconds, a board left alone pauses after a few minutes with no input, and a connection asks "Still here?" after two hours. Click to carry on.
Can an agent work on a board?	Yes. An agent you connect to your organisation, such as Claude, opens a board, reads a tab and changes it over the hosted MCP server, as you and with your access. Everyone on the board sees it as "Claude, for you@example.com (opens in a new tab)", and what it changed pulses. See Connect an agent, and talk to it from the board.
Is a board public?	Never: nobody signed out opens one. A board shared with anyone signed in opens, read only, for any Plotwork account, but only while your owner allows guests, and never when it is Confidential. Otherwise a tab reaches a public link only by being saved to the library and shared from there, under the library's rules.
Can I use a board from a terminal or a script?	Yes. The command line's `plotwork board` commands do what the agent's tools do, with an organisation key that has the boards scope: list and open boards, pull a tab into a file and push it back, edit, import, save, work in revisions, and watch for changes. See From the command line.
What does Plotwork keep?	Each tab's diagram source and its history, until the board is deleted or your organisation's retention removes it. Who is on a board and where their pointer is are never stored.

1. Make a board

In the portal, open your organisation and choose the Boards tab.
Choose New board and give it a name. It starts with one empty tab.
Choose its label (Public, Internal or Confidential), as for a library diagram. A member can raise a board's label; only the owner and admins can lower it.

2. Work on a board

To	Do this
Add a tab	Choose the plus at the end of the tab strip for an empty tab, or Add from in the board's More menu for a library diagram, one of your own diagrams, or source you paste.
Rename, move or delete a tab	Double-click its name to rename it, drag it to move it, or use its menu to delete it. A board keeps at least one tab.
Draw	Use the canvas as in the diagram editor: the toolbar, the shape picker, and the bar over the selection.
Type	Open the source panel. Your text is sent a second after you stop typing. If someone changed the tab meanwhile, the two versions are merged by line when they do not touch the same lines; otherwise you choose which to keep.
See who is here	The row of avatars at the top shows everyone on the board, dimmed when they are idle. Their pointers and selections show on the canvas in their colour. Click someone to follow the tab they are on.
See what changed	Added and changed items pulse in the colour of the person who changed them.
Go back	Open History in the board's More menu. Each change lists who made it, when and what it changed. Choose a version to look at it, and Restore to make it the current one again. Restoring is a new change, so nothing is lost.

A change to a tab names the version you were looking at. When someone else changed the same tab first, the board applies your change to the new version if it still fits, and otherwise tells you so and reloads the tab.

Choose Share on the board.

Part	What it does
Copy link	Copies the board's address with the tab you are on (`#tab-<id>`). A second button copies the short link.
General access	Everyone in the organisation can view, or can edit; or only the people added.
People and groups	Add a member, or a group your identity provider sends over SCIM, as a viewer, an editor or a manager. Someone outside the organisation must be invited to it first. A reader stays a viewer whatever you choose.
Anyone with the link who is signed in	Lets anyone signed in to Plotwork watch the board, read only, as a guest. Someone without an account makes a free one with their email address, and the board opens for them after they sign in. A guest sees only this board: not your library, your members or your other boards. It is offered only when your organisation's owner turns on Allow guests on boards in the organisation's settings, and never on a Confidential board. Turning it off, or the owner's switch, closes every guest out at once. Each guest's visit is in the audit log.
Invite link	A link that adds any member of your organisation who opens it, as a viewer or an editor, for 30 days. It never lets in a person outside the organisation. The link is shown once; revoke it at any time.
Join message	A line to paste into Teams, Slack or a Zoom chat with the short link. A Confidential board's message leaves its name out.
QR code	The short link as a QR code, for a meeting room screen. It is drawn in your browser.

Someone who opens a board they cannot see gets "You do not have access to this board" and Ask for access, with an optional note. The board's managers get an email and answer the request on the board. The page looks the same whether the board exists or not, so a link that leaks tells nobody anything.

A link to a board pasted into a chat app shows Plotwork's own card, which names nothing of the board.

4. Diagrams in and out

To	Do this
Save a tab to the library	Choose Save to library in the board's More menu. Save as a new diagram, with a name and a folder, or save it as a new version of the library diagram it came from. Every library rule applies: folder rules, the label, secret scanning, the size, and approval, which may hold the save until an approver decides. The tab then shows Saved, Changed since saved, or Waiting for approval.
Open a library diagram on a board	Choose Open on a board on the diagram's page, or Add from and then The library in the board's More menu. The tab stays linked, so saving it later makes a new version of the library diagram. The diagram's page lists the boards it is on.
Export	Choose Export in the board's More menu: SVG and PNG in the theme you are using, the `.diagram` source, Markdown with a `diagram` fence, a view link, or every tab as a zip. The files are made in your browser. A Confidential board offers no view link.

A diagram published without its source cannot be opened on a board. Publish it again with its source, or keep diagrams editable in your organisation's settings.

5. Connect an agent

An agent connected to your organisation can follow a meeting on a board and keep a tab up to date: draw what the room decides, add a service someone names, or tidy a diagram while you talk.

Connect the agent to the hosted MCP server and, when it asks, choose your organisation, as Connecting an agent explains. A connection to your own account cannot reach a board.
Ask it for the board by name or by its address, for example "Open the board Q4 planning and add what we decide to the Checkout tab".

Tool	What it does
`list_boards`	Lists the boards you can open, newest change first. It changes nothing.
`open_board`	Opens one board: its tabs and their versions, your access, and who is on it.
`read_board_tab`	Reads a tab's diagram source and version. With the version it read last, it also says what people changed since and who, which is how the agent follows the meeting. It can add the picture.
`edit_board_tab`	Changes a tab with small edits, the same ones `edit_diagram` makes, or with a whole new source, against the version it read.
`add_board_tab`	Adds a tab with a diagram, or an empty diagram of a kind.
`import_to_board`	Adds a tab made from a library diagram (linked to it), one of your own diagrams, a Plotwork link or SVG, Mermaid, a file such as SQL, OpenAPI or Terraform, or a pattern. What the import left out comes back for the agent to tell you. The file is read and not kept.
`save_board_tab`	Saves a tab to your organisation's library, as a new diagram or a new version of the one it came from, under every library rule, approval included.
`wait_for_board_messages`	Waits up to 25 seconds for a message you type to the agent on the board, and answers as soon as one arrives. See Talk to your agent from the board.
`reply_board_message`	Answers your message, in the board's code panel.

Question	Answer
What can the agent do?	What you can, never more. On a board you may only view, its edits are refused. Owners and admins can also make an organisation key with the live whiteboards scope under Keys & CI in the portal; such a key reaches only the boards open to the whole organisation.
How does the room see it?	The board shows "Claude, for you@example.com (opens in a new tab)" among the people on it, a mark on the tab it is reading or editing, and, after each change, what it added and changed, pulsing.
What if two change the same thing?	The agent's change names the version it read. When someone changed the tab since, the board applies the agent's change to the new version if it still fits; otherwise the agent is told, reads what changed and makes its change again. It never overwrites your work by replacing the tab.
Which rules apply?	All of them: your organisation's allowed agents, its daily limits, secret scanning on every change, the board's label, legal hold, and the audit log, which names the agent and you.
Is it on the local server?	No. The board tools are on the hosted server only, and only for a connection whose organisation has boards.
Can I script it?	The same tools are REST routes under `/v1/boards`, for an organisation key with the boards scope: see the API reference.

6. Talk to your agent from the board

Type to your own agent in the board's code panel, under the problems: "update the task diagram", "add a Redis cache in front of Orders". The agent does it in its own revision and answers in the same place.

Start your agent listening. In Claude Code with the Plotwork plugin, run /plotwork:listen <board id> (the id is in the board's address). Any other agent: ask it to call wait_for_board_messages for the board in a loop, act in its revision, and answer with reply_board_message.
On the board, open the code panel. Ask Claude Code shows your agent's name and whether it is Listening, Busy (it has your message and is working on it) or Not listening.
Type and press Enter. Turn on Send problems to attach the tab's warnings and errors. Your message shows Sent, then Seen when the agent reads it, then Answered with its reply.

Question	Answer
Why must the agent listen?	Agents on a subscription, such as Claude Code on Pro or Max, or Cursor, run on your machine. Plotwork cannot call them; they ask the board for your messages. A listening agent waits on the board without keeping it awake, and its waits are not counted against your daily calls.
What if it is not listening?	Your message waits for it, and the agent gets it the next time it opens or reads the board. Copy prompt copies a ready prompt with the board, the tab, the revision and your message, to paste into your agent's session.
Who can send my agent a message?	Only you, the person who connected it, and only you see the thread. Your organisation's owners and admins can too, if an owner or admin turns on "Owners and admins can message members' agents" in Settings.
Who can my agent answer?	Only you, in its own thread. It cannot read or write anyone else's.
Does it merge?	No. It works in its own revision and asks you before it asks to merge; a person merges.
What is checked and kept?	Each message and reply is scanned with your organisation's secret scanning, and the audit log records that one was sent, never its words. A thread keeps its last 50 messages, for 30 days at most, and goes with the board.
How long can it listen?	Agents can listen on one board for four hours a day in all. A listening agent stops when nobody has the board open, unless you ask it to keep listening.

7. Staying live

A board's live connection counts against a daily budget of live time, for your organisation and for the service, because it keeps a server awake. The portal keeps a board quiet when nobody is looking:

When	What happens
The browser tab is hidden	After 30 seconds the live connection closes. It opens again, with everything that changed, when you come back.
Nobody touches the board	After a few minutes with no pointer, key or change, the board pauses with "Paused to save the board's live time. Click to resume."
A connection has been open two hours	The board asks "Still here?".
Today's live time is spent	The board opens without its live connection. Your changes still save; choose Reload to see other people's. It comes back at 00:00 UTC.

The numbers are your plan's, as your organisation's Plan page shows them.

8. Policies that apply

Policy	On a board
Secret scanning	Every change is scanned with your organisation's settings. Under Block, a change that holds something that looks like a secret is refused; under Warn, it is kept and counted.
Classification	A board has one label, shown on it, on its exports and on a tab saved to the library.
Approval	Changes to a board are not publishes and are never held. Saving a tab to the library is, and goes through approval when its folder needs it.
Retention	A board nobody changed for your organisation's retention days is deleted by the daily clean-up, unless an owner or admin keeps it.
Legal hold	While your organisation is on legal hold, no board or tab can be deleted and no history is trimmed.
Audit log	Making, renaming, labelling, keeping and deleting a board; tabs added, renamed, moved and deleted; one event for each run of edits by one person or agent on one tab; restores; sharing, invite links and requests for access; saves, imports and exports; messages to an agent and its replies. Never a diagram's source or a message's words.

9. From the command line

The Plotwork command line, plotwork, reaches a board through the same /v1/boards routes as the agent's tools, so the same rules, limits and audit apply. Each command is described in the command reference, and plotwork board <command> --help prints it in a terminal.

On the Keys tab of your organisation, under Keys & CI, make an organisation key and turn on its live whiteboards scope. A key reaches only the boards open to the whole organisation.
Set it in PLOTWORK_API_KEY, then run plotwork board list. The board commands come with the release of the command line after 0.2.0; plotwork board --help lists them when yours has them.

Command	What it does
`plotwork board list`, `plotwork board open <board>`	The boards the key may open; one board's tabs, versions, who is here, and each tab's revisions. A board is named by its id, its address, or its name.
`plotwork board pull <board> <tab> -o <file>`	Writes the tab's source to the file, and the version it pulled to `<file>.board.json` beside it. A file with changes of its own is never overwritten without `--force`.
`plotwork board push <file>`	Sends the file as the tab's new version, against the version it was pulled at.
`plotwork board edit <board> <tab> --rename api=gateway --add-node cache:database=Redis`	Small edits, which the board applies to the current version even when someone changed it since. `--op` takes any edit as JSON.
`plotwork board add-tab`, `plotwork board import`, `plotwork board save`	A new tab, a file or library diagram imported as a tab, and a tab saved to the library.
`plotwork board revision create`, `list`, `compare`, `request-merge`	Work in a revision of a tab, see what merging it would change, and ask a person to merge it.
`plotwork board watch <board> [<tab>]`	Prints each change as it lands, until you press Ctrl-C.

Question	Answer
What if someone changed the tab since I pulled it?	`board push` is refused, and prints who changed what since, how your file differs from the tab now, and what to do: pull and redo your change, send it as edits with `board edit` (which the board fits onto the new version), or `--force` to replace the board's version with yours. The tab's history keeps the version you replaced. Nothing is overwritten unless you ask.
What is in `<file>.board.json`?	The board, tab and revision ids, the version the file holds, and a hash of the file. Never a key or the source. Commit it with the file to record which board version the repository's copy matches.
Does `watch` keep the board awake?	No. It asks the API whether the board changed, which does not wake it, and reads a tab only after a change. It waits longer while nothing changes, up to two minutes, and stops after 30 quiet minutes. Each check counts against the key's daily calls.
Can a script read the output?	`--json` prints the API's answer, the same as the agent's tool gives, or `{ "error": true, "errorCode", "message", "hint", "status" }`. `board watch --json` prints one JSON object a line. Exit code 0 means it worked, 1 a refusal or a conflict, 2 a mistake in the command or the key.
Can I use it in GitHub Actions without a key?	No. The keyless sign-in of the GitHub Action signs a job in as a trusted publisher, and a trusted publisher never reaches a board. Store an organisation key with the boards scope as a secret and pass it in `PLOTWORK_API_KEY`.
Can I answer my agent's messages from it?	`board wait` and `board reply` exist for an agent's own connection; an organisation key has no thread, so the API answers `boards.connection_required`.

These steps are what the Claude Code plugin's /plotwork:board skill follows in a meeting, with the hosted tools when the agent has them and the command line otherwise:

Step	MCP tools	Command line
Find and open the board: its tabs, their versions, who is here	`list_boards`, `open_board`	`plotwork board list`, `plotwork board open`
Make your own revision of the tab, or reuse yours	`list_revisions`, `create_revision`	`plotwork board revision list`, `plotwork board revision create`
Read the tab, and what changed since the version you hold	`read_board_tab`	`plotwork board pull`
Change it with typed operations against that version	`edit_board_tab`	`plotwork board edit`
Add a tab, or import a file or a library diagram as one	`add_board_tab`, `import_to_board`	`plotwork board add-tab`, `plotwork board import`
See what merging would change on main, and the conflicts	`compare_revision`	`plotwork board revision compare`
Ask a person to merge, after the person says yes	`request_merge`	`plotwork board revision request-merge`
Save the tab to the library, when asked	`save_board_tab`	`plotwork board save`

And these are what its /plotwork:board-sync skill follows to keep a file in your repository and a tab in step:

Find the pair. If <file>.board.json exists beside the file, it names the board, the tab, the revision and the version the file was pulled at. Otherwise ask the person for the board and the tab, by id, address or name.
First time. With no sidecar and no file, run board pull <board> <tab> -o <file>. With a file that was never pulled, show the person how it differs from the tab (board pull <board> <tab> -o - prints the tab's source; compare_diagrams compares the two), and ask which side wins before you run board pull --force or board push <board> <tab> <file> --force.
Send the file's changes. Run board push <file> --json. changed: false means the file has not changed since it was pulled; a version means the tab now has the file's source.
Take the board's changes. When the push sent nothing, run board pull <board> <tab> -o <file>: the file had no changes of its own, so nothing is lost, and the command lists what changed on the board since.
A conflict. diagram.version_conflict means both sides changed. Its details give changesSince (who changed what on the board) and difference.summary (how the file differs from the tab now). Tell the person both. To keep both: save the file's text aside, board pull <board> <tab> -o <file> --force, write the file again with both sides' changes, check it with validate, and board push <file>. Use board push <file> --force only when the person says the file should replace the board's version; the tab's history keeps the old one.
After a pull. The plugin's hook draws a file Claude saves, not one the command line writes: run sync or render for the repository's pictures. Commit the file and its sidecar together only when the person asks; the sidecar records which board version the file matches.

Page	What it covers
Organisations	Members, roles and the private library
Connecting an agent	Connecting Claude and other agents to the hosted MCP server and to your organisation
Secret scanning	What counts as a secret, and Warn or Block
Classification labels and publish approval	Labels, and how a save can be held
Retention, legal hold and approved patterns	How long things are kept, and the hold
Audit log	Reading and exporting your organisation's events
Privacy policy	What a board stores and for how long
Command reference	Every `plotwork board` command, its options and exit codes
Claude Code plugin	The `board`, `board-sync` and `listen` skills