pen.dev

A .pen file is plain JSON: children holds the frame tree and variables holds the tokens. Three writers touch it:

The pen CLI runs its own designer agent. pen --in X.pen --out X.pen --prompt ... rewrites the whole file. pen status must show an active session.
The pen.dev desktop app, driven through the pen.dev (Pencil) MCP execute tool (Get, Update, Export, SetVariables, ...).
Scripts that read and write the raw JSON.

Keep design files in designs/ (for example designs/app.pen), never in a temp folder.

Branches

Designer iteration: the owner wants screens or a design system designed by the pen designer, whether a first build from a brief, a multi-screen round, or a refinement grounded in Mobbin evidence.
Gated runs: a change must touch only named frames or components in a shared file, or an owner reviews every change. It holds the snapshot and frame-diff procedure the other branches reuse.
Token migration: renaming, aliasing, deleting or restructuring variables, adding dark mode, removing literal colours, or nodes rendering black after a token change.

A designer round that an owner reviews runs inside the gate. A token migration uses the gate's snapshot and diff as its structural check.