What is Diorama?
Diorama is a playbook that a coding agent reads before it builds a small 3D scene in the browser: a staged set on a slab, seen from a three-quarter camera you can orbit, with toy-scale figures that walk, swim or fight. The scene is drawn with Three.js and finished in one of three looks: pixel art (a 64-colour palette with dithering and an inked outline), stroked toon, or both combined.
The core is SKILL.md, a long instruction file with skill frontmatter (name, description, version 5.7.0), so Claude Code and other skill-capable agents can load it by name. Around it sit topic files in references/ for long sessions, copy-in JavaScript modules in templates/ (camera, lighting, rigs, water, effects) and eight QA scripts that drive Chromium to screenshot and score frozen frames.
It is MIT-licensed JavaScript by Nehal Kanak (sloemo), created on 24 October 2026, with about 656 stars and 61 forks. It installs from npm as @sloemo/diorama, which recorded 1,913 downloads in the week to 17 November 2026.
Is Diorama worth it?
Diorama is less a code library than a contract for how an agent should work, and that is its strength. Before the first mesh, the agent must ask two questions, which look to use and whether models come from licensed libraries or are built by hand, then research the real subject on video, log every asset search in SOURCES.md and record licences in CREDITS.md. Assets marked non-commercial, no-derivatives or with no stated licence are a hard stop. Few agent skills take provenance this seriously.
The verification design is the other reason to look at it. Every scene is a pure function of time, so ?t=12.4 always renders the same frame, and the scripts in templates/qa/ freeze, screenshot and score it through playwright-core. The frames.mjs script records each actor separately and marks it FROZEN, TELEPORT, EMPTY or OFFSCREEN, so a figure that stopped animating cannot hide behind a busy neighbour. Agents tend to report success on scenes they never looked at; this makes them produce evidence instead.
The catch: it is heavy. The npm install copies about 155 files and 1.6 MB, and the install prompt tells the agent to read all of SKILL.md, the reference index, several templates and the worked examples before building. That costs context on every new session, and the README concedes that long builds will hit context compaction, which it handles by keeping state in files. The install prompt also tells agents to use npm rather than clone the repository so the download count reflects use, which makes that count a softer signal than it looks. The project is three and a half weeks old, has no tagged GitHub releases and has moved through many skill versions quickly.
Our take: for a one-off illustration or an explainer of a mechanism, the process is worth the tokens, because the QA scripts catch the problems a human reviewer would otherwise find later. For quick throwaway visuals, Teardown or a plain prompt is lighter; Diorama earns its overhead when the scene has several moving actors.
Where it earns its place
An indie game developer prototyping a level mood board
Get an animated pixel-art scene of a location without modelling it myself
Install the skill, name a subject, and the agent researches it, fills DESIGN.md, sources CC0 or CC-BY models and runs the QA scripts before showing frames. The cost is agent time and tokens; the code is free.
An engineering teacher building a web explainer of a four-stroke engine
Show a working mechanism students can click apart
Ask for an educational scene: the playbook's educational mode adds a side card, clickable parts with short explanations, keyboard selection and checks that simplification has not deleted working parts.
A marketing designer at a small studio making looping social clips
Turn a scenario into a short animated scene with credits that are safe to publish
The agent records every asset and its licence in CREDITS.md and refuses non-commercial ones, then hands over frozen frames and motion strips for review before anything is published.
Before you commit
- Setup
- Paste the README's install prompt into an agent with shell access; it runs npx @sloemo/diorama into a folder (Node 18+), verifies the file count, reads the playbook and reports back before building.
- Integrations
- Three.js r170; skill frontmatter for skill-capable coding agents; QA through playwright-core and Chromium, plus two Python helpers; optional demo media from @sloemo/diorama-media (20 MB).
- Data and privacy
- Everything runs locally in your project; the copy step installs nothing globally and runs nothing afterwards, per the README. Asset research happens through your agent's own web access. MIT licence.
- Limits
- Context-heavy on long builds; no tagged releases; quality depends on the agent following a long playbook, and the shown scenes are the author's own demos.
What’s good
- Ships as a SKILL.md that skill-capable agents load by name
- Deterministic scenes: any timestamp renders the same frame
- Eight QA scripts, including per-actor frame verdicts
- Strict licence rules and logs for every imported asset
What’s not
- Large playbook costs context at the start of each session
- Three and a half weeks old, with no tagged GitHub releases
- Fixed house style; other looks mean fighting the playbook
- Install prompt pushes npm installs to raise download counts
Best for
Developers who want a coding agent to produce animated Three.js scenes in a consistent pixel or toon style and prove each frame works.
Diorama alternatives
Diorama: common questions
- Is Diorama worth it?
- Diorama turns a vague request for a pretty 3D scene into a disciplined build with research, a fixed look and frame-by-frame checks, and asks a lot of the agent's context in return. We rate it 3.8 out of 5.
- How much does Diorama cost?
- Free and open source (MIT). You pay for the coding agent and model that use it.
- What are the downsides of Diorama?
- Large playbook costs context at the start of each session; three and a half weeks old, with no tagged GitHub releases; fixed house style; other looks mean fighting the playbook; install prompt pushes npm installs to raise download counts.
- Who is Diorama best for?
- Developers who want a coding agent to produce animated Three.js scenes in a consistent pixel or toon style and prove each frame works.
- Is Diorama safe for company data?
- Everything runs locally in your project; the copy step installs nothing globally and runs nothing afterwards, per the README. Asset research happens through your agent's own web access. MIT licence.
- What are the best Diorama alternatives?
- The closest alternatives we have reviewed are teardown, motionmaxxing and HyperFrames.
Answers checked Nov 18, 2026.