Cómo empezar a automatizar Revit 2027 con Claude Code: pyRevit primero, C# después

Resumen

Conclusiones

• Claude Code ya programa bien contra la API de Revit 2027. En 24 sesiones (12 tareas, en C# y en pyRevit 7) resolvió todas, sin inventar ningún método de la API.
• Para empezar, pyRevit 7 con su runtime de agente. No compila, no reinicia Revit y no pide aceptar avisos de seguridad. C# es igual de capaz y ~27 % más barato en tareas sobre el modelo, pero antes hay que construirle un sistema para probar sin reiniciar Revit.
• Lo que decide el resultado no es el lenguaje, sino que Claude pueda ejecutar dentro de Revit y ver qué pasó. Los fallos vienen de Revit en ejecución, no del código.

Lo clave

• Dynamo, pyRevit, las macros y los servidores MCP usan la misma API .NET y heredan sus reglas: Revit abierto con licencia, un solo hilo y nada sin interfaz en escritorio.
• Crear un botón en la cinta: 0,7 min en pyRevit, 5,8 en C#. Cambiar el código sin reiniciar: 2,3 min frente a 8,3. Personas necesitadas: 0 frente a 3.
• pyRevit no deja guardar desde un script (8 de 8 sesiones que guardaban). Solución: PostCommand(Save), que se ejecuta al terminar el script.
• IronPython 2.7 tropieza con .Name de tipos y familias, ElementId(int) y las tildes. Cuatro líneas en el CLAUDE.md lo evitan.
• 20 de 201 operaciones probadas no tienen API: fases, opciones de diseño, scope boxes, familias in situ, campos calculados, render.
• Un aviso de Revit congela la API hasta que alguien lo cierra. El runtime de pyRevit los devuelve como datos; en C# hay que interceptarlos con Application.FailuresProcessing.

Recomendaciones

1. Instala pyRevit 7 por usuario, activa su runtime de agente y registra su servidor MCP en Claude Code.
2. Copia el CLAUDE.md para pyRevit: cómo guardar, las rarezas de IronPython y lo que no tiene API.
3. Antes de prometer una automatización, revisa los límites de la API.
4. Pasa a C# cuando el add-in se vaya a distribuir o mantener, y monta antes un bucle sin reinicios.

---

1. Qué estás programando en realidad

Toda automatización de escritorio en Revit, sea en pyRevit, Dynamo, una macro o un MCP, termina en la API .NET de Revit. Las herramientas cambian el lenguaje y la comodidad, no lo que se puede hacer:

• Revit tiene que estar abierto y con licencia. No hay modo sin interfaz en escritorio; sin interfaz, solo en la nube con APS Automation API (según la documentación, no se probó).
• Todo corre en el hilo principal de Revit y en un contexto válido: un comando, un evento o un ExternalEvent. Después de un await, el código queda fuera de contexto.
• Lo que la API no permite, ninguna herramienta lo permite.

Por eso el primer paso no es elegir el lenguaje: es saber qué no se puede.

2. Lo que Revit no deja hacer por código

De 201 operaciones probadas en Revit 2027.1, 20 no tienen API:

• Crear fases, opciones de diseño, scope boxes o familias in situ.
• Crear una leyenda o un esquema de color desde cero (sí duplicar uno de la plantilla).
• Crear campos calculados en tablas.
• Renderizar, escribir en la barra de estado o asignar atajos de teclado.
• Cambiar las unidades por defecto de Revit o las rutas de las plantillas.
• Escribir los datos de carbono incorporado de un material.
• Abrir un RVT fuera de Revit: solo se leen sus metadatos (BasicFileInfo) y la vista previa.

Otras 47 funcionan con condiciones. Están en los límites de la API y en el checklist de las 206 pruebas.

3. Elige el stack: pyRevit para empezar

Las mismas 12 tareas, de un muro recto a una escalera en U, se resolvieron con los dos stacks en sesiones nuevas de Claude Code. Las decidió un verificador que lee el modelo, no la IA.

• Tareas sobre el modelo (muros, parámetros, planos, puertas, tablas, cotas, familias, escaleras): empate en tiempo (16,8 min en C#, 18,3 en pyRevit). C# más barato: 4,44 USD frente a 6,10, porque pyRevit lleva más contexto en cada turno y necesita más llamadas. C# no falló ninguna de sus 27 compilaciones.
• Tareas de entorno, donde pyRevit gana con claridad:
  • Botón en la cinta: 0,7 min frente a 5,8. En C#, Claude tuvo que instalar un manifiesto y reiniciar Revit, y una persona aceptó el aviso de add-in sin firma.
  • Cambiar el código sin reiniciar: 2,3 min frente a 8,3. pyRevit vuelve a leer el script en cada clic. En C#, Claude tuvo que construir un cargador que compila con Roslyn dentro de Revit.
• Ciclo por iteración: 0,16 s en pyRevit; en C#, 1,1 s de compilar más 0,7 s de ejecutar, y solo porque había un runner (sin él, reiniciar Revit cuesta 37 s).

La tabla completa está en C# frente a pyRevit.

4. Prepara pyRevit 7 con Claude Code

1. Instala pyRevit 7 con el instalador por usuario. Según los issues #3302 y #3441, el de administrador deja Revit 2027 sin cinta (no se probó).

2. Activa el runtime de agente:

   pyrevit configs agent enable
   pyrevit configs agent policy auto
   

   Con ask, cada cambio al modelo espera un clic tuyo. Con auto, Claude modifica el modelo solo: úsalo únicamente con modelos de prueba.

3. Registra el servidor MCP en la carpeta de tu proyecto: pyrevit mcp install claude --project. Claude Code pedirá aprobarlo al abrir la sesión. Desde ahí, Claude ejecuta Python dentro de Revit (run_query para leer, run_modify para cambiar) y consulta la API con lookup_revit_api.

4. Registra una carpeta para tus herramientas: pyrevit extensions paths add <carpeta>. Los botones que cree Claude aparecen ahí sin reiniciar Revit.

pyRevit 7.0.0.26278 convivió con Dynamo 4.0.2 (un nodo Python con PythonNet3 siguió funcionando) y con otros add-ins. Su cargador está compilado para Revit 2025: Revit 2027 anota un conflicto de versiones en el journal, pero lo carga.

5. Lo que tienes que decirle a Claude

Casi todos los fallos de pyRevit se repitieron entre sesiones y se evitan escribiéndolos en el CLAUDE.md. La plantilla ya los trae:

• Guardar: doc.Save() falla dentro del runtime («Saving is not permitted when there is any open transaction phase started by API client»). Se guarda con uiapp.PostCommand(RevitCommandId.LookupPostableCommandId(PostableCommand.Save)), que corre al terminar el script.
• Transacciones: en run_modify, el script abre su propia Transaction.
• IronPython 2.7:
  • Element.Name.GetValue(tipo) en vez de tipo.Name;
  • ElementId(System.Int64(n)) en vez de ElementId(n);
  • .Value en vez de IntegerValue, que ya no existe en 2027;
  • # -*- coding: utf-8 -*- si el archivo lleva tildes.
• Por etapas: el único crash de pyRevit salió de un script que lo hacía todo de una vez. Claude lo rehízo en pasos y funcionó.

6. Las trampas de Revit, en cualquier stack

Estas no dependen del lenguaje: solo aparecen ejecutando.

• Un aviso bloquea la API. Dos muros superpuestos abren un diálogo que congela todo hasta que alguien lo cierra (146 s en la prueba). El runtime de pyRevit devuelve los avisos en failures. En C# se interceptan con Application.FailuresProcessing desde el primer día.
• Fallos silenciosos. Exportar a DGN devuelve false sin explicación. Vincular un RVT que está abierto no hace nada, y lo mismo pasa al registrar un panel acoplable fuera del arranque.
• Revit crea cosas solo. Una escalera por componentes ya trae barandillas, y crearlas encima falla.
• Las operaciones largas congelan Revit. Procesar la interfaz cada tanto permite mostrar progreso y cancelar, a cambio de un 27 % de velocidad.
• Guardar en bucle en una carpeta vigilada tumba Revit. Dentro de un repositorio o de una carpeta que mira Visual Studio cae a los 8–9 ciclos; en otra carpeta aguantó 120. El archivo que se guardaba quedó corrupto. Guarda los modelos de prueba fuera de esas carpetas y verifica cada archivo.
• Lo que exportas sigue el tema de Revit. Con el tema oscuro, las imágenes salen con fondo oscuro; los PDF no.
• El journal de Revit es la mejor documentación. Está en %LOCALAPPDATA%\Autodesk\Revit\Autodesk Revit 2027\Journals y registra lo que la API no dice.

7. Cuándo pasar a C#

C# compensa cuando el add-in se va a distribuir o mantener, o cuando el coste por tarea importa: tiene tipos que atrapan errores antes de ejecutar y la API completa, sin la capa de IronPython. Lo que necesitas para que Claude rinda igual:

1. Un runner. Es un add-in fijo que carga cada compilación en un AssemblyLoadContext descartable y recibe órdenes por un canal local. Así Claude prueba en ~4 s, de guardar a ver el resultado, sin reiniciar Revit. El Hot Reload de Visual Studio no sirve: Revit lo trae desactivado.
2. Un inventario de la API sacado por reflexión de RevitAPI.dll y RevitAPIUI.dll, que Claude consulta antes de usar un nombre. Con él, en todo el laboratorio hubo una sola API inventada, en 6.777 líneas, y la detectó el compilador.
3. net10.0-windows y el manifiesto en %APPDATA%\Autodesk\Revit\Addins\2027. En 2027, la carpeta de ProgramData se ignora sin aviso. Para todos los usuarios, la ruta es C:\Program Files\Autodesk\Revit\Addins\2027.
4. Aislamiento de dependencias. Con UseRevitContext="False", el add-in puede usar su propia versión de una librería (si no, gana la Newtonsoft de Revit). Compartir librerías entre add-ins aislados tiene tres trampas; hay dos manifiestos de ejemplo: el que comparte y el que usa.

Los add-ins compilados para 2024 y 2026 cargaron en 2027. Para procesar modelos en lote sin nube, un journal abre el modelo, ejecuta tu comando y cierra Revit (29 s). Con dos Revit a la vez, el rendimiento sube ×1,5.

Cómo se midió y qué no

• Probado en Revit 2027.1 (build 27.1.0.45, .NET 10, licencia educativa): 201 de 206 pruebas de la API .NET y la comparación de C# con pyRevit 7.0.0.26278, en 24 sesiones de Claude Code (claude-opus-5-5, esfuerzo high), con verificador independiente.
• No probado: Dynamo como herramienta de automatización (solo se comprobó que convive con pyRevit), macros, servidores MCP de terceros, APS y pyRevit sin su runtime de agente o con CPython. Tampoco cuánto empeora Claude sin runner ni inventario.
• Límites: 12 tareas son una muestra indicativa, no estadística. El C# medido llevaba runner e inventario. El runtime de agente de pyRevit es experimental y puede cambiar, sobre todo el bloqueo al guardar.

Material de libre uso

• CLAUDE.md para pyRevit: la plantilla para empezar.
• C# frente a pyRevit: las 12 tareas, tarea por tarea.
• Límites de la API de Revit 2027: lo que no se puede, lo que se puede con condiciones y lo que funcionó mejor de lo esperado.
• Checklist de las 206 pruebas, cada una con su resultado.
• Resumen de métricas de la IA y métricas detalladas del laboratorio en C#.
• Ejemplos: journal para lotes y los dos manifiestos con aislamiento (proveedor, dependiente).