Skip to content

Cinegram

Mermaid draws the system; Cinegram plays the story.

Animated, narrated, explorable architecture diagrams from a Mermaid-compatible DSL — for the humans who read them and the AI agents that write them.

A static diagram shows you that an Ingress sits in front of a Service. It cannot show you what happens to a single GET /api/orders as it travels LB → Ingress → Service → Pod and back. Cinegram adds a small animation language on top of Mermaid so that path becomes something you can watch.

Press play.

That is not a video and not a GIF. It is the diagram below, compiled to a timeline and animated in your browser — scrubbable, and readable as text in the source.

Where to go

  • The examples tour

    Twelve diagrams, front to back: a request path, a release, a failure and a recovery, a consensus round. Each one plays on the page and opens in the playground.

  • The guide

    What a .dgm file is made of, how to narrate one, how to present it, and every command the CLI has.

  • Embedding cinegrams

    Putting a player inside a page of your own — a Zensical or MkDocs site, or anything else you serve. This site is built that way.

  • The playground

    The compiler itself, built to WASM and running in the tab. Paste a diagram, watch it animate, share the link. Nothing is uploaded.

Let your AI write it

The fastest way in is the authoring skill for Claude Code or Cursor — one line, no clone, no build:

curl -fsSL https://raw.githubusercontent.com/panset/cinegram/main/skills/cinegram/install.sh | sh            # Claude Code
curl -fsSL https://raw.githubusercontent.com/panset/cinegram/main/skills/cinegram/install.sh | sh -s -- cursor  # Cursor, from the project root

Then start a session and ask for what you want:

  • "Animate this Mermaid diagram with cinegram and give me the HTML: …"
  • "Understand the request flow in src/api/ and create a cinegram of it"
  • "Read .github/workflows/deploy.yml, draw the pipeline, and animate a deploy"
  • "Add a failure path where the payment provider times out"

The agent writes the .dgm, lints it until clean, and previews it as one self-contained HTML file you can open, share or commit — fetching the cinegram binary itself if you have none. skills/cinegram/ has the details; cinegram mcp offers the same tools to any MCP host.

Get it

A single static binary with no runtime dependencies — the compiler, the player and its own copy of Mermaid are all inside it. No package manager involved:

# target: darwin-arm64 | darwin-x64 | linux-x64 | linux-arm64
#         (Windows: cinegram-win32-x64.exe)
TARGET="$(uname -s | tr A-Z a-z)-$(uname -m | sed -e s/x86_64/x64/ -e s/aarch64/arm64/)"
mkdir -p ~/.cinegram
curl -fsSL "https://github.com/panset/cinegram/releases/latest/download/cinegram-$TARGET" \
  -o ~/.cinegram/cinegram
chmod +x ~/.cinegram/cinegram
~/.cinegram/cinegram version

Then cinegram preview diagram.dgm -o out.html and open it. Later, cinegram upgrade replaces the binary in place with the checksum-verified latest release.

If you would rather not think about it, a package manager you already have can fetch the same binary for you — both of these download the release for your platform, check it against the release's SHA256SUMS, and cache it under ~/.cinegram/bin/:

npx cinegram preview diagram.dgm -o out.html   # Node 18+
uvx cinegram preview diagram.dgm -o out.html   # uv

There is also a VS Code extension with a live preview beside the editor — it carries the same binary — and the source is on GitHub.