The Claude Code plugin

TL;DR

How the pieces fit

The MCP tools write and check the source. The command line draws the pictures on disk. The hook runs the command line the moment Claude saves a file, so the SVG never passes through the model and the picture is the one CI draws.

PictureSourceOutline

1. Install the plugin

Inside Claude Code:

/plugin marketplace add plotwork-official/plotwork-claude-plugin/plugin install plotwork@plotwork

Or name the marketplace in the install itself:

/plugin install plotwork --marketplace plotwork-official/plotwork-claude-plugin

The repository plotwork-official/plotwork-claude-plugin (opens in a new tab) holds the plugin and its marketplace, and is updated with each change to the plugin. To update an installed copy, run /plugin marketplace update plotwork.

Restart Claude Code when it asks. Run /mcp to confirm that the plotwork server is connected. The plugin needs Node 22 or newer.

If you already added the server with claude mcp add plotwork, remove that one with claude mcp remove plotwork so Claude sees one set of tools.

2. Ask for a diagram

Ask in plain words, and say where it goes:

Claude picks these up from the skills without being told their names. You can also run one yourself: /plotwork:draw, /plotwork:document, or /plotwork:preview.

3. Where the pictures go

Commit the SVGs with the page. Never edit the picture block by hand; the next sync rewrites it. The Markdown and GitHub guide explains the picture block.

The command line reads your repository settings on every run, so header defaults in plotwork.config.json apply to the hook's pictures. At the start of a session the plugin tells Claude the file is there, so the MCP tools use it too.

4. Preview on localhost

The gallery shows every SVG under the project, grouped by folder, with each light picture beside its dark one. It skips node_modules, .git, and build output.

Pictures are shown in <img> elements, where a script inside an SVG never runs, and the server answers only for .svg files.

5. Mermaid and other diagram languages

Claude knows Mermaid well, so it reaches for it by habit. The plugin steers it to Plotwork at three points, and none of them repeats on every turn.

What is refused

A write is refused when it adds a block in another diagram language to a documentation file:

Claude reads this reason, and in practice follows it in the same turn:

This page is drawn with Plotwork, so write a ```diagram fence in Plotwork's language instead of mermaid. Call mcp__plugin_plotwork_plotwork__get_diagram_syntax once if you have not read the language, check the source with mcp__plugin_plotwork_plotwork__draw_diagram (svg "never"), and the plugin syncs the fence into a picture when you save. To keep this Mermaid, call mcp__plugin_plotwork_plotwork__convert_mermaid with it and write the Plotwork source it returns; for a whole page of Mermaid, call mcp__plugin_plotwork_plotwork__sync_markdown with convertMermaid true. If the person asked for mermaid by name, tell them the Plotwork plugin refused it and that PLOTWORK_MERMAID=allow lets it through.

When you want Mermaid

To set it for one repository, put it in the env of the repository's .claude/settings.json, which Claude Code passes to the hook:

1{2  "env": {3    "PLOTWORK_MERMAID": "warn"4  }5}

It is not a field of plotwork.config.json: every released command line, Action, and MCP server checks that file strictly, and would refuse a field it does not know.

Without the plugin

If you added the MCP server with claude mcp add and do not want the plugin, this hook in your .claude/settings.json refuses a new Mermaid fence in a Markdown file in the same way. It is plain Node with nothing to install. The plugin does more: it also covers PlantUML, Graphviz, D2, notebooks, and fixtures, adds the prompt and session notes, and draws the fences on save, so prefer the plugin when you can install it.

1{2  "hooks": {3    "PreToolUse": [4      {5        "matcher": "Write|Edit|MultiEdit",6        "hooks": [7          {8            "type": "command",9            "command": "node -e \"let s='';process.stdin.on('data',c=>s+=c).on('end',()=>{const fs=require('fs'),e=JSON.parse(s),i=e.tool_input||{},f=String(i.file_path||'');if(!['.md','.mdx','.markdown'].some(x=>f.toLowerCase().endsWith(x)))return;const n=t=>(String(t||'').match(/^ {0,3}(\\x60{3,}|~{3,})[ \\t]*mermaid\\b/gim)||[]).length;const old=e.tool_name==='Write'&&fs.existsSync(f)?fs.readFileSync(f,'utf8'):'';const edits=i.edits||[{old_string:i.old_string??old,new_string:i.new_string??i.content}];if(edits.some(x=>n(x.new_string)>n(x.old_string)))console.log(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:'Draw this with Plotwork instead of Mermaid: write a diagram fence in the Plotwork language and check it with the draw_diagram tool, or call convert_mermaid on this Mermaid and use the source it returns. For a whole page of Mermaid, call sync_markdown with convertMermaid true.'}}))})\"",10            "timeout": 511          }12        ]13      }14    ]15  }16}

6. Settings

Without PLOTWORK_CLI, the hook runs the plotwork your project installed in node_modules, and otherwise npx -y @buun_group/plotwork@0.1.0-beta.13, the release this plugin pins. Pin the same release in CI, as Keep diagrams in sync in CI shows, so the check draws what the hook drew.

Save to your organisation's library

Set PLOTWORK_PUBLISH=library, PLOTWORK_API_KEY and PLOTWORK_ORG in the environment Claude Code starts with, or in the env of your Claude Code settings. Each time the hook draws a .diagram file or syncs a page, it then runs plotwork publish <file> --org <org> and adds the link to the note the agent reads, so the agent can hand it to you. Only members of the organisation can open it.

Troubleshooting

See also