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 /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).