lanshu-animated-architecture-diagram: a Codex skill that turns one JSON spec into an animated GIF diagram

The gap it fills between hand-drawn sketches and diagramming apps

Most architecture diagrams are either static images exported from a drawing tool or code-driven graphs that look like code-driven graphs. This project sits in between. The README describes it as a Codex skill and local renderer for "premium black-canvas technical diagrams with hand-drawn typography, editable Excalidraw output, static PNG previews, and genuinely animated GIFs." The stated audience is article explanations, system architecture diagrams, process diagrams, and DailyDoseOfDS-style black-background technical sketches.

The practical problem is repetition. If you publish system walkthroughs regularly, you need a diagram style you can reproduce without redrawing it each time, and you need motion for the parts that are about flow rather than structure. The repository answers that with one JSON spec that fans out to three artifacts. The .excalidraw file stays editable and text-based, so a human can still open it and move things. The PNG is the static preview. The GIF carries moving glow points and pulsing module highlights.

It is not a general diagramming tool, and the README does not pretend otherwise. The design notes say the visual system is kept intentionally narrow: dark canvas, hand-drawn title treatment, a top input strip, a middle core pipeline, bottom source, layer and pack panels, and a top-right signature. That is a template with slots, not a canvas.

One JSON spec, three outputs, and a fixed 41-frame canvas

The renderer is a single Python script, scripts/render_animated_diagram.py, driven by a spec file. The README gives the pipeline as JSON spec to .excalidraw plus .png plus animated .gif, and states that each render produces three files named after the basename you pass in.

The animation is not a video. It is a frame sequence composited with Pillow: the README says the default canvas is 1210 x 1138 at 20 fps across 41 frames, which is 2.05 seconds. Motion comes from moving glow points and pulsing module highlights layered over a clean static diagram, a split the design notes make explicit: "Clean static diagram with motion added only in GIF overlays." That is why the .excalidraw file can stay sane. The animated layer is not part of the editable vector source.

The spec fields you are expected to touch are listed in the README: signature, title.prefix, title.highlight, title.subtitle, inputs, core.cards, decision, output, left_panel, center_panel and right_panel. Iconography is limited to seven keys: folder, file, scan, shield, db, hash, package. Anything outside that vocabulary is not documented in the README, and the reference file references/spec-format.md is where the README sends you for detail.

Dependencies are deliberately thin. requirements.txt contains one line, Pillow>=10.0.0. The README states the project does not require Excalidraw, browser automation, ImageMagick, remote APIs, or external icon libraries. ffprobe is optional, for media inspection.

Installing the skill and rendering your first animated diagram

The README gives two install paths. For Codex use, the folder goes into your skills directory. The repository also documents a typical local path built from CODEX_HOME, defaulting to $HOME/.codex.

~/.codex/skills/lanshu-animated-architecture-diagram

${CODEX_HOME:-$HOME/.codex}/skills/lanshu-animated-architecture-diagram

For a plain local checkout, clone the repository and install the single runtime dependency. The README requires Python 3.9+ and Pillow 10.0.0+.

git clone https://github.com/cclank/lanshu-animated-architecture-diagram.git
cd lanshu-animated-architecture-diagram
python3 -m pip install -r requirements.txt

Then render the bundled template. The --verify flag prints sampled frame differences, and the README states that nonzero changed pixels confirm that the GIF is genuinely animated. The --check flag validates the generated PNG, GIF and Excalidraw output contract and exits nonzero if a required property fails.

python3 scripts/render_animated_diagram.py \
  --spec assets/default-spec.json \
  --outdir outputs \
  --basename sample \
  --verify

You should end up with sample.excalidraw, sample.png and sample.gif in outputs. To make your own, copy the template and edit the documented fields.

cp assets/default-spec.json work/my-diagram-spec.json

If you are driving it from Codex instead of the shell, the README shows the invocation form directly: "Use $lanshu-animated-architecture-diagram to turn this article into a premium hand-drawn animated architecture GIF."

What --check actually validates, and where the renderer can fail you

