oxframe

Working with AI agents

Coding agents like Claude Code, Codex or Cursor can write oxframe scenes for you. Every new project comes with instructions that teach them how — and a way for them to see what they made.

What oxframe init adds

AGENTS.mdThe project's rules for any agent: how scenes work, which commands to run, what never to do (non-deterministic code, editing meta.json by hand) and fixes for the most common compile errors.
CLAUDE.mdOne line, @AGENTS.md, so Claude Code reads the same file.
.claude/skills/oxframe/A skill with a step-by-step workflow (SKILL.md) and an API cheat sheet (reference.md). Agents that support skills load it whenever you ask for a change to a scene.

The files are plain Markdown. Read them, edit them, add your own project conventions.

Letting the agent see its work

Animation is visual, so compiling is not enough to know a change is right. The instructions tell the agent to check itself with snapshots:

oxframe check                          # does it compile?
oxframe snapshot --at 0.5 --at 2       # render those moments as PNG
cargo run -q -- info                   # scene lengths and marker times as JSON

snapshot prints one path per image, the agent opens the PNGs and compares them with what you asked for. No editor, no ffmpeg, nothing that keeps running — oxframe dev is for you, not for the agent.

A good way to work together

  1. Keep oxframe dev open in your browser.
  2. Ask the agent for a change in plain words: "after the title, slide three cards in from the left, one after another".
  3. The agent edits the code and checks it with snapshots; your preview reloads by itself.
  4. Fine-tune timing yourself with markers and sliders. The agent is told to keep your meta.json values, so your adjustments survive its next edit.

Keeping the files up to date

After upgrading oxframe, refresh the instructions:

oxframe agents          # refreshes the generated files
oxframe agents --force  # also replaces files you made your own

Generated files carry an oxframe-agents marker comment. To keep your own version of a file, delete that comment — files without it are left alone. Projects created with an older CLI can get the files the same way.

For tools that read the web

This documentation is also available as plain text for language models at /llms.txt.