Archscribe: a skill and renderer that turns one JSON file into hand-drawn, genuinely animated diagrams

Diagrams that look hand-drawn and actually move

Archscribe is a Codex and Claude skill paired with a local renderer that generates premium hand-drawn technical diagrams: hand-drawn fonts, editable Excalidraw source files, static PNG previews, and, distinctively, genuinely animated GIFs. The README's pipeline is one line: a JSON config becomes an `.excalidraw` file plus a `.png` and an animated `.gif`, with `.mp4`, standalone `.svg` and interactive `.html` also available.

The user is someone explaining a system, an agent, or a workflow in an article or presentation who wants diagrams with the DailyDoseOfDS sketch aesthetic rather than sterile boxes, in either a dark-neon or a light-paper style. Because it is driven by JSON and invoked as a skill, an agent can generate these diagrams from a prompt, which is the intended workflow.

What makes it more than a diagram library is the combination of editability and real animation. The Excalidraw output stays editable plain text, so a human can tweak the result, while the GIF and MP4 are actually animated rather than static images pretending to move. It is MIT licensed, Python-based, with bilingual documentation.

Three layouts, two styles, six animation presets

Archscribe is opinionated about structure, which is what keeps its output coherent. The README defines three layout templates chosen by a `layout` field: `panorama` for a full system view of inputs, core pipeline and output panels; `swimlane` for category bands and role comparisons; and `graph` for free node-and-edge topologies with automatic DAG layout and dedicated loop channels. Long graphs stack vertically automatically to avoid cropping.

Two styles, set by `--style` or a config field, share identical layout, animation and icons and differ only in finish: `default` is a black-background neon sketch, and `paper` is a warm off-white with muted color bands and near-black ink, where the flowing animation becomes small dots moving along arrows instead of light beams. Six animation presets, `flow`, `draw`, `relay`, `trace`, `chapter` and `failure-recovery`, are selectable with `--animation` and work across all layouts.

The elasticity is specified: panorama supports 2 to 6 inputs and 2 to 4 core cards, swimlane 2 to 5 bands, and graph up to 24 nodes and 40 edges with `kind: "loop"` loop edges. The canvas height is computed from content, so you describe the diagram and the renderer sizes it, which is the right division of labor between config and tool.

Rendering a diagram

The renderer is a Python script driven by a JSON spec, and the README shows the command-line form with an explicit style override:

python3 scripts/render_animated_diagram.py \
  --spec assets/examples/swimlane-spec.json \
  --outdir outputs \
  --basename my-diagram \
  --style paper

The README notes that a `--style` flag takes priority over a `style` field in the config, and that `default` is used when neither is set. As a skill it is invoked in natural language with a `$archscribe` reference, describing the diagram you want and the formats to output.

The default browser renderer uses a headless Chromium with rough.js to hand-draw each shape and embedded webfonts for a true Excalidraw look, and a classic Pillow pipeline is kept as a fallback via `--renderer pillow`. A default render produces the `.excalidraw`, `.png`, `.gif` and `.mp4`, with `.svg` and interactive `.html` optional through `--formats`. The Python dependencies install from the repository's requirements.txt.

Validation and output contracts are built in

A detail that signals this is built for agent use is that Archscribe checks its own work. The README describes pre-render config validation, via `--validate-only` or automatically at render time, that reports field-level errors with a `path`, a `message` and a `fix`, so an agent can correct a bad spec automatically. That structured error format is aimed squarely at a model iterating on a config.

Beyond input validation, the README documents output-contract checks: `--check` verifies dimensions, frame counts, real animation, MP4 stream parameters, SVG font embedding, HTML hotspots and Excalidraw invariants, and checks whether a graph is cropped or vertically unbalanced. A `--verify` flag prints a frame-difference report. Verifying that the animation is genuinely animated, and that the MP4 and SVG meet their format contracts, is the kind of check most diagram tools never perform.

