# Quick start

> Page: https://docs.plotwork.dev/quick-start. Index of every page: https://docs.plotwork.dev/llms.txt

Connect an AI agent, ask it for a diagram in plain words, and have a checked picture in about five minutes. It is for anyone who has just added Plotwork to Claude Code, Cursor, VS Code, or Claude Desktop, and for anyone who wants diagrams in a Markdown file instead.

## TL;DR

| Question | Answer |
|---|---|
| What is Plotwork? | A small text language for twenty kinds of diagram (flow, sequence, database schema, git graph, Gantt chart, class, state, timeline, user journey, mind map, treemap, pie chart, quadrant chart, layered architecture, C4, matrix, Sankey, XY chart, tree, and swimlane), and a renderer. Your agent writes the text, Plotwork checks it and draws it. You never draw boxes by hand. |
| What do I do first? | [Connect your agent](https://docs.plotwork.dev/mcp/connect.md) once, then paste the first prompt in step 2. |
| What do I say to the agent? | Plain words: what the diagram shows and who it is for. You do not name tools. Copy a prompt from this page or from the [examples](https://docs.plotwork.dev/examples.md). |
| What comes back? | The diagram text, any mistakes with line and hint, a plain-text outline to check the meaning, and the picture in light and dark. |
| How do I see the picture? | Ask the agent to save it as a file, put it in a Markdown file, or, on the hosted server, publish a link. Step 4 has the words to use. |
| How do I change it? | Say what is wrong, such as "put a cache between the API and the database". The agent edits the text and draws again. |
| No agent? | Write a `diagram` fence in a Markdown file and send the file to the HTTP API, which answers with the picture files to save. This needs the Pro plan and an API key. See step 8. |

## 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:

```sh
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](https://docs.plotwork.dev/mcp/connect.md).

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](https://docs.plotwork.dev/mcp/connect.md#6-troubleshooting).

## 2. Ask for your first diagram

Paste this into your agent:

```text
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.

| Step | Tool | What it does |
|---|---|---|
| 1 | `get_diagram_syntax` | The agent reads the language once. |
| 2 | `draw_diagram` | The agent sends the diagram text. If the text has mistakes, Plotwork returns every one with its line, column, and a hint, and draws nothing. |
| 3 | `draw_diagram` again | The agent fixes each mistake and calls again until the text is valid. A valid diagram comes back with warnings (such as a suggested icon), an outline, and the picture. |
| 4 | none | The agent compares the outline with your request and answers. |

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.

**Diagram source**

```diagram
flow "How a login request is checked" desc="A user signs in through an API that checks the password against a database and answers with a session or an error." direction=down

node user  person   "User"
node api   service  "Auth API"     sub="POST /login"
node db    database "Users DB"
node check decision "Password correct?"
node ok    terminal "Session issued" icon=status:success
node deny  terminal "401 Unauthorized" icon=status:error

user  -> api   : "email and password"
api   -> db    : "look up user" role=data
db    -> check
check -> ok    : "yes"
check -> deny  : "no"
```

*Picture: How a login request is checked: 6 nodes, 5 connections. A user signs in through an API that checks the password against a database and answers with a session or an error.*

**Text description**

**Nodes:**

- User, person
- Auth API (POST /login), service
- Users DB, database
- Password correct?, decision
- Session issued, terminal
- 401 Unauthorized, terminal

**Connections:**

- User to Auth API: email and password
- Auth API to Users DB (stored data line): look up user
- Users DB to Password correct?
- Password correct? to Session issued: yes
- Password correct? to 401 Unauthorized: no

| Line | Meaning |
|---|---|
| `flow "Title" direction=down` | The first line names the kind (`flow`, `sequence`, or `schema`) and gives a title. `direction` says which way it reads. |
| `node id type "Label"` | One box. The id is how arrows refer to it. The type (`person`, `service`, `database`, `decision`, `terminal`, and more) picks the icon and the shape. |
| `a -> b : "label"` | An arrow from `a` to `b`, with an optional label. `-->` draws a dashed arrow. |
| `group id "Name" { ... }` | A box around other nodes, for a network, a tier, or a team. See the [examples](https://docs.plotwork.dev/examples.md). |

The full language, kind by kind, is in [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md).

## 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:

| You want | Say |
|---|---|
| A file to open | "Save the light and dark SVGs to docs/diagrams/login.svg and docs/diagrams/login.dark.svg." Open the file in a browser or in VS Code. |
| The diagram in a README or doc | "Add this diagram to README.md under a Login heading, and render it." The agent uses `sync_markdown`, and GitHub shows the picture and switches to dark mode on its own. See [Markdown and GitHub](https://docs.plotwork.dev/markdown-and-github.md). |
| A link to paste in chat or a pull request | "Publish it and give me the link." This needs the [hosted server](https://docs.plotwork.dev/hosted-diagrams.md); it returns a public link and a Markdown image to paste. |
| A private copy for your team | "Publish it to the Platform organisation." Members of the [organisation](https://docs.plotwork.dev/organisations.md) see it after signing in. Nobody else can. |

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:

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

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

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

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

```text
Number the steps.
```

```text
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:

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

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

```text
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](https://docs.plotwork.dev/agents/prompts.md). Ready-made diagrams you can copy are in the [examples](https://docs.plotwork.dev/examples.md).

## 7. If something is not right

| Symptom | Cause | Fix |
|---|---|---|
| The agent writes a Mermaid diagram or ASCII art | It did not call the tools | Say "Use Plotwork" in the prompt, or add the [rules file](https://docs.plotwork.dev/agents/rules.md) to your project. |
| The agent keeps fixing the same mistake | The hint is not being applied | Ask it to read the error out loud, then to read the language again with `get_diagram_syntax`. |
| No picture in the answer | The diagram is large, or the client hides tool output | Ask for a file or a link, as in step 4. |
| The picture is too wide to read | Many boxes in one row | Say "make it read top to bottom" or "split it into two diagrams". |
| The icons are generic | The agent did not look up product names | Say "choose icons for every service with `map_icons`". |

## 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:

````md
```diagram
flow "Login request"
node user person  "User"
node api  service "Auth API"
node db   database "Users DB"
user -> api : "POST /login"
api  -> db  : "look up user" role=data
```
````

The [command line](https://docs.plotwork.dev/cli/quick-start.md) draws every fence of a file on your machine, with no account or key:

```sh
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](https://docs.plotwork.dev/plans-and-billing.md) and an API key from [app.plotwork.dev](https://app.plotwork.dev). Send the whole file and its path. The command reads the key from the environment variable `PLOTWORK_API_KEY`:

```sh
jq -n --rawfile markdown notes.md '{markdown: $markdown, documentPath: "notes.md"}' |
  curl -s -X POST https://api.plotwork.dev/v1/markdown/sync \
    -H "X-API-Key: $PLOTWORK_API_KEY" \
    -H "content-type: application/json" \
    -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](https://docs.plotwork.dev/markdown-and-github.md).

## Next steps

| Doc | Why |
|---|---|
| [Examples to copy](https://docs.plotwork.dev/examples.md) | Eight ready diagrams with the prompt for each: a login flow, services, a sequence, a schema, AWS, a release pipeline, numbered steps, and a data flow that moves |
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | Flow, sequence, and schema diagrams, groups, icons, and cloud architecture, with a guide for each of the seven other kinds |
| [Prompts and recipes](https://docs.plotwork.dev/agents/prompts.md) | What to say and which tool answers |
| [Hosted diagrams](https://docs.plotwork.dev/hosted-diagrams.md) | Publish a link to a diagram |
| [Organisations](https://docs.plotwork.dev/organisations.md) | Share a private diagram library with your team |

## See also

| Doc | Why |
|---|---|
| [Connecting an agent](https://docs.plotwork.dev/mcp/connect.md) | Client settings, sign-in, and troubleshooting |
| [MCP server](https://docs.plotwork.dev/mcp/overview.md) | The tools and how they behave |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | Every word the language accepts |
| [How a diagram is drawn](https://docs.plotwork.dev/how-it-works.md) | What happens between your text and the picture |