Skip to content
Connect an agent
Documentation

Diagrams for AI agents

Plotwork is a small text language and a renderer. Your agent writes the text, Plotwork checks it and draws it as SVG, and the picture looks the same in a README, in your editor and over MCP.

Quick startLanguage reference
  • 18MCP tools
  • 130API operations across 104 paths

Connect your agent

Add the local server to your client once. It runs on your machine, needs Node 22 or newer, and needs no key and no account.

Run this once, then run /mcp in Claude Code to check that plotwork is connected.

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

Also works with

  • Windsurf
  • Cline
  • Codex
  • Gemini CLI
  • GitHub Copilot
  • Goose
  • opencode
  • Roo Code
  • Kilo Code
  • Kiro
  • Amp

For the hosted server, a browser sign-in, and the other clients, see Connecting an agent.

Copy a prompt

Paste one into a connected agent and change the names to yours. Say what the diagram shows, in plain words, and the agent chooses the tools.

  • An architecture

    A network or an app on a cloud, drawn from a checked pattern with the provider icons.

    Prompt
    Use Plotwork to draw a three-tier network on Azure with a load balancer in front, and call the app tier "Billing API".
    Architecture patterns

  • A login sequence

    Who sends what to whom, in order, with the failure path as well.

    Prompt
    Use Plotwork to draw a sequence diagram of a login. A browser posts an email and password to an Auth API, which looks the user up in a Users database and answers with a session cookie, or with 401 Unauthorized when the password is wrong.
    Examples to copy

  • A schema from a migration

    Your tables and keys, read from the SQL files you already have.

    Prompt
    Use Plotwork to read the SQL migrations in db/migrations and draw the database as a schema diagram, with the primary keys and the foreign keys between the tables.
    Writing diagrams

  • Mermaid to Plotwork

    Convert the diagrams you have, and read what could not carry over.

    Prompt
    Use Plotwork to replace the Mermaid diagrams in README.md with Plotwork diagrams, tell me what could not be converted, and give me the files to write.
    Migrating from Mermaid

Pick a kind of diagram

Each kind starts with a header line, and its guide has an example to copy and the words it understands.

  • Flow

    Boxes, groups, and arrows for architecture, code flow, and decision flow.

    flow "Title"

  • Sequence

    Actors and the ordered messages between them, for auth flows and request lifecycles.

    sequence "Title"

  • Database schema

    Tables and the relations between their columns, for database schemas.

    schema "Title"

  • Git graph

    Branches as lanes, with the commits, merges, and tags along them, for a repository history.

    git "Title"

  • Gantt chart

    Tasks and milestones on a time axis, in sections and with dependencies, for a project schedule.

    gantt "Title"

  • Class diagram

    Classes with their members and the relations between them, for object models.

    class "Title"

  • State

    States and the transitions between them, with composite states, choices, and parallel regions, for lifecycles and state machines.

    state "Title"

  • Timeline

    Dated events on a rail, in the order written and grouped in sections, for a history or a roadmap.

    timeline "Title"

  • User journey

    The steps a person takes and how they feel at each, as a satisfaction curve over stages of tasks and the actors involved.

    journey "Title"

  • Mind map

    A root idea and the branches that grow from it, drawn round the root or as a tidy tree, for brainstorms and outlines.

    mindmap "Title"

  • Treemap

    Nested areas sized by value, grouped by branch, for where size or cost sits in a hierarchy.

    treemap "Title"

  • Share chart

    Parts of a whole drawn as a donut with a legend, for a few shares that add up to one total.

    pie "Title"

  • Quadrant chart

    Items placed on two axes and read by quadrant, for priorities such as impact against effort.

    quadrant "Title"

  • Layered architecture

    Stacked layers of blocks with the links between them, for layered and tiered architectures.

    layers "Title"

  • C4 diagram

    People, systems, containers, and components with their relationships and boundaries, in the C4 model of system context, container, component, deployment, and dynamic views.

    c4 "Title"

  • Matrix

    Rows against columns with meaningful cells, for options comparisons, decision matrices, RACI charts, and risk heat maps.

    matrix "Title"

  • Sankey diagram

    Flows between stages drawn as ribbons as thick as the amount, for where traffic, data, or cost goes.

    sankey "Title"

  • XY chart

    Bars, lines, and areas over a category or number axis, with reference lines, for metrics, capacity, and trends.

    xychart "Title"

  • Tree

    A hierarchy drawn as a file tree, an org chart, or an outline, for repository layouts, teams, ownership, and taxonomies.

    tree "Title"

  • Swimlane

    A process whose steps sit in lanes, one for each actor or system, with decisions and hand-offs between the lanes, for business and integration flows.

    swimlane "Title"

Read the docs as an agent

An agent can read these docs without a browser. Every page is also served as Markdown, and one index lists them all.

  • llms.txtAn index of every page, with a line on what it holds and its size in tokens. Start here.
  • /quick-start.mdOne page as plain Markdown. Add .md to the address of any page.
  • llms-full.txtThe text of every page in one file, for a search index.
How an agent reads these docs