Cora

Open-source diagram tool for AI coding agents and the humans who review their output. Agents author architectural diagrams as YAML; the CLI validates and renders professional SVG, PNG, PDF, or text artifacts.

AI agents: read AGENTS.md first — validate loop, JSON error shape, schema contract, and error codes.

Status

Phase	State	Delivered
1 — Foundation	Complete	`cora validate`, `cora schema`, v1 JSON Schema, structured errors
2 — Renderer + SVG	Complete	`cora render` → `.svg` / `.png`, ELK layout, pure SVG renderer, default theme
3 — PDF Export	Complete	`cora render -o diagram.pdf`
3.3 — Component Preview Canvas	Complete	`cora preview` interactive editor and component workbench
3.4 — Text Export + SKILL.md	Complete	`cora render` stdout text, `.txt`, `--charset ascii`, agent skill guide
3.5 — Preview Visual Beauty	Complete	Polished preview workbench UI and interaction pass
3.6 — Default Component Look Lockdown	Complete	Shared renderer/preview component defaults and look tokens
3.7 — Package Surface Lockdown	Complete	Built-in default icons, shipped preview command, public API exports, clean package
3.8 — Grid Capability	Complete	Optional `diagram.grid`, snap helpers in `cora/core`, preview snap
4 — Interactive Canvas	Complete	`cora preview` ships in npm; file-mode AST save, file watch, bundled `dist/web/`
5+	Planned	Extensions (`cora ext`), `cora doctor`

Today: validate any diagram, export schema, render all five v1 diagram kinds to SVG, PNG, PDF, or simplified graph-like text. Edit diagrams interactively in the browser with cora preview. Built-in component defaults are shared by the renderer and preview controls. Icon nodes support bundled offline Iconify Material Symbols and built-in default icons.

Install

Requirements: Node.js 22+ or Bun 1.x (recommended for development).

From source:

git clone https://github.com/isa/cora.git
cd cora
bun install
bun run build

When published:

npm install -g cora

Link the CLI locally after building:

cd packages/cora && bun link
cora --version

Test the npm tarball (what users get from npm install):

cd packages/cora
bun run build
mkdir -p /tmp/cora-pack
npm pack --pack-destination /tmp/cora-pack

mkdir -p /tmp/cora-install-test && cd /tmp/cora-install-test
npm init -y
npm install /tmp/cora-pack/cora-0.0.0.tgz
npx cora --version
npx cora preview diagram.yaml --no-open   # use an absolute path to your YAML

Automated smoke:

bash packages/cora/tests/legacy/smoke/clean-install.sh

From the repo without linking:

bun run cora -- <command> ...

Quick start

# Validate (human-readable in a TTY)
bun run cora validate diagram.yaml

# Validate for CI / agents (JSON array on stdout)
bun run cora validate diagram.yaml --format json

# Render SVG
bun run cora render diagram.yaml -o /tmp/diagram.svg

# Render PNG (default 2× scale)
bun run cora render diagram.yaml -o /tmp/diagram.png

# Render text to stdout or a .txt file
bun run cora render diagram.yaml
bun run cora render diagram.yaml -o /tmp/diagram.txt

# Export JSON Schema
bun run cora schema --out cora-schema.json

# Open the interactive diagram editor
bun run cora preview diagram.yaml --no-open

# Open the workspace workbench
bun run cora preview --no-open

Commands

Global

Flag / env	Purpose
`--version`	Print package version
`--yes`	Non-interactive mode for future install prompts
`CORA_AUTO_INSTALL=1`	Same as `--yes` (read at startup)

`cora validate [file]`

Validate a diagram YAML or JSON file against the v1 JSON Schema and semantic rules (edge targets, extensions, etc.).

Option	Default	Description
`--format text\|json`	`text`	Output format for errors

Exit codes: 0 when valid; 1 when invalid or parse error.

Success output:

TTY + --format text → no output (silent success)
--format json or non-TTY stdout → [] plus newline

# Human-readable errors (colored in a TTY)
cora validate diagram.yaml

# Machine-readable errors for agents and CI
cora validate diagram.yaml --format json

# Piped stdout is treated as JSON even without --format json
cora validate diagram.yaml | jq .

`cora render [file]`

Parse, validate, layout, and render to SVG, PNG, PDF, or simplified graph-like terminal text. Output format is determined by the -o extension (.svg, .png, .pdf, or .txt). Omit -o to print text output to stdout.

