Claude Code con Blender: scripts Python paso a paso

Qué aporta Claude Code frente a un chat

Claude Code es el agente de programación de Anthropic que funciona en la terminal. A diferencia de un chat, trabaja dentro de una carpeta: lee los archivos que necesita, propone cambios y puede ejecutar comandos. Para Blender, eso significa que puede escribir un script de Python que use la API bpy, lanzarlo con Blender y leer el error si algo falla.

Ese acceso es útil y también exige cuidado. Claude Code te pide permiso antes de ciertas acciones según el modo de permisos de la sesión, que puedes cambiar con Shift+Tab. Al empezar, mantén el modo que pregunta antes de editar archivos o ejecutar comandos. Así ves cada paso y decides si se aplica.

Lo que obtienes no es un vídeo generado, sino un archivo de Blender con objetos, materiales y fotogramas clave que puedes editar a mano después. Si ya conoces el flujo general de trabajar con IA en Blender, este tutorial se centra en la parte práctica de la terminal.

1. Prepara una carpeta de proyecto y una copia del .blend

Crea una carpeta solo para este ejercicio. Dentro, coloca una copia del archivo .blend y una subcarpeta para los scripts. Claude Code trabaja sobre la carpeta desde la que lo abres, así que no lo inicies en tu carpeta personal ni en la de todos tus proyectos.

Comprueba también que puedes lanzar Blender desde la terminal. En macOS, el ejecutable está dentro del paquete de la aplicación, en /Applications/Blender.app/Contents/MacOS/Blender. En Windows, con el instalador, suele estar en C:\Program Files\Blender Foundation\Blender\blender.exe. Si la ruta de tu instalación es otra, anótala: tendrás que dársela a Claude Code.

1. Crea una carpeta, por ejemplo pap-claude-blender, con una subcarpeta scripts.
2. Copia dentro el .blend con el que vas a practicar y renómbralo como escena_base.blend.
3. Ejecuta Blender con --version para confirmar la ruta y la versión.
4. Si usas Git, inicia un repositorio para guardar los scripts y poder comparar cambios.
5. Abre la terminal en la carpeta y escribe claude para iniciar la sesión.

cd pap-claude-blender
/Applications/Blender.app/Contents/MacOS/Blender --version
claude

2. Deja las reglas del proyecto en CLAUDE.md

Claude Code lee un archivo CLAUDE.md de la raíz del proyecto al empezar cada sesión. Es el lugar adecuado para fijar la versión de Blender, la ruta del ejecutable y lo que no debe hacer. El comando /init puede generar una primera versión, aunque en una carpeta casi vacía tendrás que escribir tú casi todo.

Ten en cuenta que estas instrucciones son contexto, no un bloqueo técnico: Claude las sigue mejor cuanto más concretas sean, pero no sustituyen a tu revisión. Escríbelas cortas y comprobables.

# Proyecto Blender
- Blender 4.5 LTS en /Applications/Blender.app/Contents/MacOS/Blender
- Los scripts van en scripts/ y usan solo bpy y la biblioteca estándar.
- Nunca sobrescribas escena_base.blend. Guarda el resultado en salida/ con otro nombre.
- No instales paquetes ni borres archivos sin preguntar.
- Ejecuta Blender siempre con --background y --python-exit-code 1.

3. Pide un cambio pequeño y con nombres concretos

Empieza por algo que puedas verificar en un minuto: crear cuatro cubos con nombres fijos, animar la posición de un objeto entre dos fotogramas o ajustar la resolución de render. Indica los nombres de los objetos, los fotogramas y lo que debe quedar intacto. Pide que explique el plan antes de escribir el código.

Una petición abierta como «mejora la escena» obliga al agente a adivinar. Una petición acotada produce un script corto que puedes leer entero. Si el resultado es bueno, pide el siguiente cambio en otra iteración en lugar de ampliar el primero.

Lee scripts/ y CLAUDE.md. Quiero un script scripts/despiece.py que:
- trabaje sobre la escena activa del .blend que abra Blender,
- anime PAP_Capa_4 en Z: posición actual en el frame 1 y +2 unidades en el frame 90,
- no toque cámara, luces ni materiales,
- guarde el resultado en salida/despiece_v1.blend.
Antes de escribirlo, explícame qué vas a hacer. Después ejecútalo en modo background
y dime qué objetos han cambiado.

El prompt orienta el trabajo, pero no garantiza que el código sea correcto. Lee el script antes de aprobar su ejecución.

4. Ejecuta el script en modo background

La opción --background (o -b) ejecuta Blender sin interfaz, y --python (o -P) ejecuta un archivo de Python. El orden importa: Blender procesa los argumentos en el orden en que aparecen, así que primero va el .blend que quieres abrir y después el script. Con --python-exit-code 1, Blender termina con un código de error si el script lanza una excepción, lo que permite a Claude Code detectar el fallo en lugar de dar el trabajo por terminado.

Todo lo que pongas después de dos guiones (--) llega intacto al script a través de sys.argv. Es una forma limpia de pasar la ruta de salida sin escribirla dentro del código. En modo background los cambios no se guardan solos: el script debe guardar el archivo de forma explícita, y conviene que lo haga con un nombre nuevo.

blender --background escena_base.blend \
  --python-exit-code 1 \
  --python scripts/despiece.py \
  -- salida/despiece_v1.blend

# Dentro del script, al final:
# import sys
# ruta = sys.argv[sys.argv.index("--") + 1]
# bpy.ops.wm.save_as_mainfile(filepath=ruta)

Sustituye blender por la ruta completa del ejecutable si no lo tienes en el PATH.

5. Revisa el código, el archivo y la imagen

Que el comando termine sin errores solo indica que el script se ejecutó. Abre salida/despiece_v1.blend en Blender y comprueba los fotogramas 1, 45 y 90. Mira el Outliner por si aparecen objetos nuevos o duplicados. Si usas Git, pide a Claude Code que te muestre el diff del script: así revisas qué líneas cambiaron entre una versión y otra.

Para una comprobación visual rápida, puedes renderizar un único fotograma también desde la terminal. Coloca la ruta de salida antes de la orden de render, porque Blender ejecuta los argumentos en orden. Cuando algo falle, copia el mensaje de error exacto y pide una corrección localizada en vez de regenerar todo el script.

Con el tiempo acabarás repitiendo las mismas instrucciones: nombres, comprobaciones, formatos de salida. En Pieza a Pieza reunimos las skills que usamos en el canal en un kit, por si prefieres partir de ellas en lugar de escribirlas desde cero.

1. Lee el script completo antes de aprobar su ejecución.
2. Abre el archivo de salida y revisa los extremos y una pose intermedia.
3. Renderiza un fotograma de prueba y míralo al tamaño final.
4. Guarda la versión que funciona antes de pedir el siguiente cambio.

blender -b salida/despiece_v1.blend -o //render/prueba_ -f 90