Quick start

TL;DR

1. Connect your agent

Do this once per client. The quickest way is the local server: it runs on your machine, needs Node 22 or newer, and needs no key and no account.

For Claude Code:

claude mcp add plotwork -- npx -y @buun_group/plotwork-mcp@0.1.0-beta.10

Then run /mcp inside Claude Code. plotwork should be listed as connected. For Cursor, VS Code, Claude Desktop, the hosted server, and sign-in without a key, follow Connecting an agent.

Check it worked by asking your agent: "Which Plotwork tools do you have?" It should name draw_diagram, get_diagram_syntax, draw_from_pattern, and others. If it names none, see Troubleshooting.

2. Ask for your first diagram

Paste this into your agent:

Use Plotwork to draw a diagram of how a login request is checked. A user sends an email and password to an Auth API. The API looks the user up in a Users database. If the password is correct a session is issued, otherwise the API answers 401 Unauthorized. Draw it, then tell me in one sentence what it shows.

Here is what happens, step by step. You see these as tool calls in your client.

You did not write any diagram text. The agent did.

3. Read what the agent wrote

This is the kind of text the agent sends. It is plain, one statement per line, and you can read it and edit it by hand.

PictureSourceOutline

The full language, kind by kind, is in Writing diagrams.

4. See the picture

The agent gets the picture as SVG text. Your client shows it as text unless the agent saves or publishes it, so ask for what you want:

A large diagram, about 30 nodes or more, comes back without its picture so that the answer fits what a client can read. The check and the outline still arrive. Ask for a file or a link and you get the picture.

5. Change it

Say what is wrong in words. The agent edits the text and draws again. These all work:

Add a Redis cache between the API and the database, and show that the API reads from it first.

Rename "Auth API" to "Identity service", and put the service and the database in a group called "Backend".

Use AWS icons: API Gateway for the entry point, Lambda for the service, and DynamoDB for the database.

Make it read left to right, and add a step after "Session issued" that sends a welcome email.

Number the steps.

Animate the flow.

You can also edit the text yourself and tell the agent: "I changed the diagram, check it and draw it again."

6. Start from something that exists

You do not need a blank page. These prompts start from a checked pattern or from Mermaid you already have:

Draw a three-tier network on Azure with a load balancer in front, and call the app tier "Billing API".

Convert this Mermaid flowchart to Plotwork, tell me what was lost, and draw it.

Replace the Mermaid diagrams in README.md with Plotwork diagrams and give me the files to write.

More prompts, each with the tool it leads to, are in Prompts and recipes. Ready-made diagrams you can copy are in the examples.

7. If something is not right

8. Without an agent: Markdown and the HTTP API

The text is the same without an agent. Write a diagram fence in any Markdown file, using text like the example in step 3:

1```diagram2flow "Login request"3node user person  "User"4node api  service "Auth API"5node db   database "Users DB"6user -> api : "POST /login"7api  -> db  : "look up user" role=data8```

The command line draws every fence of a file on your machine, with no account or key:

npx -y @buun_group/plotwork@0.1.0-beta.13 sync notes.md

Over HTTP, Plotwork draws the fences of a document in one call, POST /v1/markdown/sync, the HTTP form of the sync_markdown tool. Calling the drawing routes of the API directly needs the Pro plan and an API key from app.plotwork.dev (opens in a new tab). Send the whole file and its path. The command reads the key from the environment variable PLOTWORK_API_KEY:

1jq -n --rawfile markdown notes.md '{markdown: $markdown, documentPath: "notes.md"}' |2  curl -s -X POST https://api.plotwork.dev/v1/markdown/sync \3    -H "X-API-Key: $PLOTWORK_API_KEY" \4    -H "content-type: application/json" \5    -d @- > result.json

result.json holds the rewritten document in markdown, the light and dark SVG files in files, each with its path and content, and a report with the line and a hint for every mistake. Plotwork writes nothing itself: save markdown over notes.md and each entry of files at its path. Send "mode": "check" as well and the call changes nothing and says in changed whether a picture is stale, which is the form to run in CI. How the picture block works and where it shows is in Markdown and GitHub.

Next steps

See also