Getting started

Install Chromium

excalix needs Node 22 or newer. Export and text measurement run in headless Chromium, which Playwright downloads separately. Do this once per machine:

npx -y playwright@1.63.0 install chromium

Skip it and the first render stops with a message that names the fix:

error: Chromium is not installed. Run: npx -y playwright@1.63.0 install chromium

Render a spec

A spec is a JSON file listing nodes, the edges between them, and optionally the groups they sit in. This one is two boxes and an arrow:

{
  "title": "order pipeline",
  "groups": [{ "id": "aws", "label": "AWS eu-north-1" }],
  "nodes": [
    { "id": "web", "label": "Web app", "kind": "client" },
    { "id": "api", "label": "Order API", "kind": "service", "group": "aws" }
  ],
  "edges": [{ "from": "web", "to": "api", "label": "POST /orders" }]
}

Three commands cover the command line:

npx -y excalix render spec.json -o out/spec
npx -y excalix validate spec.json
npx -y excalix schema

render writes out/spec.excalidraw, out/spec.svg and out/spec.png and prints their paths. Without -o the basename is the spec path minus its extension. End -o with a slash and it names a directory instead, so -o docs/diagrams/ writes spec.excalidraw and its siblings in there.

validate checks the spec without opening a browser. It prints the counts, here ok: 2 nodes, 1 edge, 1 group, or every problem at once and a non-zero exit. schema prints the JSON Schema of the spec, useful for editor completion or for handing to a model. The spec reference explains each field.

Commit the spec beside its outputs, so the next person regenerates the diagram instead of redrawing it.

Connect an agent

excalix mcp serves one tool, sketch, over stdio. It takes the same spec, writes the three files and returns the PNG in the same result, so the agent can look at what it drew. Register it once.

Claude Code

claude mcp add excalix --scope user -- npx -y excalix mcp

--scope user makes it available in every project. Files the tool writes land relative to the server's working directory, which is the project directory when Claude Code launches the server.

Other MCP clients

Cursor, VS Code, Claude Desktop and others accept this shape in their MCP configuration file:

{
  "mcpServers": {
    "excalix": {
      "command": "npx",
      "args": ["-y", "excalix", "mcp"]
    }
  }
}

Where that file lives differs by client; check its documentation for the path. The MCP server page describes what sketch accepts and returns.

The skill

A Claude Code skill tells the agent when to reach for excalix and how to write a spec that lays out well: reading order, short edge labels, when to split a diagram in two. Install it next to your other skills:

mkdir -p ~/.claude/skills/excalix
curl -fsSL https://raw.githubusercontent.com/yasinmiran/excalix/main/skills/excalix/SKILL.md -o ~/.claude/skills/excalix/SKILL.md

It is plain Markdown, readable on GitHub before you install it. Its description is written to match asks like "draw the architecture", "sketch a diagram" or "put this system into excalidraw".