bpmn — Claude Code plugin for BPMN 2.0

A Claude Code plugin that lets Claude work with BPMN 2.0 process diagrams (.bpmn XML): read and explain them in plain language, and create or edit them so they come out valid and visually clean in any modeler (Camunda Modeler, bpmn.io, Cawemo…).

The model does the semantic reasoning (what the process means, what to change); a small bundled Node script does the deterministic mechanics — parsing, regenerating layout, validating, and linting control flow.

What it can do

• Explain a .bpmn: happy path, decision points, exception/timeout handling.
• Create / edit processes from a description (you never hand-write diagram coordinates), with full layout coverage: collaborations (all pools + message flows), swimlanes, sub-process drill-down pages, and data objects/annotations.
• Edit non-destructively: layout is safe by default — on a file that already has a diagram it preserves the layout (hand-tuned positions, Camunda multi-diagram sub-process pages) and only prunes shapes for deleted elements and places shapes for new ones. A full re-layout happens only with --rebuild.
• Validate: well-formed XML, every node/edge has a shape, no overlaps (checked per diagram plane).
• Lint control flow: catches bugs that are valid XML but wrong behaviour — deadlock (parallel join after an exclusive split), double execution (exclusive join after a parallel split), stuck-token gateways (all branches conditioned, no default), unreachable nodes, dead ends, and a missing start/end event.
• Compare & search: diff two versions (As-Is vs To-Be or edit review) and find elements by name or type.

Requirements

• Claude Code
• Node.js >= 18 and npm — on first use the skill runs npm install in its own folder to fetch bpmn-moddle and bpmn-auto-layout (deps are not committed).

Install

This repository is both the plugin and a one-plugin marketplace:

/plugin marketplace add architawr/claude-bpmn-skill
/plugin install bpmn@bpmn-tools
/reload-plugins

The skill is model-invoked: once installed, Claude uses it automatically when you work with .bpmn files or ask to model/review a process. It is namespaced as bpmn (the plugin name).

Or, for local development without installing:

claude --plugin-dir ./claude-bpmn-skill

Commands

The skill is model-invoked automatically, but the plugin also adds explicit slash commands (namespaced /bpmn:):

Usage

The skill is invoked automatically, but the bundled tool can also be run directly:

node skills/bpmn/scripts/bpmn-tool.mjs summarize  [--json]
node skills/bpmn/scripts/bpmn-tool.mjs layout     [out.bpmn] [--rebuild]
node skills/bpmn/scripts/bpmn-tool.mjs validate  
node skills/bpmn/scripts/bpmn-tool.mjs lint      
node skills/bpmn/scripts/bpmn-tool.mjs diff       
node skills/bpmn/scripts/bpmn-tool.mjs find       

Full workflow, modeling conventions and limits are in skills/bpmn/SKILL.md; element-level XML recipes in skills/bpmn/references/bpmn-reference.md.

Known limits (auto-layout)

Layout covers single-pool flows, collaborations (all pools + message flows), swimlanes, sub-process drill-down pages, and data objects / annotations / associations. It does not auto-place groups (a group is a purely visual rectangle with no membership in the model). Auto-placement of pools, lanes, data objects, and annotations is approximate — valid and clean, but a user may want to nudge spacing in a modeler. See the reference for details.

License

MIT © 2026 Artur Karapetyan