AgentDraw

中文 README

AgentDraw helps coding agents create editable diagrams and article-style visual boards.

Ask Claude Code, Codex, Cursor, or another agent to draft a clean SVG or Mermaid diagram, convert it into an editable .agentdraw.json whiteboard, open it in a local browser editor, and export JSON, SVG, or PNG when you need to share the result.

Install

Recommended for agent workflows:

npm install -g @aidraw/agentdraw
npx skills add agentdraw/agentdraw --skill agentdraw -g -y

Agent bootstrap URL:

https://raw.githubusercontent.com/agentdraw/agentdraw/main/INSTALL.md

CLI-only usage:

npm install -g @aidraw/agentdraw
agentdraw --help
agentdraw guide

No global install:

npx @aidraw/agentdraw@latest import-svg board.svg --out board.agentdraw.json --style boardroom --json
npx @aidraw/agentdraw@latest open board.agentdraw.json --background --open

Quick Start

Convert an SVG draft into an editable local board:

npx @aidraw/agentdraw@latest import-svg board.svg --out board.agentdraw.json --style boardroom --json
npx @aidraw/agentdraw@latest repair board.agentdraw.json --style boardroom --write --json
npx @aidraw/agentdraw@latest validate board.agentdraw.json --style boardroom --json
npx @aidraw/agentdraw@latest open board.agentdraw.json --background --open

Use Mermaid for formal diagram grammar:

npx @aidraw/agentdraw@latest import-mermaid flow.mmd --out flow.agentdraw.json --style blueprint-formal --json

Run from this repository:

pnpm install
pnpm build
pnpm agentdraw open examples/complex-agentdraw-workbench.agentdraw.json --background --open

Gallery

AgentDraw examples are real editable scene files. Preview images are shown here for scanning; click an image to open the corresponding .agentdraw.json source.

Complex Board

Theme Examples · bundled design systems and visual moods

Theme previews link to the design.md system that produced the look.

System Formal · precise architecture and workflow diagrams	Boardroom · executive operating reviews and decisions
Blueprint Formal · technical systems and protocols	Runtime Doc · technical document explainers
Slate Notes · clean product spec boards	Manual Cream · retro instruction manuals
Riso Brut · editorial launch and growth loops	Grove · grounded strategy and planning maps
Mint Brut · playful product roadmaps	Coral · warm journeys and onboarding maps
Violet Marker · clustering and research walls	Archive Shelf · catalog-card research maps
Inkline · severe technical memos and specs	Espresso Paper · warm executive decision pages
Incident Dark · dark RCA and incident reports	Neon Grid · high-energy event and signal maps
Soft Pop · friendly product and onboarding maps	Raw Grid · strict validation and issue matrices
Bold Poster · high-impact thesis boards	Soft Editorial · research and discovery boards
BlockFrame · playful maker workflows	Long Table · warm action tables and agendas
Pin & Paper · pinned workshop synthesis boards	Hatch Whiteboard · hand-drawn data whiteboards
Crayon Stack · playful idea stacks and maker maps

Data Whiteboard Examples · hand-drawn editable data-flow boards

These examples use Hatch Whiteboard and the rules in data-flow-whiteboard-patterns.md.

D01 Transform Lanes · MapReduce-like staged transforms	D02 Warehouse Layer Ladder · layered data warehouse lineage
D03 Spaghetti To Structure · chaos-to-governed target state	D04 Governance Swimlanes · trust-building data governance lanes

Layout Examples · communication structures, not just color themes

The layout rules live in editorial-layouts.md.

E01 Monochrome Big Number · three-stage editorial argument	E02 Reading Room Overlap · calm thesis with staggered panels
E03 Swiss Statement Grid · executive claim plus evidence grid	E04 Editorial Sidebar · asymmetric article visual
E05 Poster Ledger · punchy headline with ruled proof rows	E06 Reading Room Index · long-form synthesis with several anchors
E07 Strategic Quadrant · SWOT and positioning analysis	E08 Editorial Timeline · time progression with one inflection point
E09 Roadmap Terrace · phased roadmap and maturity ladder	E10 Decision Scoreboard · option comparison and recommendation
E11 Ecosystem Orbit · stakeholder and platform force maps	E12 Pyramid Stack · hierarchy, maturity, and dependency levels

Why AgentDraw

Agent-generated whiteboards often fail in predictable ways: text overlaps, labels are not centered, arrows miss their targets, or raw whiteboard JSON drifts into messy coordinates. AgentDraw turns that into a repeatable workflow:

• Mermaid for formal diagrams with mature grammar;
• restricted SVG for custom explanatory visuals and article images;
• editable .agentdraw.json output instead of screenshots;
• reusable design systems and layout rules instead of one-off colors;
• repair, validation, quality scoring, preview export, and browser editing in one loop.

The goal is simple: fewer tokens, faster generation, and a better first visual that a human can still adjust.

Core Ideas

intent/source
  -> provider routing
  -> design style + layout system
  -> Mermaid or SVG source
  -> editable .agentdraw.json
  -> repair / validate / quality / preview
  -> local browser editor

• Use Mermaid for flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, timelines, journeys, and other structured notation.
• Use SVG for article visuals, architecture explainers, mechanism maps, strategy one-pagers, and slide-like single-page boards.
• Keep design style separate from layout style. A theme controls visual language; a layout controls reading path, hierarchy, and information structure.

More Docs

• Install options
• Detailed CLI and formats
• Style system
• Design eval
• Playbook eval
• Related project research

Inspired By

AgentDraw is shaped by several projects and ideas:

• Excalidraw
• Mermaid
• Drawnix
• beautiful-feishu-whiteboard
• open-design
• Google design.md
• guizang-ppt-skill
• html-ppt-skill
• next-ai-draw-io
• ai-excalidraw
• fireworks-tech-graph
• architecture-diagram-generator
• GitHub excalidraw-diagram-generator skill

License

MIT