paper-motion

For agents

paper-motion is built to be driven by an AI agent. The agent proposes and builds; the user decides each stage in the studio, a page on their own machine.

The starter prompt

Use paper-motion.vercel.app to make a video for my brand. Read https://paper-motion.vercel.app/llms.txt first, interview me, then let me decide each step in the paper-motion studio and on board links I can open.

The user pastes it in Claude Code, Codex, Cursor or any agent that reads the web and runs commands. From there the agent reads llms.txt, installs the skills and the engine, and follows the make-video skill.

If you are the person and not the agent: this prompt is all you type. Everything below is run by your agent; you only open the studio and decide.

Five stages

A video is made in five stages; the user sees them as four steps on one page, the studio (the brief and the content share the first). They decide each one there, and edit the video themselves.

  1. 01

    Brief

    Interview the user, then fill the five fields: what, who, format, tone and action.

    • piece init
  2. 02

    Content

    Gather what the video can really show from their site, files and brand. They keep, remove or correct each thing.

    • inventory --from
  3. 03

    Look

    Colours, type, background and movement, chosen by watching their own sentence. Done already when the brand settles them; you may suggest options.

    • board --url
  4. 04

    Video

    The studio builds the first cut. They edit it scene by scene; you listen in the background and do what they ask for.

    • piece listen
  5. 05

    Final

    The full render, from the studio or by you.

    • chain --motion-blur 5

The user

Makes the piece on one page, the studio, in four steps: what it says, how it looks, the video scene by scene, export. Edits everything there themselves and approves each step.

The agent

Hands over a stage with piece review, then keeps piece listen running in the background: what the user does arrives on its own, as lines (an approval, a change to make, an answer, a pick, an edit they already made). Build on those edits, never undo them. The studio only shows what it can check about the agent: listening, working on something, asking, or not connected.

Boards

Visual choices the agent suggests. While a piece is open and its studio runs, they appear in the studio on the step they decide; otherwise they are links on this site the user opens to compare and choose.

Without a browser

Only when the user can't open one, run the same stages in the chat.

One piece, start to finish

Every command of a real piece, in the order it is run: paper-motion’s own film, the one on the home page. Each stage ends with a review, and the next one waits for it.

  1. 00Set up

    • $ npx skills add solanodz/paper-motion
    • $ npx paper-motion setup
  2. 01Brief

    • $ npx paper-motion piece init paper-motion --title "paper-motion"
    • Interview the user: what the film says, to whom, format, tone, the action at the end.
    • $ npx paper-motion piece init paper-motion --what "Art-directed video from a conversation" --who "people who build with coding agents" --format "16:9, 30 s" --tone "quiet, exact" --action "paper-motion.app"
    • $ npx paper-motion piece review paper-motion brief
  3. 02Content

    • $ npx paper-motion inventory paper-motion --from https://paper-motion.vercel.app --from README.md --from brand
    • It reads the site (and screenshots it on a desktop and a phone), the README and the brand, and writes what it finds as proposals. Read every one before the user does: drop the noise, aim for six to eight things worth showing, and fill what the report says is missing.
    • $ npx paper-motion inventory paper-motion --remove <id>,<id>
    • A command found in a README has no output until it runs. Run it and pipe what it really printed; never invent one.
    • $ <the command> 2>&1 | npx paper-motion inventory paper-motion --output <id>
    • $ npx paper-motion piece review paper-motion inventory
    • In the studio the user keeps, removes or corrects each thing, stars what must appear and adds their own, then moves on to How it looks.
  4. 03Look

    • If the brand already settles colours, type and a background, this step opens done. To suggest options, use the same board command: with the studio running they go into How it looks, not into a link.
    • $ npx paper-motion board --url --title "Looks for paper-motion" --ask "Which feels like it?" --option sage-night --option slate-sea --option clay-desert --option ochre-sun
    • It prints where they show and waits for the pick, then the same reply line: paper-motion: C · clay-desert. A palette, font pair or background they pick is already applied to brand/. When they press Make my video, the studio builds the first cut itself: the planner's structure, every scene filled with their content.
  5. 04Video

    • $ npx paper-motion piece review paper-motion video --no-wait
    • Then keep listening in the background, so the user never has to come back to the chat. It returns as soon as they need you, with lines like review's; start it again after (exit 3 means nothing in 9 minutes).
    • $ npx paper-motion piece listen paper-motion
    • The user edits it scene by scene: text, animation, background, speed and the transition into the next; order, scenes added or removed. Each edit is a line; build on them, never undo them. Do only what they ask for in Ask your agent (a changes line). Say what you are doing, and answer them in the studio:
    • $ npx paper-motion piece working paper-motion video --on "warmer words for the ending"
    • $ npx paper-motion piece say paper-motion "Done: the ending is warmer now."
  6. 05Final

    • The user renders it from the studio's Export step. Or render it yourself:
    • $ npx paper-motion chain paper-motion --motion-blur 5
    • $ npx paper-motion piece review paper-motion final
    • $ npx paper-motion studio --stop

