The diagram above is docs/hero.yaml: 40 lines of YAML, laid out and rendered by orrery. It moves because every SVG is animated by default: a packet travels each edge, and the numbered steps play in order, on a loop. GitHub keeps the animation; the PNG of the same spec is a still frame.

What you get

• Official, current icons only. 16,682 icons: AWS (810), Azure (636), Google Cloud (233), Kubernetes (40), GitHub Octicons (399) and IBM Carbon (2,776), plus 5,502 tech logos and 6,286 neutral symbols for system design. The cloud packs are rebuilt from each vendor's own download, pinned by checksum. Google Cloud products get the icon Google's 2026 guide assigns them; deprecated sets and unofficial redraws of cloud icons are left out.
• Official conventions. AWS groups follow the AWS Architecture Icons deck (borders, dashes, corner tiles, label placement, open arrowheads, numbered callouts); Google Cloud and Azure groups are measured from their own reference diagrams. Every value cites its source in styles.md.
• Automatic layout. The Eclipse Layout Kernel places nested boundaries, routes edges at right angles, joins fan-in and fan-out into trunks and keeps the order you wrote unless that would cross edges. No coordinates to write.
• Diagrams that move. Animated SVG by default: packets travel every edge at one speed, numbered steps play as a story, line styles stay as drawn. animate: flow for marching dashes, --static for a still file.
• Five outputs from one spec. SVG for READMEs and docs, PNG for slides and chat (3x by default, sharp when zoomed), .drawio you can keep editing, a TSX component for React sites, and a standalone HTML viewer with dark mode, pan and pinch zoom.
• Made for agents. A skill with a fast path and authoring rules, a JSON Schema, 392 short aliases (aws:s3, azure:aks, k8s:deploy), ranked icon search, and a validator whose every finding names the subject and the fix.
• No install. The CLI, layout engine, PNG renderer, fonts and the official cloud packs ship in the skill folder (9 MB). Logo and glyph sets are not copied in: they load from their own npm libraries the first time a diagram uses them, verified by checksum and cached. Node.js 22 or newer is all it needs.

Install

Claude Code plugin:

/plugin marketplace add Sagargupta16/orrery
/plugin install orrery@orrery

Any agent that reads Agent Skills (Codex, Cursor, Gemini CLI, Kiro and others):

npx skills add Sagargupta16/orrery
gh skill install Sagargupta16/orrery orrery              # GitHub CLI, any supported agent
gemini extensions install https://github.com/Sagargupta16/orrery   # Gemini CLI extension

Only the CLI, from npm:

npx @sagargupta1610/orrery doctor
npx @sagargupta1610/orrery render diagram.yaml -f all --theme both

Or from a clone: node orrery/skills/orrery/scripts/orrery.mjs doctor.

Quick start

Ask your agent for a diagram ("draw the architecture of this repo", "a three-tier web app on AWS across two Availability Zones", "turn this Mermaid flowchart into a Google Cloud diagram"). It writes a spec, validates it, renders it and checks the picture. Or write one yourself:

title: Orders API
direction: right
groups:
  cloud:  { type: aws:cloud }
  region: { type: aws:region, label: eu-west-1, in: cloud }
nodes:
  users: { icon: aws:users, label: Customers }
  api:   { icon: aws:api-gateway, in: region }
  fn:    { icon: aws:lambda, label: Create order, in: region }
  table: { icon: aws:dynamodb, label: Orders, in: region }
edges:
  - users -> api: HTTPS
  - api -> fn -> table

node skills/orrery/scripts/orrery.mjs render orders.yaml -f svg,png

Labels default to the official service names, so { icon: aws:lambda } reads "AWS Lambda". Edges use arrows: -> solid, --> dashed, ..> dotted, ==> thick, <-> both ways, a -> b, c to fan out. The full format is in spec.md.

Gallery

Every picture below is the animated SVG rendered from a spec in skills/orrery/examples, checked against the renderer by CI; orrery init <name> copies any of them as a starting point. All 27, with commands, in examples/README.md.

modern-web-stack: Cloudflare, Next.js on Vercel, Neon, Upstash, Stripe, Clerk, Resend, Sentry and PostHog, drawn as cards

gitops-kubernetes: GitHub Actions and Argo CD with the official Kubernetes icons, numbered steps from pull request to production

gcp-gke-platform: Google Cloud's own frames and 2026 product icons around a GKE cluster and its delivery pipeline

azure-hub-spoke: an Azure hub-spoke network with ExpressRoute, a VPN backup, Azure Firewall, Bastion and private endpoints

data-platform-oss: an open-source lakehouse from change data capture to dashboards

rag-open-source: RAG with open components: an ingestion lane and a query lane meeting at Qdrant

multi-cloud: each vendor's own group style side by side, joined at a colocation router

system-design-url-shortener: vendor-neutral system design with product logos

aws-three-tier: VPC, two Availability Zones, public, web and data subnets, an Auto Scaling group drawn across both zones

c4-container: a C4 container view built from shapes

How it works

Validation that tells you the fix

