archgram

Aesthetic architecture diagrams, straight from the code. Animated flows,
light and dark.

archgram is an open-source CLI tool for software architecture diagrams.
Write a YAML or JSON spec, or let Claude Code, Codex, Cursor or Gemini CLI
draw one from your code. It writes one self-contained SVG that follows
light and dark mode and animates the path a request takes. The file drops
into a GitHub README or any docs page, and the animation plays wherever an
image shows.

You describe the system: its nodes, what connects them and the paths a
request takes. archgram lays it out, routes the lines around the boxes and
draws it, in light and dark, with the flows animated.

It also draws a sequence diagram: the order in which the parts call each
other for one request, and what comes back, told in phases and played one
phase at a time (docs/SPEC.md,
Sequence).

Install

npm install --save-dev archgram

The command is a native binary for macOS, Linux and Windows, on x64 and
arm64. npm installs the one for your machine from an optional dependency,
@archgram/cli-<os>-<cpu>; nothing runs or downloads at install time.

If npm was told to leave optional dependencies out (--omit=optional),
or the lockfile was written on another platform, the binary is missing:
delete node_modules and package-lock.json and run npm install again.
ARCHGRAM_BINARY points the command at another binary.

Use

Write a spec in JSON or YAML, for example
docs/diagrams/linkshort.archgram.yaml:

archgram: 1
title: linkshort
description: A visit goes through the API to Postgres.
nodes:
  - { id: browser, kind: browser, label: Visitor }
  - { id: api, kind: service, label: API, tech: fastapi }
  - { id: db, kind: database, label: links, tech: postgresql }
edges:
  - { from: browser, to: api }
  - { from: api, to: db }
flows:
  - { name: a visit, steps: [browser, api, db] }

Then draw it:

npx archgram build docs/diagrams/linkshort.archgram.yaml

It writes docs/diagrams/linkshort.svg beside the spec, light and dark in
one file.

Commands

archgram build <spec>

Draws the diagram. A spec named <name>.archgram.yaml (or .yml,
.json) draws <name>.svg beside it. It says the size it drew and the
direction, and warns, still drawing, when the drawing is wider than keeps
its text readable where it is shown: 1,300 px in a README on GitHub, or
the ratio of shownWidth when the spec says it is shown elsewhere. With
direction: auto in the spec, archgram keeps left to right while it
fits, and otherwise the narrower direction (docs/SPEC.md).

npx archgram build docs/diagrams/linkshort.archgram.yaml

archgram check <spec>

Checks a spec without drawing it, and lists every problem at its line and
column, with the nearest id or logo when one is misspelt. When a node or
an edge names what backs it (source), its code or the document that
states it, it also says which of that is gone: a part or a line whose
code or sentence was removed is reported, and archgram build warns of
the same and still draws.

npx archgram check docs/diagrams/linkshort.archgram.yaml

archgram spec

Prints the spec format this archgram reads: every field, node kind and
rule. --brief prints its short part, one complete spec and what each
other section covers; --section <name> prints one section, such as
theme-file.

npx archgram spec --brief

archgram theme check <archgram.theme.json>

Reads your design tokens as the theme and shows each colour role in light
and dark, or every problem, such as a pair that falls short of contrast.

npx archgram theme check archgram.theme.json

archgram --version, archgram --help

Print the version, or every command and option.

Draw with your coding agent

The archgram skill lets a coding agent draw a project's architecture from
its code, or the sequence of one request: it reads the code and the docs, writes the spec in
docs/diagrams/, checks and draws it with npx archgram, in archgram's
colours or, when you ask, your project's own, and lists each part it drew
with the file behind it. It is
written to the open Agent Skills format, so any
agent that reads skills can use it: Claude Code, Codex, Cursor, GitHub
Copilot, Gemini CLI and others. Install it with the
skills command, which puts it
where each of your agents looks:

npx skills add byabas/archgram

It asks which agents to install it for; add -g to install it for every
project rather than this one. Then ask your agent to draw the architecture,
or, in Claude Code, type /archgram.

