drawio-ai-kit

An orchestration and validation framework enabling AI agents to generate structurally precise and aesthetically standardized draw.io diagrams, optimized for AWS, Azure & GCP architectures.

It mitigates common AI agent hallucinations (such as generating non-existent stencil IDs that result in empty shapes) using three key components:

1. Declarative Catalog — A single source of truth mapping draw.io stencil IDs (mxgraph.aws4.*) to their respective taxonomies and canonical color palettes.
2. Design Principles — Codified architectural and layout rules (skills/drawio/references/principles.md).
3. Structural Validator — A static analysis engine that audits diagram XML to guarantee stencil references are valid and design principles are satisfied prior to serialization.

Exposed to the AI via the self-contained drawio-ai CLI (one bundled file, nothing extra to install).

Showcase

One diagram per platform — all generated end-to-end by the kit: no hand-placed coordinates, real stencils, validated, vision-checked. Full set in examples/.

Quick start

Requirements: Node.js ≥20.6 or Bun 1.4+. Nothing else to install.

Bun-only machine (no node)? The CLI's shebang is #!/usr/bin/env node (the Windows-safe standard), so install.sh writes ~/.local/bin/drawio-ai as a wrapper that runs bun <pkg>/dist/cli.mjs. Re-run install.sh after bun update -g. With a manual bun add -g, run bun $(bun pm bin -g)/../install/global/node_modules/drawio-ai-kit/dist/cli.mjs or install Node.

1. One-liner (CLI + skill)

curl -fsSL https://raw.githubusercontent.com/sparklabx/drawio-ai-kit/refs/heads/main/install.sh | sh

It installs drawio-ai-kit@latest globally with Bun (if present) or npm, links the drawio-ai command into ~/.local/bin (pick another dir with BIN_DIR=/dir or --bin-dir /dir; pin a version with --version 2.0.1), then registers the drawio skill with every agent it finds. It never installs a runtime and needs no sudo. Prefer to read it first? Download install.sh, open it, then run sh install.sh (--dry-run prints the commands only; --help lists options).

Re-run it to upgrade. It first removes old installs so exactly one copy remains:

• any global copy from npm or Bun, including old git installs
• the old skills (drawio-aws, drawio-cloud-architect, …) and their leftover folders
• the pre-1.0 MCP entry

Pass --no-clean to keep them.

2. Manual (npm or Bun)

npm i -g drawio-ai-kit && drawio-ai skill install      # npm
bun add -g drawio-ai-kit && drawio-ai skill install    # Bun

About 2 MB from the npm registry, so it takes seconds. drawio-ai skill install registers the skill straight from the installed package, with no second download. Restart your agent, then try: "draw an AWS 3-tier web app".

3. As a project dependency (scripts and types)

npm i drawio-ai-kit        # or: bun add drawio-ai-kit

import { Diagram, group, icon, renderTree } from "drawio-ai-kit";   // full TypeScript types included

Run such a script with plain node build.mjs or bun build.mjs. Without a local install, use the global CLI: drawio-ai run build.mjs (it resolves "drawio-ai-kit" to the installed CLI).

The global install puts the drawio-ai binary on PATH (see INSTALL.md to pin a version). Install only from the npm registry; installing from git or GitHub is not supported. The CLI ships as a Bun-minified production bundle (dist/) that runs on Node or Bun. Its one library (icon search) is bundled inside, so users install nothing extra. The skill step uses the skills CLI, which auto-detects Claude Code, Codex, Gemini CLI, … — without it the agent never picks the kit up on its own.

One skill covers every domain: it asks you what's missing (which cloud? what to draw?), then loads just that domain's reference. It is written in short, explicit steps so small fast models (e.g. Claude Haiku) can drive it end-to-end.

• Optional, for the full experience: the draw.io desktop app enables drawio-ai render (the vision self-check); Graphviz enables vendor/autolayout.py for large graphs. Details in INSTALL.md.

Is it safe to install?

Short answer: yes — and you don't have to take my word for it.

• No hidden code. No postinstall (or any lifecycle) hooks — nothing runs on npm install. No dependencies are installed alongside it. No sudo, no runtime installs, no remote code at run time. The optional one-line installer is a short POSIX script you can read first. The shipped dist/ is minified, but it is a reproducible build of the readable src/: it is never committed; CI builds it on every PR (and checks the build is deterministic), and the release job builds the published copy from the tagged source.
• Self-contained. The package has no runtime dependencies. The one library it uses (minisearch, for icon search) is a devDependency that Bun bundles into dist/, and npm audit --omit=dev runs in CI.
• Runs locally, no telemetry. The CLI only reads/writes local files. The single optional outbound call is icon-logo fetching from public CDNs (lobe-icons), and it's opt-in.
• Easy to undo:

