# Use with an agent
> Set up Claude Code, Codex or Cursor to make vawe films, and see what the agent does at each stage of the loop.
Canonical: https://vawe.dev/docs/agents
By the end of this page, an agent in a vawe checkout reads the house rules, loads the skills and follows the loop. Every command it runs is logged under its name. Install vawe first: [Install](https://vawe.dev/docs/install).
## What the agent reads
vawe keeps its rules in one file, `AGENTS.md` at the root of the checkout. Codex, Cursor and other agents read `AGENTS.md`. Claude Code reads `CLAUDE.md`, which points to `AGENTS.md`.
`AGENTS.md` holds the setup, the hard rules, the ten stages of the loop, the shell rules and an index of the docs. The skills add the detail for one task each.
## The skills
A skill is a folder in `skills/` with a `SKILL.md` file. Any agent can read a `SKILL.md`. The skills run inside a vawe checkout.
| Skill | Load it when |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| `html-to-video` | You start here: a film is asked for and none exists yet. |
| `vawe-brief` | A request has no `brief.md` yet. |
| `vawe-page` | You write or edit `page.html`. |
| `vawe-transitions` | You plan the cuts between worlds. |
| `vawe-critique` | A draft is rendered and needs a look, before any fix. A session that did not write the page does this. |
| `vawe-reference` | A reference mp4 must be matched. |
`AGENTS.md` tells the agent to read `skills//SKILL.md` before its stage, so a checkout needs no install.
### Install the skills
The skills are also published in `vawe-hq/skills`, so an install does not download the whole repository. Use one of these:
```bash
npx skills add vawe-hq/skills
claude plugin marketplace add vawe-hq/skills
claude plugin install vawe@vawe-skills
```
The first line works for any agent that the `skills` CLI supports. The other two are for Claude Code.
### Claude Code
Open Claude Code in the vawe checkout. It reads `CLAUDE.md`, which loads `AGENTS.md`. The repository does not track a `.claude/settings.json`, so each person registers the hooks in `harness/live/`.
The hook `harness/live/stage-say.mjs` runs on each prompt. It names the next command for the film you edited last. It stays silent when no page changed in the last three hours.
### Codex, Cursor and other agents
Tell the agent to read `AGENTS.md` first. Any agent that reads files and runs shell commands can follow the loop. Without a hook, each verb of `bin/vawe` prints a `next:` line that names the next stage.
## What the agent does at each stage
| Stage | The agent | The command |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Brief | Asks for the missing facts, then writes the brief. With `--defaults` it guesses and marks each guess. | `bin/vawe new --request ""` |
| Reference study | Lists the references and fills “Taken from” in `brief.md`. | `bin/vawe refs list` |
| Design system and kit | Writes `DESIGN.md` and `kit/` for the film. | none |
| States | Builds one key frame for each world. | `bin/vawe frames ` |
| Ideas, board | Fills “Ideas” and “Board” in `brief.md`, then makes the storyboard. | `bin/vawe storyboard ` |
| Draft | Renders a half-size draft with sound. `--silent` leaves the sound out. | `bin/vawe dev ` |
| Motion pass | Reads a strip of every cut and writes one “Motion pass” row for each cut. | `bin/vawe strip --cuts` |
| Critique | Runs in a fresh session that did not write the page. | `bin/vawe critique ` |
| Fix | Renders again only the seconds that the critique names. | `bin/vawe dev --from s --to s` |
| Final | Asks for a fresh judge. The owner approves. Then the agent ships and waits. | `bin/vawe judge --fresh`, `bin/vawe approve `, `bin/vawe ship `, `bin/vawe wait ` |
> The owner runs `bin/vawe approve `. The agent never runs it. `ship` refuses until a fresh review and the owner approval both exist.
The critique and the judge run in a session that did not write the page. An agent never judges its own page or records its PASS.
### Rules for the shell
`AGENTS.md` lists the mistakes that agents make in the shell:
* The shell is zsh. Quote every glob and every `?`.
* Never use `sleep`. Wait with `bin/vawe wait `.
* Never pipe `bin/vawe` into `tail`, `head` or `grep`. The pipe hides the exit code.
* Read the last line of each verb: `vawe: ok|FAILED () in s`.
Use a `bin/vawe` verb before raw `ffmpeg` or Chrome. If no verb does the job, say so in your report.
## The run log
Each verb adds one JSON line to `out/.runs.jsonl`. The line holds the time, the verb, the film, the session, the agent name, the model and the git state.
To name an agent, set two variables in the shell before the first command:
```bash
export VAWE_AGENT=writer-1
export VAWE_MODEL=
```
`VAWE_AGENT` is the only way to name an agent. A subagent shares the session id of its parent, so the session cannot tell them apart. Without `VAWE_AGENT`, the log writes the first 8 characters of the session id, a `#` and a short tag. A name with a `#` counts as unnamed.
The critique must come from another session than the author. Another `VAWE_AGENT` name in the same session does not count: `ship` refuses it. `bin/vawe runs ` shows a `critique` line with the agent that ran it.
Read the log with `vawe runs`:
```bash
bin/vawe runs hello # time, failures and the draft series of one film
bin/vawe runs --all # one row for each film of the last 30 days, then medians for each model
```
## What to read next
- []()" title="Quickstart" href="/docs/quickstart">
Make the first draft by hand.
- []()" title="The page" href="/docs/the-page">
The contract that every page obeys.
{/* sources (vawe d8481cc61):
AGENTS.md is the map, CLAUDE.md points to it, Codex and Cursor read AGENTS.md: README.md "Use it from your agent"; CLAUDE.md
skills table: the SKILL.md description of each folder in skills/; skills/html-to-video/SKILL.md "Which skill next"; AGENTS.md last line of "Shell"
read skills//SKILL.md before its stage, nothing to install: AGENTS.md "The loop"
npx skills add, claude plugin lines, vawe-hq/skills copy: README.md "Use it from your agent"
no tracked .claude/settings.json: harness/README.md "Hooks"
stage-say hook, silent after 3 hours: harness/live/stage-say.mjs header and RECENT_MS
stage table: AGENTS.md "The loop" rows 1 to 10
approve, never self-run, fresh review: AGENTS.md "Hard rules"; bin/vawe approve --help; bin/vawe ship --help
shell rules: AGENTS.md "Shell" and "Hard rules"
run log fields, VAWE_AGENT, subagent note, "#": harness/lib/runlog.mjs agentId, namedAgent, appendRun
critique from another session, a VAWE_AGENT label is not a session: harness/lib/critique-gate.mjs critiqueProblem; AGENTS.md "The proof before you say done" item 4
runs flags: bin/vawe runs --help
*/}