In Claude Code, it is also a plugin in
Anthropic's directory: find archgram there
and add it to your claude.ai account. Claude Code loads it, as
archgram@synced, the next time it starts signed in with that account
(plugins synced from claude.ai).

Or take it from the release, into your agent's skills folder
(~/.agents/skills, or ~/.claude/skills for Claude Code):

mkdir -p ~/.agents/skills && curl -sL https://github.com/byAbas/archgram/releases/download/v0.10.1/archgram-skill-0.10.1.tar.gz | tar -xz -C ~/.agents/skills

The skill's archive carries a signed record of the build that made it:
gh attestation verify archgram-skill-X.Y.Z.tar.gz -R byAbas/archgram.
0.5.0 and earlier were built before the account was renamed, and their
records carry its earlier name.

FAQ

Does the animation play in a README or a docs page?

Yes. The flows are animated with SMIL inside the SVG, which needs no
script, so the drawing moves in an <img>: in a GitHub README, on npm and
in any docs page.

Does it follow dark mode?

One SVG carries both themes and follows the reader's system setting. To
follow GitHub's own theme instead, draw with --split-themes and put the
two files in a <picture> with prefers-color-scheme.

Does it need a server, a browser or the network?

No. archgram is one native binary, and the SVG is self-contained: no
script, no external file, no web font, so it shows the same wherever it is
opened.

How is it different from Mermaid?

Mermaid draws many kinds of diagram from text and is rendered by the page
that shows it; GitHub renders it in Markdown. archgram draws two kinds,
the architecture of a system and the sequence of one request, into an SVG
file ahead of time: it routes the lines around the cards, animates the
flows and embeds its font, so the file looks the same everywhere. For a
chart, or a kind archgram does not draw, Mermaid is the better tool.

How is it different from draw.io or Excalidraw?

draw.io and Excalidraw are canvases you arrange by hand, which suits a
sketch. archgram places everything from the spec, so the diagram lives in
git beside the code and changes in a diff when the system does.

How is it different from D2 or PlantUML?

D2 is a language for many kinds of diagram, and PlantUML draws UML from
text, such as sequence, class and deployment diagrams. archgram draws two
kinds, the architecture of a system and the sequence of one request, from
a spec in plain YAML or JSON that an agent can write from the code; it
routes the lines, animates the flows inside the SVG and gives the same
file on every machine. For the rest of UML, PlantUML is the better tool;
for a diagram in many shapes, D2 is.

How is it different from Structurizr and the C4 model?

Structurizr models a system once in its DSL and draws several C4 views
from that model; it is the C4 model's reference implementation. archgram
draws one diagram per spec, the parts and the path a request takes, as an
animated SVG for a README or a docs page. To keep several C4 views in
step, Structurizr is the better tool.

Can a coding agent draw my architecture from the code?

Yes, with the archgram skill (above): it reads the code, draws a part
only where a file backs it and an edge only where a line of code makes it,
and lists both.

How do I keep architecture diagrams in sync with the code?

Keep the spec in git beside the code. archgram redraws the diagram from
it, and its agent skill can write the spec again from the code, so the
diagram changes in the same pull request as the system. When the spec
names the code behind each part and line (source), or the document
that states them, archgram check says which of it is gone, so CI can
fail a pull request that leaves the diagram behind.

Can it use my design system's colours?

Yes: --theme-file maps archgram's colour roles to your design tokens
(W3C Design Tokens), and refuses colours that fall short of contrast
(docs/SPEC.md, Theme
file).

Will the same spec give the same file tomorrow?

Yes, byte for byte, on every machine, so a diagram changes in git only
when the system does.

Documentation

• archgram.dev: what archgram does, with drawings it made.
• docs/SPEC.md: the spec, every field and rule, with examples.
• DESIGN.md: the visual rules.
• ARCHITECTURE.md: how archgram works inside.
• examples/: complete specs.

License

MIT. The embedded font, Geist, is under the SIL Open Font
License; technology logos come from Simple Icons, CC0.