npm uninstall -g drawio-ai-kit              # remove the CLI (Bun: bun remove -g drawio-ai-kit)
npx skills remove drawio                  # remove the skill (Bun: bunx skills remove drawio)

• Updating — two independent channels:

npm i -g drawio-ai-kit@latest && drawio-ai skill install   # CLI + skill (Bun: bun add -g drawio-ai-kit@latest)

The skill drives drawio-ai at runtime, so engine fixes reach you the moment you update the CLI. Re-running drawio-ai skill install refreshes the skill's docs from the same version. Pin a release with drawio-ai-kit@2.0.0.

To report a security issue, see SECURITY.md.

Build a diagram — declarative, no hardcoded coordinates

Define a diagram topology (pipeline/hierarchy/network/hubspoke/hybrid/mesh/sequence), declare the nested structure, and the layout engine programmatically computes spatial coordinates (x/y/w/h) — frames auto-size to fit their children, while rows and columns auto-space. You define the logical topology, not raw pixels.

import { Diagram, group, icon, box, renderTree } from "drawio-ai-kit";   // run: drawio-ai run build.mjs (or plain node/bun where drawio-ai-kit is installed)

const d = new Diagram("network");
const tree = group("region", "group_region", "Region", { dir: "row" }, [
  group("vpc", "group_vpc", "VPC", { dir: "col" }, [
    icon("alb", "elastic_load_balancing", "ALB"),
    icon("ec2", "ec2", "EC2"),
  ]),
]);
renderTree(d, tree);                 // engine lays everything out + sizes the page
d.title("My VPC");
d.link("alb", "ec2");                // edges by id; router picks straight/corridor
const res = d.validate();            // names real? colors/nesting/labels clean?
// d.mxfile("My VPC")  → write to .drawio, export PNG, then vision self-check

Icon names are retrieved from drawio-ai search to prevent name fabrication (it tolerates typos, aliases like k8s/pg/es, and multi-keyword queries); edge routing, container sizing, alignment, and contextual corner styles are dynamically computed. The AI agent defines the logical layout and iterates via a render-analyze-rectify loop (vision-based self-correction). Example: examples/aws/build_mesh.mjs (zero manual coordinates).

Migration (from 1.x)

At 2.0.0 the 5 domain skills (drawio-aws, drawio-azure, drawio-gcp, drawio-databricks, drawio-bpmn) were merged into ONE drawio skill, and the CLI became a Bun-minified bundle in dist/.

• Easiest: re-run install.sh. It removes the old skills and the old CLI, then installs fresh.
• Skills (manual): npx skills remove drawio-aws drawio-azure drawio-gcp drawio-databricks drawio-bpmn, then drawio-ai skill install.
• CLI (manual): npm i -g drawio-ai-kit (from the npm registry; the bin points at dist/cli.mjs).
• Your build scripts: import everything from "drawio-ai-kit" (the package no longer ships src/). Re-scaffold, or replace the <ROOT>/src/builder.ts / layout-engine.ts / bpmn.ts imports with that one name. Run with drawio-ai run build.mjs.
• drawio-ai principles --mode … and drawio-ai workflow still work; they now print the skill's references/ and workflows/build.md.

Migration (from <1.0)

At 1.0.0 the MCP server and bespoke installer were removed. To migrate:

• Install: run install.sh. It removes the drawio-ai-kit MCP entry and the old drawio-cloud-architect / drawio-aws-architect skill folders, then installs the CLI from npm and the drawio skill.
• Manual: claude mcp remove drawio-ai-kit --scope user, delete the old skill folders (e.g. ~/.agents/skills/drawio-cloud-architect), then npm i -g drawio-ai-kit && drawio-ai skill install.
• Vision self-check: the inline image was replaced by drawio-ai render → PNG → Read.
• Uninstall: npm uninstall -g drawio-ai-kit + remove each skill via the skills tooling.

Template library (examples/)

Each file builds one common architecture via the layout engine (zero hardcoded coordinates) — copy one as a starting point. Examples are organized into domain subfolders — see examples/README.md for the full index. Copy one out of the kit and run it: drawio-ai scaffold <file> -o <dir>/build.mjs --name <name>.drawio && drawio-ai run <dir>/build.mjs (the .drawio lands next to the script; never run examples inside the kit folder).

examples/aws/