$ orrery validate orders.yaml
error DG101 node "fn" uses unknown icon "aws:lamda" {"node":"fn","icon":"aws:lamda"}
      fix: use icon "aws:lambda"
      fix: run `orrery icons search lamda`
error DG108 unknown key "lable" in node "db" {"where":"node \"db\"","key":"lable"}
      fix: rename "lable" to "label"
failed: 2 error(s), 0 warning(s)

Spec errors (DG1xx) stop the render; composition warnings (DG2xx: an edge through a node, colliding labels, a diagram too wide to read) keep it going unless --strict is set. render --json writes every file atomically and prints a receipt with the size and SHA-256 of each output.

A review board that measures before it judges

orrery review looks at the diagram at the width readers see it (880 px for a README column) and scores six dimensions: official conventions, layout, grid, arrows and flow, overlap, and size and quality.

$ git show v0.2.1:skills/orrery/examples/gitops-kubernetes.yaml > gitops-0.2.yaml
$ orrery review gitops-0.2.yaml --width 880
review gitops-0.2: 1964x786 in a 880px column, seen at 880x352 (scale 0.45, light)
score 85.3/100  FAIL (pass = no blocker or major and score >= 85)
...
blocker quality.label-size node labels render at 5.82px at this width (1964px canvas shown at 0.45x)
        fix: use direction: down so the diagram is narrower

The review loop took that diagram to 98.5 and passing: it now runs top to bottom, so its labels show at full size in the README column.

In Claude Code, /orrery:review <spec> runs the full loop. Code measures everything that can be counted: overlaps, crossings, alignment, text size and contrast at display width. Three read-only agents run in parallel and judge what cannot be counted:

• conventions-reviewer checks the vendor's own rules, quoted from the AWS deck, Azure Well-Architected, Google's icon guide and the C4 notation.
• flow-reviewer checks the story the arrows tell.
• legibility-reviewer reads the PNG at display size.

A finding counts only if it cites a measured value or a vendor rule. Each round applies one to three spec patches, and a round is kept only when the score goes up and no hard count does; the loop stops after three rounds or two without progress. Vision models are weak at counting overlaps and intersections, so they never decide those. The rubrics live in references/review, so the same passes run inline anywhere the skill is installed without subagents.

Commands

Command	Does
render <spec> [-o base] [-f svg,png,drawio,tsx,html|all] [--theme light|dark|both] [--animate packets|flow|none] [--static]	Validate, lay out, render.
validate <spec> [--strict] [--json]	Spec errors and composition warnings, each with fixes.
review <spec> [--width 880] [--theme light|dark] [--strict] [--json]	Score the diagram at the width readers see it; writes <base>.review.json and a PNG at that width.
icons search <words> [--pack aws]	Ranked icon ids with official names.
icons show <id>, icons list, icons packs	Browse the catalog and its sources.
icons fetch	Download and cache the logo and glyph libraries for offline renders.
styles	Every group type and node shape.
init [template]	Start from one of the examples.
import mermaid <flowchart.mmd>	Turn an existing Mermaid flowchart into a spec, with official icons where the labels name real products.
doctor, demo	Check the install; render every example.

Icon packs

Pack	Icons	Source	Ships
aws	810	AWS Architecture Icons, 2026-07-31 package	bundled
azure	636	Azure Architecture Icons V24	bundled
gcp	233	Google Cloud icons, core and category icons mapped to products as in Google's May 2026 guide	bundled
k8s	40	Kubernetes community icons	bundled
github	399	GitHub Octicons	npm @primer/octicons
ibm	2,776	IBM Carbon icons, IBM's diagram node icons and product glyphs	npm @iconify-json/carbon
logos	2,151	SVG Logos	npm @iconify-json/logos
si	3,351	Simple Icons	npm @iconify-json/simple-icons
tabler	6,286	Tabler Icons	npm @iconify-json/tabler

Bundled packs exist only as vendor downloads, so they ship with the skill and work offline. The npm sets load at render time from a local node_modules, the user cache or jsDelivr, checked against a pinned SHA-256; orrery icons fetch caches them ahead of time, and icons.md has the details. Renovate's monthly dependency PR also checks the vendors' pages for new releases and carries the updated packs. Icons, logos and trademarks belong to their owners and are used under the terms listed in THIRD_PARTY_NOTICES.md; the AWS, Microsoft and Google terms allow them in architecture diagrams.

Development

pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm build                       # src/ -> skills/orrery/scripts/orrery.mjs
pnpm gallery                     # re-render examples/ and docs/
node scripts/check-repo.mjs      # dashes, links, counts, doc snippets, gallery freshness
pnpm sync-icons                  # rebuild icon catalogs (--latest re-pins new vendor releases)
node scripts/pack-npm.mjs        # stage the npm package in out/npm (a GitHub release publishes it)

See CONTRIBUTING.md for how the pieces fit and SECURITY.md for reporting issues.

License

Code and docs: MIT. Icons, fonts and the vendored engines keep their own licenses: THIRD_PARTY_NOTICES.md.