Comparison
Chiltepin vs PlantUML: UML depth or agent flow
PlantUML is the deepest text-to-diagram tool there is. It covers every UML diagram type plus deployment, timing, network, Gantt, Salt wireframes and C4 through C4-PlantUML, with a preprocessor, includes and macros that let large teams share one vocabulary. It has run for twenty years on a JVM and GraphViz, and every IDE, wiki and CI system has a plugin or a server for it. Chiltepin covers fewer diagram kinds and models less of each. What it adds is a schema on every block, a validator that fails CI, block types for the non-diagram parts of a document, and a skill that lets an agent write all of it with something to check against.
Side by side
| PlantUML | Chiltepin | |
|---|---|---|
| Source format | The PlantUML language in .puml files or fences, with a preprocessor, !include and macros | Markdown with typed YAML blocks, one grammar for every block type |
| Who draws the layout | GraphViz dot for most diagrams, with hints like left of, -down-> and hidden edges to steer it | The renderer, from the data; no hints and no coordinates in the source |
| Where it renders | A JVM with GraphViz, locally or on a PlantUML server; editor plugins call one of the two | The CLI (Node) or the browser Studio; output is static SVG and HTML |
| Validation in CI | The parser rejects bad syntax; there is no schema beyond that | chiltepin check validates fields, references and ids against a strict schema and exits non-zero |
| Beyond diagrams | Diagrams only, including Salt wireframes, JSON and YAML views, and Gantt | Tables, API endpoints, ADRs, threat models, charts and decks in the same files and validator |
| AI agent workflow | The model writes PlantUML from memory; it usually can, but nothing checks the result | A skill the agent installs; it writes YAML, runs the validator and repairs diagnostics before handoff |
| Output formats | PNG, SVG, EPS, PDF, LaTeX, ASCII art per diagram | Static site, standalone HTML, slides, PDF per document |
| Ecosystem / tooling | Twenty-plus years: C4-PlantUML, stdlib icon sets, plugins for every IDE and wiki, Kroki | Newer and smaller: CLI, Studio, one agent skill; no PlantUML importer |
| Licence | GPL by default, with MIT, LGPL, Apache and other licence builds available | MIT |
| Best for | Full UML, deployment and timing diagrams, and teams already invested in it | Documents an agent writes and CI checks, with diagrams as one block among several |
The same diagram, both ways
A login flow: the browser posts to the auth service, which sends the user through Google and comes back with a session cookie. In PlantUML:
@startuml
participant Browser
participant "Auth service" as Auth
participant Google
Browser -> Auth: POST /login
Auth -> Google: Redirect to consent
Google --> Auth: Authorization code
Auth -> Google: Exchange code for ID token
Auth --> Browser: Session cookie
@endumlFive messages, three participants, rendered by a JVM or a PlantUML server. There is no importer for this text; an agent with the skill rewrites it as a sequence block in a few lines of YAML. The Chiltepin form of a sequence block renders in the example section below.
When to pick PlantUML
Pick PlantUML when you need real UML: class diagrams with visibility and generics, activity diagrams with swimlanes and forks, deployment and timing diagrams, or a C4-PlantUML model with sprites and shared includes. Pick it too if your team already has a library of .puml files and a server that renders them; the setup is paid for and the language is not going anywhere. PlantUML is the more complete diagramming tool, and nothing on this page argues otherwise.
When to pick Chiltepin
Pick Chiltepin when the document is the unit of work, not the diagram: an architecture note with a C4 view, an endpoint table, a decision record and a threat register, all in one Markdown file that chiltepin check validates on every pull request andchiltepin build turns into a site, a deck and a PDF. It fits best when an agent is the author. In our own generation eval (40 scenarios, September 2026) an agent with the skill delivered 40 of 40 documents clean at handoff with no render failures; the harness is in the repository. No JVM, no GraphViz, nothing to install to try it.
What a Chiltepin block looks like
This is the sequence starter template: two actors, a request, and an alt frame with two outcomes, the same fragment PlantUML writes as alt / else / end. There are no layout hints because the schema has no field for them.
```sequence
id: seq-example
actors:
- { id: Client, name: Client }
- { id: Server, name: Server }
messages:
- Client -> +Server: request
- alt: cache hit
- Server --> -Client: 200 cached
- else: miss
- Server --> -Client: 200 fresh
- end
```Every block on this site is rendered this way, at build time, by the same pipeline chiltepin build runs. See the block catalog or the documents an agent wrote. Other comparisons: vs Mermaid, vs D2, vs Eraser, vs Structurizr, vs Archify.
Frequently asked questions
- Is Chiltepin a PlantUML alternative?
- For sequence, component, state, ER and C4 diagrams inside documentation, yes. For the full UML set it is not: PlantUML has class, object, activity, deployment, timing and use case diagrams with details Chiltepin does not model, plus Salt wireframes and JSON views. Chiltepin trades that depth for a schema on every block, a validator in CI, and block types for the rest of the document.
- Can I migrate from PlantUML?
- There is no PlantUML importer, and we do not plan to parse the language; the preprocessor and includes make it a moving target. The practical path is to hand the diagram or its description to your agent and let the skill write the block, then run chiltepin check. For a large PlantUML corpus, keep it; Chiltepin can hold the new documents while the old diagrams stay where they are.
- Does Chiltepin need Java or GraphViz?
- No. The CLI runs on Node with npx and needs no other runtime; the Studio runs in the browser with nothing uploaded. PlantUML needs a JVM and, for most diagram types, GraphViz, or a PlantUML server that has both. That is the setup cost teams usually cite, and it is also why PlantUML has so many server and plugin integrations.
- Does Chiltepin support C4?
- Yes. A c4 block describes people, systems, containers and components and their relationships, and the renderer draws the diagram; there is no coordinate or layout hint in the source. C4-PlantUML is more mature and more customisable, with sprites, tags and a larger set of layout macros. If you need that control, C4-PlantUML is the better tool.
- How reliably does an AI agent write Chiltepin blocks?
- In our own generation eval (40 scenarios, September 2026) an agent with the skill picked the right block 39.5 times out of 40, 33 of 40 documents were clean on the first write, all 40 were clean at handoff and none failed to render, at about 55K tokens and 91 seconds per document. The harness is in the product repository under evals. We have not measured PlantUML the same way; models do write it well from memory, but there is no schema to score the output against.