{
  "markdown": "# excalidrawer\n\nCode-first Excalidraw diagram generation — CLI, MCP server, and SVG/PNG export.\n\n## Why not just use Excalidraw directly?\n\n[Excalidraw](https://excalidraw.com) is a fantastic *drawing* tool — you open a\ncanvas and arrange boxes by hand. excalidrawer is a *generation* tool: it turns\ncode (or a structured spec, or an agent's intent) into the same hand-drawn-style\ndiagrams, with **no browser and no manual dragging**.\n\nUse Excalidraw when a human is sketching once. Reach for excalidrawer when the\ndiagram needs to come out of an automated pipeline:\n\n- **In code / scripts** — build diagrams from data, keep them in version control,\n  and regenerate deterministically (fixed seed → clean diffs) instead of\n  re-dragging boxes every time the source changes.\n- **In CI / docs builds** — render `.svg` / `.png` as a build step so the diagrams\n  in your README or docs site never drift from the system they describe.\n- **In an AI agent** — the MCP server (and the agent plugin's skills) let an\n  agent produce a diagram in-context (\"draw the auth flow\") without leaving the\n  conversation.\n\nIt produces real `.excalidraw` files, so the output is still fully editable in\nExcalidraw afterward — generate the first draft programmatically, hand-tweak if\nyou want.\n\n## Install\n\nMost users want the **agent plugin** — it bundles the flowchart / timeline /\narchitecture / sequence / comparison skills and wires them to the MCP server, so you can\njust say *\"draw the auth flow\"* inside Claude Code or Codex. The CLI and\nlibrary entry points are below for scripting and custom use cases.\n\n### Agent plugin (Claude Code / Codex, recommended)\n\nTwo commands and you're done — the plugin bundles the skills **and**\nauto-registers the MCP server via its manifest (no global npm install, no\nseparate `claude mcp add` / `codex mcp add`).\n\nIn Claude Code:\n\n```bash\n/plugin marketplace add guohaonan-shy/excalidrawer\n/plugin install excalidrawer@excalidrawer-dev\n```\n\nIn Codex:\n\n```bash\ncodex plugin marketplace add guohaonan-shy/excalidrawer\ncodex plugin add excalidrawer@excalidrawer-dev\n```\n\nCodex reads this repo's `.claude-plugin/marketplace.json` directly, so both\nclients get the same skills and the same auto-registered MCP server — verify\nwith `codex plugin list` / `codex mcp list`.\n\nThe MCP server runs via `npx`, so the first invocation downloads the package\ninto the npx cache (~5-10 s); subsequent runs use the cache.\n\n> Auto-registering the MCP server from the plugin manifest is a plugin-host\n> feature. In a client that doesn't install plugins, register the MCP server\n> directly — see [MCP Server](#mcp-server) below.\n\n### CLI & MCP server only\n\nIf you only want the binaries (e.g. to script `excalidrawer render` in a build):\n\n```bash\nnpm install -g excalidrawer\n```\n\nThis puts two commands on your PATH:\n\n- `excalidrawer` — the CLI (`render`, `compute-layout`)\n- `excalidrawer-mcp` — the MCP server that MCP clients launch\n\n### Library\n\nOnly needed for the programmatic API (see [Custom Scripts](#custom-scripts)):\n\n```bash\nnpm install excalidrawer\n```\n\n## MCP Server\n\n`excalidrawer-mcp` is a stdio MCP server exposing two tools:\n\n| Tool | What it does |\n|------|--------------|\n| `render_diagram` | Render an array of sugar shorthand or raw Excalidraw elements to `.excalidraw` / `.svg` / `.png` files. |\n| `compute_layout` | Compute coordinates from a layout helper (grid, chain, swimlane, hub-and-spoke, edge anchors, U-routing, label anchors, titled boxes, row equalization). |\n\nEach command below registers the server with\n`npx -y -p excalidrawer@latest -c excalidrawer-mcp` — no global install needed,\nand always the latest published version.\n\n### Claude Code\n\n```bash\nclaude mcp add excalidrawer -- npx -y -p excalidrawer@latest -c excalidrawer-mcp\n```\n\nVerify with `claude mcp list` — it should report `✓ Connected`.\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\nor `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows), then restart the app:\n\n```json\n{\n  \"mcpServers\": {\n    \"excalidrawer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"excalidrawer@latest\", \"-c\", \"excalidrawer-mcp\"]\n    }\n  }\n}\n```\n\n### Codex\n\nOnly if you want the two MCP tools **without** the skills. The recommended\nCodex path is [the plugin](#agent-plugin-claude-code--codex-recommended), which\nbrings the skills and this MCP server together — a bare `codex mcp add` gives\nyou `render_diagram` / `compute_layout` but none of the recipes (palette\nconventions, back-edge routing, swimlane parameters, quality gates).\n\n```bash\ncodex mcp add excalidrawer -- npx -y -p excalidrawer@latest -c excalidrawer-mcp\n```\n\n## Agent Skills\n\nThe [`skills/`](skills/) directory holds one skill per diagram type plus a\nshared base they all read first. They ship as part of the agent plugin above —\nClaude Code and Codex both install them.\n\n| Skill | Use for | Trigger keywords |\n|-------|---------|------------------|\n| `flowchart` | Decision flows, process diagrams, branching logic | flowchart, 流程图, decision tree, yes/no, approval flow |\n| `timeline` | Timelines, roadmaps, project milestones | timeline, 时间线, roadmap, milestone, Q1/Q2 phases |\n| `architecture` | System architecture, layered components, topology | architecture, 架构图, 3-tier, microservices, data platform |\n| `sequence` | Sequence diagrams, multi-actor interactions, call chains | sequence diagram, 时序图, interaction, handshake, OAuth |\n| `comparison` | Left-vs-right comparisons, A vs B, before/after, trade-offs | compare, A vs B, 对比图, side-by-side, before and after |\n| `shared` | Common base — conventions, sugar schema, palette, output rules (read first, not invoked directly) | — |\n\nEach type skill declares a prerequisite — *read `../shared/SKILL.md`\nfirst* — so the cross-cutting rules live in one place instead of being copied\ninto every type skill. Given a request, a type skill clarifies intent with a couple of\n`AskUserQuestion` prompts, reads its recipe under `references/`, composes sugar\nelements, then calls the MCP server's `render_diagram` tool to emit\n`.excalidraw` / `.svg` / `.png`.\n\n> All skills call the `excalidrawer-mcp` server. The plugin install above ships\n> a manifest that registers it automatically; without the plugin, wire up the\n> MCP server per [MCP Server](#mcp-server).\n\n## CLI\n\n```bash\n# Render sugar / raw Excalidraw elements to files\nexcalidrawer render -i elements.json -o docs/diagram\ncat elements.json | excalidrawer render -o docs/diagram -f svg,png\n\n# Compute layout coordinates (prints JSON)\nexcalidrawer compute-layout --helper gridLayout -a '{\"count\":6,\"cols\":3,\"cellW\":140,\"cellH\":50}'\n```\n\n`render` accepts either a bare element array or `{ \"elements\": [...] }`. The\n`render` / `compute-layout` commands share the exact tool definitions the MCP\nserver uses, so the two surfaces never drift.\n\n## Custom Scripts\n\n`render()` takes the same sugar shorthand the MCP server uses and returns the\nrendered outputs — drop it into any script:\n\n```javascript\nimport { writeFileSync } from \"fs\";\nimport { render } from \"excalidrawer\";\n\nconst elements = [\n  { shape: \"rect\", id: \"start\",   at: [20, 80],  size: [130, 56], fill: \"yellow\", text: \"Start\" },\n  { shape: \"rect\", id: \"process\", at: [240, 80], size: [150, 56], fill: \"blue\",   text: \"Process\" },\n  { shape: \"rect\", id: \"done\",    at: [460, 80], size: [130, 56], fill: \"green\",  text: \"Done\" },\n  { shape: \"arrow\", from: \"start\",   to: \"process\" },\n  { shape: \"arrow\", from: \"process\", to: \"done\" },\n];\n\nconst { outputs } = await render(elements, { formats: [\"excalidraw\", \"svg\", \"png\"] });\nwriteFileSync(\"diagram.excalidraw\", outputs.excalidraw);\nwriteFileSync(\"diagram.svg\", outputs.svg);\nwriteFileSync(\"diagram.png\", outputs.png);\n```\n\nThe full sugar schema (shapes, arrows, layout helpers, `fill` / `stroke` /\n`textColor`) is documented in\n[`skills/shared/references/sugar.md`](skills/shared/references/sugar.md).\n\n## API Reference\n\n### Core\n\n| Function | Returns | Description |\n|----------|---------|-------------|\n| `render(elements, opts?)` | `Promise<{ outputs, elementCount }>` | Desugar + render to `{ excalidraw, svg, png }`. `opts.formats` subsets the output; `opts.scale` (1–4) sets PNG scale. |\n| `desugar(elements)` | `element[]` | Expand sugar shorthand into raw Excalidraw elements without rendering. |\n\n### Layout helpers\n\n| Function | Description |\n|----------|-------------|\n| `gridLayout`, `chain`, `swimlane`, `hubSpoke` | Position helpers — coordinates for grids, chains, swimlanes, hub-and-spoke. |\n| `edgePoint`, `routeU`, `labelAnchor` | Edge anchors, U-route detours, and label anchors for arrows. |\n| `titledBox`, `fitContainer` | Auto-sized geometry — a header+body card, and a container fitted to its children. |\n| `equalize` | One height that fits a group of cells, so a wrapped label can't leave a row of sibling boxes ragged. |\n| `contrastText`, `readableOn` | Pick a legible label color for a given fill (3:1 WCAG floor). |\n\nThese back the `compute_layout` MCP tool — see\n[`skills/shared/references/sugar.md`](skills/shared/references/sugar.md) for usage.\n\n### Output\n\n| Function | Returns | Description |\n|----------|---------|-------------|\n| `excalidraw(elements)` | `string` | JSON for a `.excalidraw` file |\n| `toSvg(elements)` | `string` | SVG markup with embedded fonts |\n| `toPng(elements, scale?)` | `Promise<Buffer>` | PNG buffer (resvg-js native rendering) |\n\n`excalidraw` / `toSvg` / `toPng` take already-desugared elements; call\n`desugar()` first if you're starting from sugar.\n\n### Colors\n\n```javascript\nimport { colors } from \"excalidrawer\";\n\ncolors.blue / colors.green / colors.yellow / colors.purple / colors.red / colors.orange / colors.gray\ncolors.bgBlue / colors.bgGreen / colors.bgYellow / colors.bgPurple  // section backgrounds\ncolors.strokeBlue / colors.strokeGreen / colors.strokeYellow / colors.strokeOrange  // stroke accents\n```\n\nIn sugar, set `fill` for the background, `stroke` for the border, and\n`textColor` (palette key or `#rrggbb`) for a bound label.\n\n## Roadmap\n\nDirections being explored, each tracked in its own design note under\n[`docs/`](docs/) (see [`docs/roadmap.md`](docs/roadmap.md) for the versioned\nengineering roadmap):\n\n- New diagram types (state machine, tree, pyramid/funnel, bar/line charts,\n  high-level data-stack) + a public example gallery —\n  [`docs/diagram-types.md`](docs/diagram-types.md)\n- WebP output + scenario-aware format selection —\n  [`docs/output-formats.md`](docs/output-formats.md)\n- Mermaid import — [`docs/mermaid-import.md`](docs/mermaid-import.md)\n- draw.io import — [`docs/drawio-import.md`](docs/drawio-import.md)\n- A shared component layer for composite layouts —\n  [`docs/component-layer.md`](docs/component-layer.md)\n- Hand-drawn-style icon primitives —\n  [`docs/icon-library.md`](docs/icon-library.md)\n- Agent-runtime ecosystem integration (Pi, DeepSeek, Hermes) —\n  [`docs/ecosystem-integration.md`](docs/ecosystem-integration.md)\n\n## License\n\nMIT\n",
  "bytes": 10970,
  "sha": "e6336343a32c87fb41018f80376d6abcc32cc12a3e69b09bc3371b86728f3d01",
  "repo_slug": "guohaonan-shy/excalidrawer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_guohaonan_shy_excalidrawer_excalidrawer_9a18c077/readme"
}