Commands

The reference: every command of npx paper-motion with what it does, grouped by job. Each group names the stages it serves.

Set up

before the briefThe skills and the engine. Every command answers --help.

  • $ npx skills add solanodz/paper-motion

    The skills. Read make-video right after installing and follow it in this session.

  • $ npx paper-motion setup

    The engine: Node 18+, ffmpeg and Chrome.

The studio

every stageWhere the user decides. Start the piece right after setup.

  • $ npx paper-motion piece init <piece> --title "…"

    Starts a piece, and the project's studio in the background.

  • $ npx paper-motion piece init <piece> --what "…" --who "…" --format "…" --tone "…" --action "…"

    Writes the brief, after the interview.

  • $ npx paper-motion piece review <piece> <stage>

    Hands a stage to the user. The first time it opens the studio in their browser. It waits for their decision and prints what they did, one line each. It refuses while an earlier stage is not approved; --skip moves on without it, only when the user agreed.

  • $ npx paper-motion piece working <piece> <stage>

    Marks a stage as yours: when you start it, or after the user asked for a change. The studio shows you are on it. Fix it, re-render, then review again.

  • $ npx paper-motion piece listen <piece>

    Keep it running in the background between your turns. It returns as soon as the user needs you (a message, an answer, an approval, a pick) with lines like review's, and marks them read; exit 3 after 9 minutes with nothing: start it again.

  • $ npx paper-motion piece ask <piece> "<question>"

    The studio shows the question with a box to answer it; their answer reaches piece listen. Ask it in the chat too. It closes when they answer, or with your next review or working.

  • $ npx paper-motion piece working <piece> <stage> --on "…"

    Says what you are doing, in plain words; the studio shows it with how long, until you listen or review again (20 minutes at most).

  • $ npx paper-motion piece say <piece> "…"

    A short reply the user reads in the studio, under Ask your agent.

  • $ npx paper-motion piece status <piece>

    Shows where everything stands and what you haven't read.

  • $ npx paper-motion studio --stop

    Ends the background studio when the piece is done.

Boards

look, videoTwo to four options from the registry for one visual decision. With a piece open and its studio running they go into the studio (no link); --link makes one anyway.

  • $ npx paper-motion search --type background --mode dark --near "#0a0f1f,#eef1f8,#3d6bff"

    Filters the registry by its metadata. With --near it sorts by color fit to the brand's ground, text and accent.

  • $ npx paper-motion board --url --title "Backgrounds for Kiln" --look cobalt,geist --option mesh-graphite --note "quiet, graphite" --option neuro-slate --note "a technical web" --option "dither-slate:colorFront=#3d6bff" --note "pixels in your accent" --option grain-slate

    Prints the board's link, keeps running, and prints the choice the moment the user makes it (it waits 10 minutes by default). The options play live in the look you pass.

  • $ npx paper-motion board --await <id> --wait 2

    When your shell caps how long a command may run: share the board with --no-wait, then ask with this until it prints the line. Exit code 3 means not yet.

  • paper-motion: B · mesh-sage --set speed=0.8 (bg-1)

    What it prints when the user chooses: one line, carrying every value that differs from the defaults as --set arguments.

  • paper-motion: A+C · type-on · scramble (text-1)

    When the board let them pick several, with --choose 1-3.

  • paper-motion: none of bg-1, calmer ones

    None of these, and what they would rather see.

