How to Install Diagram Design in Codex and Claude Code

Diagram Design is a third-party agent plugin that helps Codex CLI and Claude Code create structured architecture diagrams, flowcharts, sequence diagrams, timelines and other technical visuals as standalone HTML and SVG. It can also redraw Mermaid and draw.io sources, apply a brand palette and export a finished diagram as SVG or PNG.

The shortest Codex CLI setup is two marketplace commands. Claude Code uses two slash commands inside a session. After installation, start with a small architecture diagram in a disposable project, review the generated file and only then use it in a real repository.

Quick answer: install Diagram Design

For Codex CLI, run these commands in a terminal:

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

These direct Git-marketplace commands come from the Diagram Design repository. OpenAI’s current plugin documentation also says Codex CLI users can enter /plugins to open the plugin browser, then start a new session after installation. The Codex IDE extension does not currently support plugins.

Start a new Codex session after installation. The Diagram Design README states that Codex refreshes configured Git marketplaces at startup. To fetch the current marketplace immediately, the project documents:

codex plugin marketplace upgrade diagram-design

For Claude Code, enter these commands inside a Claude Code session:

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

Claude Code keeps third-party marketplace auto-updates off by default. Open /plugin, select Marketplaces, choose Diagram Design and decide whether to enable auto-update. Run /reload-plugins when Claude Code prompts you, or start a new session.

What Diagram Design does

Diagram Design is an MIT-licensed agent skill and plugin. Its repository currently documents dozens of visual formats, including architecture, flowchart, sequence, state-machine, entity-relationship, timeline, swimlane, quadrant, tree, layer-stack and data-flow diagrams.

The normal output is a self-contained HTML file containing an inline SVG. Static output is the default. Optional motion exists for ordered explanations, but you do not need it for normal documentation. The project also includes text-based import paths for Mermaid and common draw.io containers, plus an optional brand-onboarding workflow that reads a website and proposes colour and font tokens.

This is different from asking a general chatbot to draw random boxes. The plugin supplies a design system, layout rules, visual-type guidance and validation steps to the host agent. The host still reads and writes files, so you should review every output before committing or publishing it.

Prerequisites

• A current Codex CLI or Claude Code installation with third-party plugin marketplace support. OpenAI’s Codex IDE extension does not currently support plugins.
• Git access to github.com/cathrynlavery/diagram-design.
• A test directory or disposable repository for the first diagram.
• Permission to create HTML, SVG or PNG files in that directory.
• Python and Playwright only if you want PNG export. Basic HTML and SVG generation does not require the optional PNG toolchain.

The Codex manifest lists Read and Write as interface capabilities. Actual file access is still governed by your Codex permission mode and workspace boundary. Test the plugin in a narrowly scoped directory first because its workflow reads project context and saves diagram files.

Step 1: inspect the plugin before installing

Open the official repository and confirm that the owner is cathrynlavery. Review the current README, Codex manifest and security policy.

Anthropic’s plugin documentation warns that plugins and marketplaces are highly trusted components that can execute code with your user privileges. Treat the repository review as a security step, not just an installation formality.

This check matters because the project supports the latest commit on main rather than maintaining older tagged versions as separate security channels. Automatic updates are convenient, but they also mean future repository changes can reach the installed plugin. In a controlled environment, review changes before upgrading.

Step 2: install Diagram Design in Codex CLI

Open a terminal where the codex command already works, then add the project’s Git marketplace:

codex plugin marketplace add cathrynlavery/diagram-design

Install the plugin from that marketplace:

codex plugin add diagram-design@diagram-design

Close the current session and start a new one so the plugin is loaded. If you previously installed a standalone copy with an older npx skills add workflow, the project says that copy will not automatically follow the Codex marketplace. Remove the old standalone copy before installing the marketplace version so two copies do not compete.

Step 3: install Diagram Design in Claude Code

Launch Claude Code and add the marketplace from inside the session:

/plugin marketplace add cathrynlavery/diagram-design

Then install the plugin:

/plugin install diagram-design@diagram-design

Run /reload-plugins when prompted. If you enable marketplace auto-updates, remember that third-party changes can arrive after startup. Teams with a change-control process may prefer manual review and updates.

Step 4: create a safe first architecture diagram

Create an empty test folder and open it as the active workspace. Then give Codex or Claude Code a precise prompt such as:

Using Diagram Design, create a minimal-light architecture diagram for a web app with:
- browser to reverse proxy
- reverse proxy to API
- API to PostgreSQL
- API to Redis

Save it as diagram-design-test.html in this folder.
Do not modify application files or use external assets.

Open the resulting HTML file in a browser. Check that every component, connection direction and label matches the prompt. A polished diagram can still be technically wrong, so compare it with the real system before sharing it.

If you are documenting an agent workflow rather than an application stack, the site’s ThoughtDAG guide provides an adjacent example of a task graph where accurate nodes and edges matter more than decoration.

Step 5: apply brand colours only when needed

Diagram Design can inspect a public website and propose a palette and font stack. A typical request is:

Onboard Diagram Design to https://example.com.
Show me the proposed colour and font tokens before writing any files.

Keep the approval step. Website onboarding makes a network request and may discover fonts or styles that you do not have permission to redistribute. Use your own site or another source you are authorised to inspect, review the proposed diff and confirm that the final diagram has adequate contrast.

For multiple clients, the repository documents named profiles under ~/.diagram-design/profiles/ and a project-level .diagram-design marker. Do not reuse one client’s brand profile in another project by accident.