Option	Default	Description
`-o, --output <path>`	—	Output file (`.svg`, `.png`, `.pdf`, or `.txt`); omit for stdout text
`--format text\|json`	`text`	Error output format on validation/layout/parse failure
`--charset unicode\|ascii`	`unicode`	Text output charset for `.txt` or stdout text
`--size sm\|md\|lg\|xl\|xxl`	`md`	PNG raster scale (ignored for SVG)
`--without-shadow`	off	Flat nodes without drop shadows
`--monochrome`	off	Black, grey, and white only
`--page a4\|letter\|a4-portrait\|letter-portrait`	fit-to-content	PDF page size
`--quality high`	bundled PDF lane	Use Playwright/Chromium for high-quality PDF output
`--ascii-engine layout\|svg`	`layout`	Text rendering engine

PNG scale factors:

`--size`	Scale
`sm`	1×
`md`	2× (default)
`lg`	3×
`xl`	4×
`xxl`	6×

# SVG (vector, locked default component look)
cora render diagram.yaml -o out.svg

# PNG at default resolution (2×)
cora render diagram.yaml -o out.png

# High-resolution PNG for slides or print
cora render diagram.yaml -o out.png --size xxl

# Simplified terminal output for Markdown, pull requests, and agent logs
cora render diagram.yaml
cora render diagram.yaml -o diagram.txt
cora render diagram.yaml --charset ascii

# PDF, browser-free by default
cora render diagram.yaml -o out.pdf
cora render diagram.yaml -o out.pdf --page a4

# Optional Playwright/Chromium PDF lane
cora render diagram.yaml -o out.pdf --quality high --yes

# Print-friendly / documentation variants
cora render diagram.yaml -o out.svg --monochrome
cora render diagram.yaml -o out.svg --without-shadow
cora render diagram.yaml -o out.svg --monochrome --without-shadow

# JSON errors when render fails validation (same shape as validate)
cora render diagram.yaml -o out.svg --format json

# JSON diagram input works too
cora render diagram.json -o out.svg

Parent directories for -o are created automatically.

`cora schema`

