tldraw

View saved version →

---
name: tldraw
description: Draw and diagram on a tldraw canvas with the tldraw plugin. Use when the user asks for a diagram, flowchart, sequence diagram, state machine, mindmap, sketch, or board, gives you mermaid to draw, or wants to edit shapes on a canvas.
---

# tldraw canvas

The plugin gives you a real tldraw editor. You draw by writing JavaScript that runs against it. For a flowchart, sequence diagram, state machine, or mindmap, that JavaScript can be one call: write the diagram as mermaid and draw it with the `helpers.createMermaidDiagram` editor helper (see Diagrams from mermaid).

Every board is a tldraw.com board. Find one with `search_boards`, then open it with `open_board` (`action: "open"`), passing its `boardId` and name, before writing drawing code. The app opens in the thread side panel; then call `exec` to draw on it. `exec` waits for the view to connect, so call it right after opening. `open_board` with `action: "home"` lets the user browse; the user can also open the board browser from the global sidebar or thread side panel.

The board is the real one, live: `exec` edits reach tldraw.com at once and anyone else on it sees them. Change it only as the user asked. A view-only board opens read-only.

To start a new board, call `create_board` with a name, and the workspace if the user named one (it defaults to their personal workspace). Then open it with `open_board` (`action: "open"`), passing the returned `boardId` and name. Only create a board when the user asks for a new one; otherwise find the existing board with `search_boards`.

To rename a board, call `rename_board` with its `boardId` and the new name. Only rename when the user asks. Only members of the workspace that owns a board can rename it; a board shared by link cannot be renamed, so tell the user why.

If the user @-mentions a board, the message contains a `tldraw://board/<id>` link. Pass that URI (or the id) as `boardId` to `open_board`, then edit with `exec`.

Use the tldraw tools yourself, in the main thread; do not hand the drawing to a sub-agent. A board a sub-agent opens cannot load, because Codex does not let that view call this plugin.

Pass the board's `boardId` to every `exec` and `screenshot` call; `open_board` returns it, and the model context lists each open board. Do not reopen the board for each edit. If `exec` reports that the board is not open, use `list_open_boards`, or open it with `open_board`; do not claim the drawing was made.

## Tools

- `search` — query the installed SDK's API documentation with JavaScript. Use `spec.members` (names, signatures, descriptions, categories, examples), `spec.types.shapes` (shape types and props), and `spec.helpers`. Return only the relevant entries, e.g. `return spec.members.filter(m => /createShape|alignShapes/.test(m.name))`.
- `search_boards` — find the user's tldraw.com boards by name; returns IDs for `open_board`.
- `create_board` — create a new, empty tldraw.com board in the user's personal workspace or a named workspace; returns its `boardId` for `open_board`.
- `rename_board` — rename a tldraw.com board, by `boardId`; returns the new and previous names.
- `exec` — run JavaScript against an open board, named by `boardId`, with the full `editor` API and `helpers`: `createShapeId`, `toRichText`, `createArrowBetweenShapes(fromId, toId, { text?, bend? })`, which binds an arrow to two shapes so it follows them, `addImage(url, { x?, y?, w?, h?, id? })`, which puts an image from the web on the board (see Images), `createMermaidDiagram(source, options?)`, which draws a mermaid diagram as editable shapes (see Diagrams from mermaid), and the comment helpers `getComments` and `addComment` (see Comments). Return a small JSON value to inspect the board. The result includes the board ID, return value, and record-change counts. Document edits commit together as one undo step. Errors discard the proposed edit, as does a change made meanwhile to anything the edit touches; reread the board before ret

Preview of the first 4,000 characters. Read full instructions →