Install

the brandResources become code the user owns.

  • $ npx paper-motion add <id> --set key=value

    Run it in the project root with exactly the --set arguments from the reply. Moves go to moves/, backgrounds to brand/shader-set/set.json, palettes and fonts to brand/tokens.json, recipes to pieces/<id>/.

  • $ npx paper-motion add <id> --force

    add never overwrites a value already in the project. Pass --force when the user chooses or tunes again something you installed before.

Content

contentWhat the video can really show. Nothing goes in that is not true.

  • $ npx paper-motion inventory <piece> --from <url> --from README.md --from brand

    Reads a site (and screenshots it), a markdown file, a folder or the brand, and adds what it finds as proposals for the user to keep or remove. Run it again any time: it never proposes twice. Add --plain when the audience does not code: commands and code are left out.

  • $ npx paper-motion inventory <piece>

    Checks pieces/<piece>/inventory.json and says what is missing: nothing shows the product, nothing proves it, an item still incomplete.

  • $ npx paper-motion inventory <piece> --remove id,… --must id,… --set id.field=value

    Drops the noise, marks what has to appear, corrects a field.

  • $ <command> 2>&1 | npx paper-motion inventory <piece> --output <id>

    Gives a command its real output. Review refuses while an item is incomplete.

  • $ npx paper-motion inventory kinds

    The kinds of content (a figure, a sentence, a screen, a command…), their fields and the blocks that show each.

  • $ npx paper-motion plan <piece> --seconds 30

    Up to three structures from what the user kept, the same content argued in three orders. The studio uses the first when it builds the video.

Chain

video, finalA structure becomes a chain: its parts in order, rendered and joined. The studio runs these itself; they are yours when the user asks.

  • $ npx paper-motion chain init <piece> --plan A

    Installs the plan's structure A under pieces/<piece>/ with the content already in each part's CONFIG, and writes chain.json: the seconds of each part and the join between them. --board <link> --option D takes a structure chosen on a board instead.

  • $ npx paper-motion chain <piece> --check

    Plans without rendering: each part's length and speed (it always plays its whole scene, 1.6× faster to 0.6× slower), and the joins. Run it after writing the parts.

  • $ npx paper-motion chain <piece> --drafts

    A quick render of each part on its own. Add --only <dir> to redo one part.

  • $ npx paper-motion chain <piece> --draft

    A quick render of the parts joined.

  • $ npx paper-motion chain <piece> --motion-blur 5

    The full render: every part in the brand's look, joined into one video.

Entry points

The machine-readable ways in. They all live under https://paper-motion.vercel.app

/llms.txt

The flow, the metadata to choose with, the board link format and every resource in one line. Read it first.

/llms-full.txt

The full catalog in text: params, notes and usage for each resource.

/registry.json

The index: id, type, title, summary, tags and the metadata of each resource.

/r/<id>.json

One resource: params with ranges, install instructions, usage and the file contents.

/schema.json

The JSON Schema every resource follows.

/b/<id>

A board as a short link, stored for 90 days.

/b#<payload>

A board carried in the link itself: the payload is base64url(deflate-raw(JSON)) and never reaches the server.

/mcp

The same registry as tools, with no install: search, resource, recolor, board (it waits for the choice) and board_choice. Streamable HTTP, no auth. Add it to the agent before opening a session. Installing stays with npx paper-motion add.

https://paper-motion.vercel.app/mcp