diagc
Diagrams as code, with a local studio. diagc turns diagram sources that live in your repository into things other people can open.
- Pages and pictures.
diagc publishwrites one self-contained HTML page per diagram, and a PNG. The page folds, zooms and switches views in the browser, with no server behind it. Host the pages on GitHub Pages, GitLab Pages or any static host, and put the PNG in a README. - Diffs in pull requests. A GitHub Action comments on a pull request that changes a diagram: the list of changes, and the before and after pictures.
- A local studio.
diagc studioopens a browser app against your repository. Draw a diagram there and the studio saves it as a file in the repository.diagc ejectturns a drawn diagram into TypeScript. - In the terminal.
diagc showprints a diagram as text, for a pipe or a coding agent.diagc tuibrowses the diagrams full-screen and redraws as you edit.
Diagrams are plain files in your repository, so they diff, review and refactor like the rest of it.
npm i -g @diagc/cli # or: npx @diagc/cli studio
Needs Node ≥ 22.
Quickstart
diagc init shop # a starter diagram in .diagrams/src/, the .gitignore lines, compiled
diagc studio # opens the editor, recompiling as you edit
npm i -D @diagc/core as well if you want types and completion on .diagram.ts files — the CLI compiles them either way.
Commands
| Command | What it does |
|---|---|
diagc init | Set a repository up: a starter diagram (--type c4 for a C4 one), the .gitignore lines, and with --agents a pointer to the guide for coding agents (AGENTS.md / CLAUDE.md, and a Claude Code skill). |
diagc compile | Compile .diagrams/src/**/*.diagram.{ts,json} into validated artifacts under .diagrams/.artifacts/. The default command. |
diagc lint | Report what compiles but is probably a mistake — typos, duplicates, unused or undrawn parts. --json for a script or an agent; exit 1 until clean. |
diagc watch | Compile, then again on every change. |
diagc publish | Write self-contained HTML pages to .diagrams/html/ and PNGs to .diagrams/static/. |
diagc show | Print a diagram as text: boxes, lines and labels in box-drawing characters, coloured on a terminal and plain in a pipe. --plane, --layers, --depth and --root choose the view, --ascii the characters. |
diagc studio | Serve the visual editor against the current directory (default http://127.0.0.1:5173). Diagrams drawn here are saved back as .diagram.json. |
diagc tui | Browse the diagrams full-screen in the terminal: fold and unfold, go into a group, switch planes and layers, search. Redraws as the sources change. |
diagc eject | Replace a drawn .diagram.json with a generated .diagram.ts, checked first to rebuild the same model. |
diagc diff | Draw what changed in the diagrams between two git refs, or a ref and the working tree: before and after pages and PNGs, and a summary. |
diagc guide | Print how to write a diagram: the DSL, then one topic per diagram type (diagc guide c4). Written for a coding agent as much as for a person. |
diagc --help lists every command and flag, and the CLI reference has the details.
PNG export drives headless Chrome. Without one, publish writes HTML and says so; npx playwright-core install chromium gets a browser it finds, or point CHROME_PATH at one.
Two ways to author, one model
Write a .diagram.ts with the builder DSL, or draw one in the studio and it writes a .diagram.json for you. Both compile to the same validated model, so a diagram is never trapped in the tool that made it. Positions live in a separate <name>.layout.json, which keeps meaning and coordinates in different diffs.
Commit .diagrams/src/. .diagrams/.artifacts/, .diagrams/html/ and .diagrams/diff/ are build output — diagc init gitignores them.
Documentation
Website and live examples: https://ferroman.github.io/diagc/
Full docs, tutorials, and the model reference: https://github.com/Ferroman/diagc
License
AGPL-3.0-only, with additional permissions under section 7: diagrams you author, and the pages and images built from them, are yours to license however you like. A commercial license is available. See the project README.