Diagram Design: Set Up Claude Code or Codex for Clearer Diagrams

Diagram Design is a third-party skill/plugin for coding agents that turns a written brief into an HTML file with inline SVG diagrams. It is not a standalone web-based diagram editor. Its useful promise is narrower: give an agent a specific process and visual direction, then review an editable browser-ready diagram rather than starting from a blank canvas.

Three practical takeaways

1. Use in-session slash commands for Claude Code and terminal CLI commands for Codex.
2. Describe the flow, constraints, and output path before asking for drawing.
3. Treat every generated diagram as a draft: verify logic, labels, privacy, and export needs yourself.

What it does, and what it does not do

The plugin can create several diagram layouts and produces static HTML by default. The inline SVG approach makes the result convenient to open, inspect, and share. Keep the request focused on the decision or process the reader must understand.

Existing Mermaid, draw.io, or Excalidraw material can be source material for a redraw, not a lossless conversion. Ask what it will retain, merge, or remove, and keep a short fidelity ledger when details matter. Simplification should not quietly erase an approval step or exception.

The content-site architecture example from the official gallery. © 2025 Cathryn Lavery, MIT License. View the original example

This example does more than arrange boxes. Labels and line styles distinguish the incoming reader request, the origin’s MDX and CMS access, and the response path. When reviewing your own diagram, first ask what moves where, then evaluate color and layout.

Install and prepare

Before you install: four things to prepare

This plugin does not install Claude Code or Codex for you. Start with a host in which you can already open a project and hold a normal conversation. Keep host installation, account access, and plugin setup separate when troubleshooting.

• One host: choose the tool you actually use. Do not mix Claude Code's slash commands with Codex's terminal commands.
• An output project: work in the project that should own the HTML. Save results with your documents rather than in the plugin's bundled example directory.
• A short brief: list the stages, connection directions, intended reader, and conditions that cannot be removed. Use fictional details for the first attempt.
• A modest first deliverable: start with static HTML. Opening that file in a browser is a separate task from preparing PNG export dependencies.

The commands below use marketplace installation. A beginner does not need to clone the repository or link a skill directory for this path. Editable, developer-oriented installation is a separate option; avoid combining two installation paths while trying to get the first diagram working.

This is a document-based guide, not a hands-on test. Command availability can vary by client version, so check the current project README before using them.

Claude Code

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

Run those exact slash commands inside Claude Code, not in your operating system terminal.

Codex

codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design

Before installing any third-party plugin, inspect its repository and requested permissions. This is a sensible editorial recommendation, not a security guarantee.

Option	Where you run it	Best first check
Claude Code	Claude Code interactive command input	Confirm the marketplace and plugin commands are supported by your installed client.
Codex	Terminal with the Codex CLI	Confirm the current README matches your CLI version and organization policy.

Check that the installation is ready

1. Check the input context. Use Claude Code's interactive input for the slash commands, or a terminal for codex plugin. Follow any instructions returned by the host rather than treating every command completion as proof that the whole workflow works.
2. Request a diagnostic. The official Cookbook documents the cross-host request run diagram-design doctor. The diagnostic is not itself a package-installation step. Do not assume every host accepts the same slash-command alias.
3. Try a small brief. Before drawing, check that the agent identifies the diagram type, size, and planned simplifications. If it asks about brand or style, that can be normal first-run setup rather than an installation failure. Explicitly choose the default style if you do not need customization.

A review-first workflow

1. Write the process in plain language. State the audience, decisions, exceptions, and the one thing the diagram must not imply.
2. Set rendering constraints. Specify the layout, approximate size, static HTML, and where the output should be saved.
3. Ask for a plan before drawing. Have the agent list planned nodes and any cuts or merges. This is where a fidelity ledger helps.
4. Generate and open the HTML. Check arrows, labels, missing steps, and whether the diagram reflects actual business logic.
5. Export only when needed. Keep HTML as the editable first artifact; request SVG or PNG for publishing channels that need them.

An example prompt

