Your AI draws. The compiler says what’s wrong.

scenec is a command-line tool and agent skill that turns a YAML scene into an SVG and tells an AI, in text, what it drew and what is wrong with it. It runs on the CPU with no image model, works with Claude Code, Codex and Cursor, and gives the same SVG from the same scene on any machine.

$ npx skills add guilhermebkel/scenec -g
Star on GitHub
An illustrated winding path across an autumn landscape, with five checkpoints from a house to a stage, labelled An idea, A YAML scene, A compiler that measures, An art director in text, and scenec.
Drawn by scenec from a 96-line scene. Read the scene

A report an AI can read, line by line.

An image model needs eyes. scenec gives the AI text instead: what it drew, where, and what is wrong. The AI fixes the scene and runs it again until the report is clean.

scene.yamlReal first draft
canvas: { width: 1000, height: 1000, theme: flat-autumn, setting: outdoor, horizon: 0.6, base: 0.84 }
objects:
  arvore: { asset: tree, at: 0.15, depth: mid }
  menina: { asset: person, pose: hands_on_hips, at: 0.45, hair_color: red, size: large }
  rex:    { asset: dog, right_of: menina, facing: left }
  banco:  { asset: bench, at: 0.85 }
canvas: { width: 1000, height: 1000, theme: flat-autumn, setting: outdoor, horizon: 0.6, base: 0.84 }
objects:
  arvore: { asset: tree, at: 0.15, depth: mid }
  menina: { asset: person, pose: hands_on_hips, at: 0.45, hair_color: red, size: large }
  rex:    { asset: dog, right_of: menina, facing: left }
  banco:  { asset: bench, at: 0.78 }
terminalReal output
$ npx @guilhermebkel/scenec check scene.yaml
warnings:
'banco' is 10% outside the frame
'rex' overlaps 'banco' by 36%; use left_of/right_of or a different depth
art:
visual weight leans left (center of mass at 35% of the width); move 'arvore' toward the center or put something on the right side
'rex' blends into the background in the middle part (41% of this outline has no contrast): the color #c9a27a is too close; change the color of one of the two
# exit code 1
# The agent edits scene.yaml, never the SVG.
# banco: moved in from the right edge (at: 0.85 to 0.78)
# rex: given another color, so it stops blending in
2 warnings and 2 remarks to clear.
Fix the scene, not the SVG: every correction goes back through the scene.
$ npx @guilhermebkel/scenec check scene.yaml
nothing to report
# exit code 0
$ npx @guilhermebkel/scenec render scene.yaml -o out --png
out.svg out.png + JSON report

The first check is real output from the README. The fix and the second check are illustrative.

Four things come back with every run.

Everything it prints is JSON, so any agent can parse it. A typo costs one more cycle, not a failure.

Warnings

Fields it did not understand, with a “did you mean”. Missing assets. Objects out of frame.

did you mean

Art critiques

An art director’s remarks in text: empty bands, overlaps, low contrast, a crowded corner, a scene too small for its frame.

in plain text

A description of the layout

Position, size and depth of every object, so the AI can reason about composition without seeing it.

no eyes needed

Repeatable output

The same scene gives the same SVG on any machine. A bundled font makes the PNG look the same everywhere.

same scene, same SVG

The compiler measures. Your agent decides.

The work is split on purpose. A fast script on the CPU does everything that must be exact. Taste and intent stay with the agent.

Parse

Validates the scene and suggests the closest name for a field it does not know.

Local script

Compose

Places every object in the frame, with depth and relations like left_of.

Local script

Draw

Draws the SVG with the style kit and the light.

Local script

Critique

Measures what it drew and writes the remarks.

Local script

Your agent

Picks one of 8 recipes, writes the scene, reads the report and fixes it, up to 5 times. Fix the scene, not the SVG. The skill tells the agent to never edit the SVG by hand, so the result stays repeatable.

One scene, six looks.

scenec gives the AI a closed vocabulary: 86 assets, ready-made groups, a map of Europe and 6 style kits. Closed on purpose, because it is what the compiler can measure.

A person with raised arms in front of a blue house, drawn in the flat kitflatFlat vector with soft light. The default.
The same scene drawn in the outline kitoutlineCartoon outline: thick on the silhouette, thin inside.
The same scene drawn in the hatch kithatchEngraving or comic: ink outline and hatched shadows.
The same scene drawn in the riso kitrisoRisograph: few vivid inks, print grain, slight misregistration.
The same scene drawn in the paper kitpaperPaper cut-out: each piece with its own shadow and fiber texture.
The same scene drawn in the sketch kitsketchHand-drawn pencil look.

Renders from the project’s visual tests, cropped to the scene.

86assets: people with poses and expressions, furniture, plants, food, vehicles, buildings
6style kits
8recipes the agent starts from
108visual baselines checked in CI
  • reel
  • carousel
  • “wrapped” card
  • e-learning
  • illustrated story
  • route map
  • ad variations
  • product

It trades open-ended style for a vocabulary it can measure.

That is the whole bargain. Here is where it fits next to the other ways to get a picture.

ApproachWhat you getWhat it costs you

Image-generation models

What you get

Richer pictures.

What it costs you

A model that can see, money per image, and two runs never give the same result.

Hand-written SVG, Mermaid, Graphviz

What you get

Repeatable output.

What it costs you

No feedback on composition. They cover charts, not illustrated scenes.

Design tools with an API

What you get

A canvas to design on.

What it costs you

A canvas and a human eye in the loop.

scenec

What you get

Cheap, repeatable and checked, with feedback in text.

What it costs you

A closed vocabulary instead of open-ended style.

Everything runs on your machine.

No network calls, no telemetry. Nothing leaves your computer, and nothing is downloaded at run time.

Files stay in the scene folder

The file reader refuses .. and absolute paths.

Custom SVG is allowlisted

Scripts, on* handlers, external links, <style> and entities are removed or rejected.

No model, no GPU

Plain CPU code: geometry, drawing and a rasterizer.

Hard limits

At most 200 objects and a 4096 px frame per scene.

Found a way around any of this? See SECURITY.md.

Questions

Does it need an image model or a GPU?

No. It is plain CPU code: geometry, drawing and a rasterizer. Nothing is downloaded at run time.

Can I use it without an agent?

Yes. The CLI has render, check, catalog and schema. check exits with 1 when there is a warning or critique, and with 2 when the scene is invalid.

Can I add my own drawings?

Yes. Under assets: a scene can bring an SVG, inline or as a file next to the scene, or an image. Custom SVG goes through the sanitizer.

What if the AI mistypes a field?

Unknown fields are not errors. The compiler warns and suggests the closest name, so a typo costs one more cycle.

Why can’t the agent edit the SVG?

Every correction goes back through the scene, so the same scene always gives the same SVG on any machine.

What do I need to run it?

Node.js 20 or newer, and any AI that can run a command, such as Claude Code, Codex or Cursor.

Let the AI draw. Let the compiler tell it what it drew.

$ npx skills add guilhermebkel/scenec -g
Then ask your agentDraw a vertical cover for a reel explaining compound interest, flat blue style.

The installer asks which of your agents should get the skill. Drop -g to install only in the current project. Requires Node.js 20+.

Star on GitHub