Print the v1 diagram JSON Schema (https://cora.dev/schema/v1/diagram.json).

Option	Description
`--out <path>`	Write schema to a file instead of stdout

cora schema
cora schema --out cora-schema.json

`cora preview [file]`

Open Cora's interactive browser editor. The command ships in the npm package with pre-built assets under dist/web/.

Pass a diagram file to edit that file with file watch, WebSocket reload, and comment-preserving YAML AST patch save. Omit the file to open the workspace workbench and component catalog.

Option	Default	Description
`[file]`	—	Diagram YAML/JSON file to edit
`--host <host>`	`127.0.0.1`	Host interface for the local server
`--port <port>`	`4173` workspace / `0` file	Preferred local port (`0` or `auto` picks a free port in file mode)
`--workspace <path>`	nearest `examples/` ancestor	Workspace root for diagram read/write
`--diagram <path>`	—	Diagram to open on startup, relative to `--workspace`
`--no-open`	off	Do not open the default browser

cora preview architecture.yaml
cora preview architecture.yaml --no-open
cora preview architecture.yaml --port 4173
cora preview
cora preview --workspace . --diagram examples/valid/minimal.yaml --no-open

When running from the source repository, workspace mode uses the Vite dev server for HMR. Installed npm builds use Express with the same bundled SPA.

Diagram format

Every file must have version: 1 at the root and a single diagram object (one diagram per file).

version: 1

diagram:
  kind: box-arrows          # required
  direction: LR             # LR or TB (optional)
  layout: auto              # auto | preserve | hybrid (default: auto)
  theme: default            # built-in theme (default)
  nodes:
    - id: client
      label: Client
      component: document   # optional; omit for the default box component
      position: { x: 100, y: 50 }   # required for layout: preserve on all nodes
      pinned: true          # keep position during auto/hybrid relayout
  edges:
    - from: client
      to: server
      label: request        # optional; rendered with gap in edge stroke
  groups:                   # optional; microservice/infra use contains: [...]
    - id: region
      label: Region
      contains: [client, server]

Diagram kinds

Kind	Typical use
`box-arrows`	Simple architecture / component diagrams
`flowchart`	Process flows
`microservice`	Service topology with domain groups
`infra`	Cloud / boundary diagrams
`database`	App ↔ datastore

Run cora schema for the authoritative field list — do not add properties outside the schema.

Layout modes

Mode	Behavior
`auto` (default)	ELK computes positions; YAML `position` ignored unless `pinned: true`
`preserve`	Use YAML `position` on every node; errors if any node lacks coordinates
`hybrid`	ELK lays out unpinned nodes; nodes with `pinned: true` and `position` stay fixed

Icons

Nodes may set icon to:

A built-in default icon under provider: default (with service: server, database, cloud, network, user, or using simple aliases directly like server, database, cloud, network, user). Status icons also include bug, warning, error, stop.
An offline Iconify id such as material-symbols:database or basil:cloud-upload-outline. Cora currently ships offline material-symbols and basil icon sets, so diagrams render deterministically without API calls:

- id: archive
  label: Archive
  component: icon
  icon: database

The older provider: default + service: database form remains supported and resolves to the built-in default database icon. Unknown icon sets fail with MISSING_EXTENSION; unknown icon names fail with UNKNOWN_SERVICE.

Validation errors

cora validate --format json and cora render --format json (on failure) print a JSON array on stdout:

[
  {
    "code": "SCHEMA_VIOLATION",
    "path": "/diagram/nodes/0/id",
    "message": "must match pattern ...",
    "suggestion": "Add version: 1 at the document root"
  }
]

Code	Meaning
`SCHEMA_VIOLATION`	Document fails JSON Schema validation
`MISSING_EDGE_TARGET`	Edge `from` or `to` references a missing node id
`UNKNOWN_SERVICE`	`service` without `provider`, malformed icon id, or unknown icon/service name
`MISSING_EXTENSION`	Requested icon provider/set is not installed
`PARSE_ERROR`	YAML/JSON syntax error
`LAYOUT_ERROR`	Layout failed (e.g. `layout: preserve` without positions on all nodes)
`CHROMIUM_NOT_INSTALLED`	`--quality=high` requested without installed Chromium or install consent
`CHROMIUM_INSTALL_FAILED`	Chromium install failed after consent
`HIGH_QUALITY_RENDER_FAILED`	Playwright high-quality PDF rendering failed
`RESVG_FONT_WARNING`	Default PDF lane found a non-bundled font in CI mode

TTY behavior: interactive terminal + default --format text → colored human-readable lines. --format json or non-TTY stdout → JSON only, no extra prose.

CI

bun run build

# Fail the job on invalid diagrams
cora validate path/to/diagram.yaml --format json | jq -e 'length == 0'

# Produce artifacts
cora render path/to/diagram.yaml -o dist/diagram.svg
cora render path/to/diagram.yaml -o dist/diagram.png --size lg
cora render path/to/diagram.yaml -o dist/diagram.pdf

Use --format json (or pipe stdout) so parsers never depend on terminal colors or wording.

High-quality PDF rendering downloads Chromium lazily only after explicit consent. In CI, pass --yes or set CORA_AUTO_INSTALL=1; otherwise --quality=high fails with a structured CHROMIUM_NOT_INSTALLED error instead of silently falling back.

Architecture

Single published cora npm package with internal modules:

YAML/JSON
  → core       parse, validate (AJV), ELK layout, theme resolution
  → renderer   React → pure SVG (no foreignObject); SVG, PNG, PDF, text
  → preview    interactive browser editor (Express + bundled SPA; Vite HMR in source checkout)
  → cli        validate, render, schema, preview

Stack: Node.js 22+, Bun, TypeScript 5, Turborepo, ELK 0.11, React 19, Vite (dev/build), @resvg/resvg-js, pdf-lib, Playwright for optional high-quality PDF, and bundled Noto Sans for consistent headless metrics and selectable PDF text.

Planned: cora ext, cora doctor, and custom extension themes.

Development

bun install
bun run build
bun run typecheck
(cd packages/cora && bun x vitest run)

# Legacy suites (archived — not run in CI)
(cd packages/cora && bun run test:legacy)
(cd packages/cora && bun run test:legacy:golden)
bash packages/cora/tests/legacy/smoke/clean-install.sh

Programmatic use (after build):

import { parseFile, validateDocument, computeLayout } from 'cora/core';
import { renderToSVG } from 'cora/renderer';

License

Apache 2.0 — see LICENSE.

Name		Name	Last commit message	Last commit date
.cursor/rules		.cursor/rules
.github/workflows		.github/workflows
.planning		.planning
examples/valid		examples/valid
graphify-out		graphify-out
packages/cora		packages/cora
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTEXT.md		CONTEXT.md
LICENSE		LICENSE
PROJECT.md		PROJECT.md
README.md		README.md
SKILL.md		SKILL.md
bun.lock		bun.lock
cleanup.js		cleanup.js
infra-orig.txt		infra-orig.txt
package.json		package.json
tsconfig.base.json		tsconfig.base.json
turbo.json		turbo.json
update-render.js		update-render.js

Navigation Menu

Repository files navigation

Cora

Status

Install

Quick start

Commands

Global

`cora validate [file]`

`cora render [file]`

`cora schema`

`cora preview [file]`

Diagram format

Diagram kinds

Layout modes

Icons

Validation errors

CI

Architecture

Development

License

Related

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Cora

Status

Install

Quick start

Commands

Global

cora validate [file]

cora render [file]

cora schema

cora preview [file]

Diagram format

Diagram kinds

Layout modes

Icons

Validation errors

CI

Architecture

Development

License

Related

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`cora validate [file]`

`cora render [file]`

`cora schema`

`cora preview [file]`