Viewing diagrams
Where you see a diagram an agent drew, in each place you work with an agent, and what is sent where when you do. An agent reads the check and the outline; you want the picture.
- Claude
- Claude Desktop
- VS Code
- ChatGPT
TL;DR
| Question | Answer |
|---|---|
| How do I see a diagram from a terminal agent? | Ask the agent for the view link. Every valid answer of draw_diagram, draw_from_pattern, and convert_mermaid has a viewUrl. Open it in a browser. |
| What does the view link show? | The diagram on a canvas with zoom and fit, light and dark, the source one tab away, and downloads as SVG and PNG. It works on a phone. |
| Is the diagram sent to Plotwork when I open the link? | No. The source is in the part of the link after #, which a browser never sends to a server. The page draws the diagram in your browser. |
| Can the link save a PNG for Slack or email? | Yes. pngUrl in the same answer is the view link with &download=png: it draws the PNG in your browser and saves it. svgUrl does the same for an SVG. See Slack, email, Confluence, and Notion. |
| How does an agent save the diagram into my repository? | It asks for the SVG with svg set to always and embedSource set to true, and writes it. Once the command line release that reads view links is on npm, the answer also carries a saveCommand the agent runs instead, so the SVG never passes through the model. See Save a diagram into a repository. |
| Who can read the diagram? | Anyone you give the link to. The source is in the link itself, so treat a view link like the diagram's text. |
| Does it work in Claude, Claude Desktop, VS Code, or ChatGPT? | In a client that supports MCP Apps, the drawing appears inline under the tool call, with light and dark, zoom, and a button that opens the view link. A client without MCP Apps shows nothing extra. |
| Can the local server open the browser for me? | Yes. Set PLOTWORK_OPEN=1 in the server's environment. Each drawing is written to your temporary folder and opened in your default browser. |
| Can I present a diagram or put it in slides? | Yes. Present shows it full screen one part at a time, and Export makes a PNG on every plan, and a PDF or a PowerPoint deck with one slide a step on Pro. See section 7. |
| Is there a size limit? | A view link is never longer than 32,000 characters. A diagram whose link would be longer gets no viewUrl, and the answer says why. Publish it instead. |
1. Where you see a diagram
| Where you work | What you see | How |
|---|---|---|
| A terminal agent, such as Claude Code or Codex | The view link | Ask the agent to give you viewUrl, then open it. The tool descriptions tell the agent to give it to you when you want to look. |
| Claude, Claude Desktop, VS Code, ChatGPT | The drawing inline, under the tool call | The drawing tools name an MCP Apps view. The client shows the SVG the answer already holds. |
| A phone | The view link | The page fits the diagram to the screen; pinch to zoom and drag to move. |
| Any browser | The view page | app.plotwork.dev/view draws the diagram from the link. |
| The local server or the npm package | A tab in your default browser | Set PLOTWORK_OPEN=1. |
| A README or a pull request | The SVG file | The agent runs saveCommand, or calls sync_markdown. See Save a diagram into a repository and Markdown and GitHub. |
| A link to share that does not carry the source | A hosted link | Call publish_diagram on the hosted server. See Hosted diagrams. |
Save a diagram into a repository
The hosted server cannot write to your computer, so the agent writes the file. Today it asks draw_diagram for the SVG with svg set to always and embedSource set to true, and writes the SVG it gets. The answer's next and the server's instructions say so.
| Field | What it is | Who uses it |
|---|---|---|
svgUrl | The view link with &download=svg. Opening it draws the SVG in your browser and saves it to your downloads. | A person who wants the file. It is not a file address: curl gets the viewer page, not the SVG. |
pngUrl | The view link with &download=png. | A person who wants a PNG for chat or email. |
saveCommand | npx -y @buun_group/plotwork@<version> render "<viewUrl>" --out <title>.svg. The command line decodes the diagram from the link, draws it, and writes the SVG with the source inside, with no request and no account. | An agent with a shell, such as Claude Code or Codex. It is in the answers of draw_diagram, draw_from_pattern, convert_mermaid, import_source, and edit_diagram only once the command line release that reads view links is on npm. Then next and the server's instructions tell the agent to run it, changing --out to the path it wants. |
When the command would be too long for a Windows command line there is no saveCommand, and next says to write the source to a .diagram file and render that file with the same command line.
Until that release, an agent without the command asks draw_diagram for the SVG with svg set to always and embedSource set to true, and writes the file itself.
2. The view link
A view link looks like https://app.plotwork.dev/view#v1. followed by the diagram's source, compressed and written in letters, digits, - and _.
| Part | What it is |
|---|---|
https://app.plotwork.dev/view | The viewer page in the portal. It needs no sign-in and asks the API for nothing. The preview environment's server points at app-preview.plotwork.dev. |
# | Everything after it is the fragment. A browser keeps the fragment to itself: it is not in the request for the page, in the referrer, or in the server's logs. |
v1. | The version of the format, so a link made today still opens after the format changes. |
| The rest | The source as UTF-8, compressed with raw deflate and written in base64url. |
The page loads the drawing engine, reads the fragment, checks the source, and draws it in light and dark. The theme switch picks which picture you see. The Source tab shows the text and copies it, with a prompt for an agent to change it. The SVG download carries the source, so read_diagram can give it back later.
| Situation | What the page says |
|---|---|
| The link has no fragment | There is no diagram in the link. |
| Part of the link is missing or changed | The link is damaged. |
| The fragment expands past the largest possible diagram | The diagram is too large to open. |
| The source has mistakes | Each mistake, with its line and column. |
The page is kept out of search engines. The first visit downloads the drawing engine, about 2.4 MB compressed, which the browser then caches.
3. What is sent where
| Step | What is sent | To whom |
|---|---|---|
| The agent draws the diagram | The source, in the tool call | The MCP server you use. The hosted server works on it in memory and keeps nothing. The local server never sends it anywhere. |
The answer carries viewUrl | The link, in the tool answer | Your agent and its model, like the rest of the answer. |
| You open the link | A request for the viewer page, without the fragment | Plotwork's host at Cloudflare, which sees an ordinary page request: your IP address and browser, never the diagram. |
| The page draws the diagram | Nothing | The drawing happens in your browser. |
| You download an SVG or PNG | Nothing | The file is made in your browser. |
You open pngUrl or svgUrl | Nothing more than for viewUrl | The page draws the file in your browser and saves it. |
The agent runs saveCommand | Nothing | The CLI decodes the link and draws the SVG on your machine. npx downloads the CLI from npm the first time. |
| You share the link | The source, in the link | Whoever you give it to, and any service the link passes through, such as a chat app that stores messages. |
The privacy policy says the same in its section on view links.
4. The inline view in MCP Apps clients
MCP Apps is an extension of the Model Context Protocol that lets a tool name an HTML view, which a supporting client shows in a sandboxed frame. draw_diagram, draw_from_pattern, and convert_mermaid name the view ui://plotwork/viewer.html in their _meta.ui.resourceUri.
| Rule | Why |
|---|---|
| The view shows the SVG the answer already holds | No extra call and no extra work on the server. |
| A picture is shown as an image, never as markup | Nothing in a diagram can run in the frame. |
| The view makes no request | The client's default policy for a view allows none, and the view needs none. |
| A client without MCP Apps ignores it | The tool answers are the same in every client. |
An answer with svg set to never has no picture | The view says so, and its button opens the view link instead. |
5. Opening the browser from the local server
The npm package and the stdio server read two variables at start-up. Neither is used by the hosted server.
| Variable | Effect |
|---|---|
PLOTWORK_OPEN=1 | After each drawing with pictures, the server writes light.svg, dark.svg, and a small index.html to a new folder in your system's temporary folder, opens the page in your default browser, and adds the folder to the answer's next. No network request is made. The folder is left for your system to clean up. |
PLOTWORK_VIEWER_URL | The viewer page that viewUrl points at, such as http://localhost:3104/view for a portal you run yourself. Unset, it is https://app.plotwork.dev/view. |
Building the view link sends nothing anywhere. Only opening it asks the viewer's host for the page.
6. For people who build clients
| Fact | Detail |
|---|---|
viewUrl is optional | It is present only for a valid diagram whose link fits in 32,000 characters. |
| Output schemas are open | Every object in a tool's output schema allows fields it does not list, so a client that kept the schema from an earlier version still accepts an answer with a new field. A client that connected before this change kept a closed schema: it accepts answers again once it reconnects. |
| The REST API adds it too | POST /v1/diagrams/draw, /v1/diagrams/convert-mermaid, and /v1/patterns/draw answer with the same viewUrl. |
7. Presenting and exporting
The viewer's toolbar has Present and Export. Both work on the view page, on a hosted diagram's page, and on an organisation's diagram page. Every file is made in your browser, and nothing is sent to Plotwork.
Presenting a diagram step by step
Present fills the screen with the diagram and shows it one part at a time.
| Kind | The steps |
|---|---|
| Flow, state, swimlane, C4, layers, Gantt, mind map, Sankey | The first box no line comes into, then the boxes it leads to, in reading order. Each box appears with the lines from the boxes already shown and their labels. A group appears with its first box. |
| Sequence | The participants first, then one message a step, in the order they are sent. |
| Any other kind | The whole diagram, as one step. |
The camera follows the presentation: each step is framed on what is shown so far, enlarged up to 2.5 times, and glides to the next frame. The last step shows the whole diagram. Whole diagram in the bar keeps the whole diagram in view instead, and the page remembers your choice in this browser.
A diagram with more than 40 boxes shows several boxes a step, so a presentation never has more than 40 steps. Nothing moves between steps: each part is where it is in the whole diagram.
| Key or gesture | What it does |
|---|---|
| Right arrow, down arrow, Space, Page Down, Enter | The next step. A presentation remote's "next" is Page Down. |
| Left arrow, up arrow, Page Up, Backspace | The step before. |
| Home, End | The first step, the whole diagram. |
| Escape, or the close button | Stops presenting. |
| Tap | The next step. A tap on the left third of the screen goes back. |
| Swipe left, swipe right | The next step, the step before. |
A screen reader hears the step number and the names of what it adds. With reduced motion turned on in your system settings, each step appears at once instead of fading in.
A hosted diagram's page reads the diagram's text from its public link to find the steps. Where the page may not read it, the diagram is presented whole, as one step.
Exporting a file
| Format | What you get | Plan |
|---|---|---|
| PNG | A picture at one, two or four times the diagram's size, on its light or dark paper. The page shows the size in pixels before you download. A very large diagram is drawn smaller, so the picture stays within what a browser can draw. | Every plan |
| One vector page the size of the diagram, sharp at any zoom and when printed. The text is set in Helvetica and fitted to the width the diagram was drawn for, so no word leaves its box. Shadows are left out, and a script other than Latin does not print: use the PNG for those. | Pro | |
| PowerPoint | A 16:9 deck with an optional title slide, then one slide for each presentation step, framed the way the presentation frames it, the last showing the whole diagram. Each slide holds a sharp PNG, centred, and its speaker notes name what the step adds. | Pro |
A diagram that follows your light or dark setting asks which colours the file keeps, and starts from the ones on screen. A diagram drawn for one scheme keeps its own.
The plan is the plan of the person exporting. For an organisation's diagram it is the plan of the organisation's owner, the same as its other limits. Someone with only a link who is not signed in can present the diagram and download a PNG, and the Export box says how to sign in for the rest.
See also
| Doc | Why |
|---|---|
| MCP server | The tools, the hosted and local servers, and their settings |
| Hosted diagrams | A public link to the picture, without the source |
| Plans and billing | What the Pro plan adds, PDF and PowerPoint downloads among it |
| Editing an existing diagram | Reading the source back from a picture |
| Privacy policy | What is stored, what is not, and what a view link carries |
| draw_diagram | The tool as the server describes it |