The --check flag is the most useful thing in the repository for anyone who has been burned by a GIF that turned out to be a single frame repeated. According to the README, it checks dimensions, GIF frame count and frame duration, sampled GIF motion, unique Excalidraw IDs, text font family, and that no external files are embedded. That last check matters if you plan to hand the .excalidraw file to someone else: an embedded external file would break the portability the format is supposed to give you.

The failure modes are mostly about the spec, not the renderer. The README does not document rollback, partial renders, or what happens when a spec field is missing or an icon key is outside the supported seven. There is a tests/ directory in the repository layout, but the README does not describe what it covers, so you cannot infer validation behaviour from it.

The bigger limitation is layout. The design notes describe a fixed structure, and the README calls it "a fixed high-quality layout for clean technical storytelling." If your architecture does not fit a top input strip, a middle core pipeline, and bottom source, layer and pack panels, you are fighting the template. There is no documented way to place a node at an arbitrary coordinate, no documented multi-page support, and no documented theming beyond the dark canvas. The frame budget is fixed at 41 frames and 2.05 seconds in the default configuration, and the README does not describe a flag for changing frame count, frame rate or canvas size. For a looping explainer that is fine. For anything that needs a longer narrative or a different aspect ratio, it is the wrong tool.

How it differs from Excalidraw itself and from diagram-as-code tools

The obvious alternative is Excalidraw, and the README names it as a supported output format rather than a competitor: the project writes .excalidraw JSON and lists the Excalidraw web app or editor plugin as an optional dependency for manual editing. The difference in approach is that Excalidraw gives you a canvas and no opinion about your diagram, while this project gives you an opinion and no canvas. You get hand-drawn typography, a signature, grain and vignette, and animation, but you give up free placement. If you want to draw exactly what is in your head, open Excalidraw. If you want the same polished look every week with a spec you can diff in git, this is the narrower but faster path.

The other comparison is diagram-as-code tools that generate SVG or PNG from a text description. Those typically target accuracy and layout automation, and they generally do not produce animation. This project does not parse your description into a graph. You fill in named slots, and the renderer composites a known-good layout. That is a weaker abstraction but a more predictable output, which is the trade the design notes openly make.

One point worth flagging: the README's feature list says it does not require remote APIs or browser automation. Everything runs through local Pillow rendering, so a render does not depend on a network round trip or a headless browser version.

Maintenance status, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-03. Recent releases were not retrieved, so there is no version history to reason about: you are tracking the main branch. For a project this small that is a minor concern, since the surface area is one script, one spec template, one reference document and one dependency. It is also the reason an upgrade is cheap. Pillow>=10.0.0 is an open lower bound, so a pip install can pull a newer Pillow than the one the author ran, and the README does not pin an upper bound. If a Pillow release changes image or GIF encoding behaviour, the --check contract is your only automated signal, and it is the thing to run after any dependency bump.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is a permissive licence, and the practical implication is that you can ship generated diagrams and modified copies of the renderer inside a commercial product. Nothing in the repository raises a licensing question about the outputs themselves. This is a description of the licence text, not legal advice; if your use is unusual, read LICENSE and talk to counsel.

The real upgrade cost is visual, not technical. Because the layout is fixed, a future change to the template or the icon set can shift every diagram you have already published. Keeping your spec files in version control next to the outputs is the only way to tell whether a re-render changed something you did not intend.

Editorial conclusion

Adopt it if you write technical articles or system walkthroughs and want a repeatable black-canvas diagram with real motion, produced locally with no browser automation or remote API. Skip it if your diagrams need arbitrary node placement, live data, or interactive viewers: the README describes a fixed layout, seven icon keys and a 1210 x 1138, 41-frame canvas, and the repository does not document a way to change those. Before committing, run the render with --verify --check on assets/default-spec.json and confirm the reported pixel differences and output contract pass on your machine.

Frequently asked questions

Official sources

1. cclank/lanshu-animated-architecture-diagram on GitHub
2. Issues
3. License: MIT
4. README