For agents

These are the instructions codeflix install-skill gives Claude Code. Any agent can read them here, as skill.md, or as llms.txt.

Install for Claude Code

codeflix install-skill

Install for Codex (adds to AGENTS.md in this folder)

codeflix install-skill --codex

A first prompt

Using the codeflix skill: build a 10-second Blender Cycles animation of a paper boat crossing a pond at sunset in ./my-film. Check it and preview it with Codeflix and show me the preview. Then quote the full render and wait for my go-ahead before rendering.

The instructions

---
name: codeflix
description: Render Blender Cycles animations on many cloud GPUs at once and get back an MP4 link. Use when the user wants a Blender animation rendered (especially a long one, 4K, or when the local machine has no fast GPU), says "render it with Codeflix", "render in the cloud", or "render it fast". Also covers building the project so it renders correctly on render machines.
---

# Rendering Blender films with Codeflix

Codeflix renders a Blender project's frames on many GPUs at the same time and returns a video
link. You build the scene locally; Codeflix does the rendering, retries and encoding.
You drive it with the `codeflix` command. Every command prints at most 12 `key: value` lines,
blocks until it has an answer, and uses exit codes you can act on.

## When to use it

- The final render of an animation: hundreds or thousands of frames, or 4K, or anything that
  would take more than a few minutes on this machine.
- Not for a single still or a quick look while modelling: render that locally.
- Cycles only. EEVEE scenes must be switched to Cycles first.

## The workflow

1. **Build the project** in a folder of its own, by Python script with Blender if you are
   generating it. Save the `.blend` at the top of that folder.
2. **Check it:** `codeflix check ./film`. Fix whatever it reports (see Errors) and run it again.
   It is free and takes seconds.
3. **Preview it:** `codeflix preview ./film`. It prints the path of one image with the middle
   frame of every shot. Open that image and look at it yourself, then show the user. Fix
   framing, lighting or timing and preview again until it is right. Previews are free.
4. **Quote it:** `codeflix quote ./film`. It renders three real frames and prints the price
   and time for the whole film, plus a suggested cap.
5. **Get approval for the spend** if the user has not given you a budget. Show the quote.
6. **Render:** `codeflix render ./film --max-spend <usd>`. It never spends more than the cap.
7. **Deliver:** give the user the `video:` link, or `codeflix pull <job>` to download the MP4
   into `./film/.codeflix/`. Add `--frames` to get every frame for your own finishing steps.

Running the same command again with an unchanged folder returns the same job; it does not
charge twice. After you change the project, the next command starts a new job.

## Making a project render correctly on render machines

Frames render out of order, on different machines that only have what is in the folder.

- One `.blend` at the top level of the folder. Other `.blend` files go in subfolders.
- Every texture, image sequence, HDRI and cache inside the folder, referenced by **relative**
  path. Before saving: `bpy.ops.file.make_paths_relative()`.
- Render engine Cycles: `scene.render.engine = 'CYCLES'`. Save with Blender 5.0 or 5.2.
- Bake simulations (cloth, rigid bodies, particles, fluids, geometry-node simulations) with
  their caches inside the folder: `bpy.ops.ptcache.bake_all(bake=True)` for point caches.
- Animation must come from keyframes or baked data. Python drivers and startup scripts do
  **not** run on render machines.
- Use cameras bound to timeline markers for cuts; the preview picks one frame per shot from them.
- A long image sequence used as a texture uploads faster as one movie file.
- Resolution, samples, frame range and output format come from the file. You can override
  `--frames A-B`, `--scale PERCENT` and `--samples N` on the command line.
- Up to 4K, 20,000 frames and 5 GB per project.

## Waiting

`render` and `quote` wait up to 9 minutes by default (`--wait 540`). Run them with a 10-minute
tool timeout, or in the background. If the job is still going, the command exits with code 4
and prints `wait: codeflix wait <job>`. Run that; it waits for you. Never write your own
polling loop.

## Exit codes

| Code | Meaning | What to do |
|---|---|---|
| 0 | done | use the result |
| 1 | cancelled | nothing |
| 2 | the project needs a fix | read `error:` and `fix:`, change the project, run again |
| 3 | spending cap or credit | raise `--max-spend`, or give the user the top-up link printed |
| 4 | still running | run the printed `codeflix wait <job>` |
| 5 | our fault, not charged | run the same command again |

## Errors you will see, and the fix

| Error | Fix |
|---|---|
| `E_NO_BLEND` / `E_MULTI_BLEND` | exactly one `.blend` at the top of the folder |
| `E_MISSING_FILES` | copy the listed files into the folder, `make_paths_relative()`, save |
| `E_OUTSIDE_PATHS` | same: files outside the folder or absolute paths |
| `E_UNBAKED_SIM` | bake the listed simulations into the folder, save |
| `E_ENGINE` | switch to Cycles |
| `E_VERSION` | save with Blender 5.0 or 5.2 |
| `E_GPU_MEMORY` | smaller textures or less geometry, or `--scale` |
| `E_FRAME_FAILED` | `codeflix logs <job> --frame N` shows Blender's own error |
| `E_OVER_CAP` | the message says the price; raise `--max-spend` or lower `--samples`/`--scale` |
| `E_NO_CREDIT` | give the user the top-up link from the `fix:` line |

## Money

- `codeflix balance` shows the credit left and a top-up link for the user.
- You pay only for the seconds GPUs spend rendering frames. Checks, previews and quotes are
  free (up to 20 previews a day). A final render costs at least $0.50.
- If a job fails because of us, it is not charged.

## Other commands

`codeflix status <job>`, `codeflix cancel <job>` (finished frames are kept and paid for),
`codeflix logs <job> [--frame N]`, and `--json` on any command for the same fields as JSON.