Step 6: redraw Mermaid or draw.io diagrams

The plugin can parse Mermaid files and fenced Mermaid blocks in Markdown. It can also read common draw.io containers, including .drawio, .drawio.xml, embedded .drawio.png and .drawio.svg files.

Ask the agent to preserve meaning and report simplifications:

Redraw architecture.mmd with Diagram Design for a 16:9 slide.
Use balanced detail for a mixed technical audience.
List every node or relationship you merge, simplify or omit.

The repository describes these importers as text parsers: they do not render source HTML, run JavaScript or follow embedded links. You should still treat imported files as untrusted input and review the generated output.

Step 7: export SVG or PNG

SVG export extracts the diagram from the generated HTML and preserves its accessible title and description. In Claude Code, run /diagram-design:export path/to/diagram.html --svg-only. In Codex, ask in natural language, for example: Export diagram-design-test.html as SVG and PNG.

PNG export is optional and uses Playwright with Chromium. The project’s export guide says to install these dependencies yourself:

pip install playwright
playwright install chromium

Do not add Playwright only for basic HTML or SVG output. It downloads a browser runtime and expands the local dependency surface. Install it in a dedicated Python environment when repeatable PNG export is genuinely required.

How to update Diagram Design safely

The Diagram Design README states that Codex refreshes configured Git marketplaces at startup. For an immediate marketplace refresh, it documents:

codex plugin marketplace upgrade diagram-design

Start a new session afterward. In Claude Code, use the marketplace controls under /plugin; enable auto-update only if that matches your risk tolerance.

Before a material upgrade, finish or commit unrelated work, read the repository diff and regenerate one known test diagram. The plugin’s security policy supports only the current main branch, while the absence of tagged releases makes a conventional version pin and rollback less straightforward.

Troubleshooting Diagram Design

The Codex CLI plugin command is unknown

Your Codex CLI installation may predate plugin marketplace support, or the command may not be available in that build. Enter /plugins to check whether the plugin browser is available. Otherwise, check the current Codex installation guidance, update through the same trusted channel you originally used and retry. Do not replace the marketplace command with an unverified third-party installer.

The plugin installed but is not being used

Start a new session. State the plugin name explicitly in the first request: “Using Diagram Design, create…”. In Claude Code, run /reload-plugins after installation.

Two Diagram Design copies appear

An older standalone skill may still exist beside the marketplace installation. Remove the legacy copy using the host’s plugin or skill manager, keep the marketplace version and restart the session. Back up any custom style file first.

Brand colours disappeared after an update

Direct edits inside the installed references/style-guide.md can be replaced by managed updates. Use the project’s named-profile system or an editable local clone when you need durable customisations.

The diagram looks attractive but the architecture is wrong

Reduce the prompt to verified components and relationships. Ask the agent to list its interpretation before drawing, then correct the model in text. Diagram Design improves presentation; it cannot discover undocumented architecture reliably.

PNG export says Playwright is missing

Install Playwright and Chromium in a dedicated Python environment, then retry the export. If you do not need a raster image, request SVG instead and avoid the extra dependency.

Fonts change when the SVG opens elsewhere

Some offline design tools do not fetch remote web fonts from an SVG. Use PNG for pixel-consistent sharing, or replace the font with one available in the target environment.

Frequently asked questions

Is Diagram Design an official OpenAI or Anthropic plugin?

No. It is an independent open-source project that supplies plugin manifests for Codex CLI and Claude Code. Review its repository and permissions as you would for any third-party developer tool.

Is Diagram Design free?

The repository is published under the MIT licence. You still need access to a supported host such as Codex CLI or Claude Code, and the host’s normal usage or subscription costs can apply.

Does it send my project to another diagram service?

The standard output is generated as local HTML and SVG through the host agent. Brand onboarding intentionally fetches the website you provide, and SVG files may reference web fonts. The model provider used by Codex or Claude Code may also process the context you give the host, so follow that provider’s privacy terms and avoid exposing secrets.

Can it replace Mermaid?

It targets a different workflow. Mermaid is concise, text-first and easy to keep beside code. Diagram Design is useful when presentation, branding, multiple output sizes or a more editorial layout matter. It can redraw Mermaid sources instead of forcing you to abandon them.

Can I use it with a local coding model?

The plugin runs through a compatible agent host, not directly inside a model file. If your priority is local coding inference, start with the site’s Code Llama installation guide. Model quality affects how accurately an agent interprets a complicated system description.

Which diagram should I create first?

Start with one architecture or data-flow diagram containing fewer than ten verified components. It is easier to check than a large current-state map and quickly reveals whether the plugin’s layout and labelling suit your documentation.

Should you install Diagram Design?

Diagram Design is a sensible addition when Codex CLI or Claude Code already sits in your documentation workflow and you frequently need architecture, process or data-flow visuals. Its strongest advantage is not simply drawing boxes; it combines a reusable design system, import paths and multiple export formats.

Install it first in a disposable project, verify one small diagram and review the files it writes. Keep normal output static, use website onboarding only with permission and treat automatic updates from an untagged main branch as a conscious trust decision.

If you are choosing a coding assistant before adding specialist plugins, compare the options in the site’s coding LLM guide.

Primary sources

• Official OpenAI documentation for plugin support and installation surfaces
• Official OpenAI documentation for Codex permission modes
• Official Anthropic documentation for Claude Code plugin installation, updates and security
• Diagram Design repository and README
• Codex plugin manifest
• Claude Code plugin manifest
• Diagram Design security policy
• Official SVG and PNG export procedure
• MIT licence