The interactive HTML output is its own feature: the README says clicking a module highlights its connections, a whole-chain checkbox shows BFS propagation across the graph, and the single file can be shared directly. Together with the editable Excalidraw source, this makes Archscribe output something you can refine and explore, not just a final image.

The limitations: a headless-Chromium renderer and a narrow purpose

The honest limitation is operational: the primary renderer runs a headless Chromium to achieve the true Excalidraw look, which is a heavier dependency than a pure-Python image library. The README keeps the classic Pillow pipeline as a `--renderer pillow` fallback precisely because the browser renderer is not always available, but the best output depends on Chromium being present, which is a real setup cost in constrained environments.

The second limitation is scope. Archscribe is built for explanatory diagrams of systems, agents and workflows in a specific sketch aesthetic, with three layouts and elasticity bounds (up to 24 graph nodes, 2 to 6 panorama inputs). It is not a general diagramming tool for arbitrary charts, and a diagram that does not fit panorama, swimlane or graph is outside its design. That focus is what makes its output consistent, but it is a boundary.

The aesthetic itself is also a commitment. The dark-neon and light-paper styles are distinctive and deliberate, which is a strength when that look fits your article and a limitation when it does not, since the styling is the point rather than an option to fully replace.

Against Mermaid or hand-drawing in Excalidraw

The alternatives are a text-to-diagram tool like Mermaid, or drawing by hand in Excalidraw directly. Mermaid is great for quick, clean, static diagrams from text and is widely supported, but its output is a standard rendered chart, not a hand-drawn animated one, and it does not produce editable Excalidraw sources or real GIF and MP4 animation. Hand-drawing in Excalidraw gives full control and the sketch look, but it is manual and not reproducible from a config.

Archscribe sits between them: config-driven like Mermaid, but producing the hand-drawn Excalidraw aesthetic, genuine animation, and an editable source you can still adjust by hand, with validation and output contracts suited to an agent generating the config. The cost is the heavier renderer and the narrower set of layouts. Choose Mermaid for fast static diagrams in a conventional style. Choose manual Excalidraw for full artistic control on a one-off. Choose Archscribe when you want reproducible, animated, hand-drawn explainers from a JSON spec, especially generated by an agent, and the sketch aesthetic is what you are after.

MIT, embedded assets, and where to start

Archscribe is MIT, with bundled fonts under the OFL and a Tabler SVG icon subset under MIT, and the README stresses fully offline rendering, so the renderer does not phone home for assets. That offline, permissively-licensed asset story matters for a tool meant to run inside an agent or a CI pipeline.

Upgrade cost is mostly the renderer dependency: the browser renderer needs headless Chromium, while the Pillow fallback needs only Python. Because output is driven by a JSON contract with validation, specs are portable across versions, and the `--check` and `--verify` flags give a way to confirm a render still meets its contract after an update.

The concrete first step is to render one of the example specs to see the aesthetic and confirm your environment: run `render_animated_diagram.py` against a bundled example with `--style paper`, check that the `.gif` and `.mp4` are genuinely animated with `--check`, and decide whether the panorama, swimlane or graph layout fits your subject before writing your own spec. If Chromium is unavailable, verify the `--renderer pillow` fallback produces acceptable output for your needs.

Editorial conclusion

Reach for Archscribe when you want reproducible, hand-drawn, genuinely animated explainer diagrams from a single JSON spec, especially generated by an agent: the editable Excalidraw output, the six animation presets, and the built-in validation and output-contract checks are its real strengths. It is the wrong tool for arbitrary charts outside its panorama, swimlane and graph layouts, or for environments where a headless-Chromium renderer is impractical, though the Pillow fallback covers the basics. Start by rendering a bundled example spec with render_animated_diagram.py and --style paper, confirm the GIF and MP4 are genuinely animated with --check, and pick the layout that fits your subject before writing your own config.

Frequently asked questions

Official sources

1. Issues
2. lazypay/Archscribe on GitHub
3. License: MIT
4. README