How an agent should use raea

This page is for coding agents (Claude Code, Codex, Kimi, Gemini and others) and for the people who set them up. After reading it, an agent knows the loop raea expects, which commands to run at each step, and which steps need a person.

#Where each step runs

Every step below is marked with where it can run:

An agent with only a terminal can do every HEADLESS step, which covers making, checking and delivering. Each PAGE step below says what to do headless instead.

#1. Install the skill (once) — HEADLESS

curl -fsSL https://raea.io/install | sh            # installs raea and the skill for Claude Code
raea skills install --agent codex                  # or kimi, gemini: the skill where that agent reads skills

If the skill your agent loaded names a different version than raea --version, read raea skill instead. It prints the skill as the installed raea ships it.

#2. Read before you make — HEADLESS

In a project folder, print everything to read first, in order:

raea context .

That prints the person's taste (~/.raea/taste/taste.ts), the workspace's taste, the project's brief, its look, the workspace's controllers (its settings and workflows), the craft floor, and the guide for each of the brief's modes. Read all of it. A line in the person's taste beats any guide's default.

With no request in hand, raea next lists the two or three useful next steps for the project. Offer them to the person; don't run one unasked.

Right before any edit to a composition, even a one-line change, read the craft floor:

raea guide craft

raea guide alone lists every guide: the modes (pitch, explain, story, play, tool), motion, music, sound, layout, words, games, rendering, and bevy with its topics for 3D.

#3. Write the composition — HEADLESS

A composition is one .tsx file. The rules that keep a render right:

• Frame-pure. Everything that moves reads useCurrentFrame(). useState, useEffect and timers don't animate a render.
• Clamp every interpolate unless you mean the value to run past its ends.
• Cue on words, not guessed frames. word("phrase") is the frame where the phrase is said, so cues follow the cut. See Captions and cues on words.
• Games are a pure step. useGameState(initial, step), with keys from useInput(). See Your first game.

Compositions and frames explains why, with examples.

#4. Check it in a second — HEADLESS

After every save:

raea check piece.tsx --quick

It renders three stills and measures their text (clipped, cramped, outside the safe areas, too small) in about a second. With Claude Code, the installer's hook runs it for you after each save and hands you what it finds.

#5. Look at frames — HEADLESS

Render the moments that matter as PNGs and look at all of them in one batch: each cut, each part's entrance and settled state, the first half second, the end card.

raea render piece.tsx --at 0,45,89 -o frames/

Fix everything the batch shows, then render the batch again. Don't render one still per change.

#6. Render and check the export — HEADLESS

raea render piece.tsx -o piece.mp4 --manifest render.json
raea check piece.mp4 --manifest render.json -o piece.check.json

raea check measures what a still can't: text under a platform's buttons, captions on too briefly to read, caption contrast against the footage behind them, frozen stretches, flashing, cues that miss their words, loudness, and blotching in dark areas. Each finding is ranked P0 to P3 with its fix. It exits 1 while a P0 or P1 stands. Don't hand over a render while raea check still names a fault.

#7. Show it and take notes — PAGE, PERSON

In the raea app, post the render to the project's feed. The person watches or plays it there and leaves notes.

Headless instead: leave the file in the project's out/ folder, give the person its path, and take their notes as text.

#8. The next version — HEADLESS

• Render each version to a new file beside the old one (piece-v2.mp4), never over it, so earlier versions stay watchable.
• Keep the person's hand edits. Edits made in the raea app come back as props on the composition (edit segments and <Nudge> offsets). Change the composition under them.

#9. Deliver — HEADLESS

• Final exports of motion graphics and type: --quality master.
• Name files with lowercase letters, digits and hyphens only: spring-launch-9x16.mp4.
• Deliver to the workspace's controllers when they set sizes, platforms or loudness (raea controller ls).

#What an agent should never do

• Never invent a flag. raea help lists every verb and flag, and the CLI reference is generated from it.
• Never render over a previous version.
• Never call a piece done without looking at its frames and running raea check on the export.
• Never add a folder to the person's libraries or approve a storyboard on their behalf. Those wait for the person.