Use the diagram-design skill with the default style to create a doc-inline flowchart for this support process: incoming customer request → classify request → search approved FAQ → draft response → human review. There must be five nodes and no automatic send step. Produce static HTML, preserve the human-review gate, and first confirm planned nodes and any cuts. Save the illustrative output to docs/diagrams/support-review.html.

If the result is unclear, do not only say “make it better.” Point to the defect: “the FAQ search must occur after classification,” “if rejected drafts return for revision in your real workflow, show that path explicitly,” or “make labels readable at document width.” For a missing step, ask for the revised node list first, then redraw.

The brief above, separated into scope and review criteria. The key constraint is not to invent an automatic send step.

Two more briefs you can adapt

These examples show how to define a request, not a record of completed runs. Replace the components and decisions with the structure you actually need to explain.

Example 2: a service overview. For a web app, API server, and database, the important question is how components connect. Limiting the component list helps prevent a simple explanation from acquiring infrastructure you never specified.

Create an architecture concept diagram with exactly three components:
web app, API server, and database.
Distinguish request and response directions. Do not add other infrastructure.
Use static HTML and save it to docs/diagrams/service-overview.html.
Confirm the connections and planned simplifications before drawing.

Example 3: a content review process. A process with approval needs both the normal route and the revision route. Make the return path explicit instead of expecting a diagram to infer how rejected drafts are handled.

Diagram this process: plan → draft → fact-check → editor approval → publish.
If approval is declined, return the flow to draft.
Do not remove the review gate or add an automatic publishing step.
Create a static HTML flowchart for a document and confirm the stage list first.

Exports and troubleshooting

Open the generated HTML before exporting. HTML is the complete composition; an SVG export is the diagram itself, so editorial headers or cards may not be included. In Claude Code, the documented export example is:

/diagram-design:export-diagram docs/diagrams/support-review.html

In non-Claude clients, ask in natural language to export the selected HTML. If the HTML opens correctly but PNG export fails, investigate the export environment before rebuilding the diagram. PNG generation uses Playwright and Chromium. The official Cookbook gives this local setup example:

python -m pip install playwright
python -m playwright install chromium

Use these commands only when you need PNG, Python is available, and your environment permits package installation. If the commands are unavailable, check the interpreter and organization policy instead of guessing a required version or path. Google Fonts can create external font requests, so do not assume fully offline typography.

What counts as a finished result?

• The file exists where you requested it. Open the saved HTML in a browser rather than relying only on a completion message.
• The logic matches the brief. Count the components, follow the arrow directions, and confirm the approval or revision path was not simplified away.
• The exported image is usable. Open the PNG or SVG and check labels at the size you intend to publish, not only in a large browser view.
• The format includes what you need. Diagram-only exports are different from the complete editorial page. Consider browser print or a full-page capture when the surrounding cards and headings are required.

Costs, privacy, and maintenance

A public source repository does not mean every AI model interaction is free. Host subscription, API, and organization usage costs can differ, so check the account and workspace terms that apply to you rather than assuming a price. Do not put customer data, sensitive identifiers, keys, or other secrets into a diagram request. Before public sharing, review generated HTML, scripts, and loaded fonts.

The plugin may offer brand onboarding, manual tokens, and defaults on first use. Brand onboarding can fetch a public homepage, so use care with private domains or inputs. Managed style-guide changes can be overwritten by updates; prefer named profiles stored outside the package.

FAQ

Is this a replacement for a diagram editor?

Not a direct replacement for every workflow. It generates HTML/SVG artifacts through a coding agent; a dedicated editor may be a better fit when direct canvas manipulation is the main job.

Can I trust the generated flow without review?

No. Check the source process, planned node list, rendered arrows, labels, omitted exceptions, and final business logic. This guide makes no accuracy or security guarantee.

Official example copyright and license

Diagram Design · MIT License

MIT License

Copyright (c) 2025 Cathryn Lavery

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Official sources

• Diagram Design README (checked 16 September 2026)
• Diagram Design Cookbook (checked 16 September 2026)
• Diagram Design gallery (checked 16 September 2026)

한국어로 읽기: Diagram Design 한국어 가이드