====== Orca ====== [[https://www.onorca.dev|Orca]] es un **entorno para trabajar con varios agentes a la vez**: cada tarea en su worktree de Git, con su agente, y en la misma ventana el diff de lo que ha hecho, un editor y un navegador. No trae modelo propio: ejecuta los agentes que ya usas (Claude Code, OpenCode, Codex...) con tu suscripción. Es gratis y de código abierto. Hace lo mismo que [[cursos:sdd:03-herdr|herdr]] (varios agentes a la vista y aviso de cuál te necesita) y le suma lo que hace falta para **revisar** lo que hacen los agentes: comentar su diff línea a línea, ver la web que están haciendo y señalarles el elemento que está mal. ^ ^ herdr ^ Orca ^ IDE ^ | Varios agentes a la vista con su estado | ✓ | ✓ | | | Un worktree por agente | ✓ | ✓ | | | Revisar y comentar el diff del agente | | ✓ | | | Navegador para señalar elementos | | ✓ | | | Contestar al agente desde el móvil | | ✓ | | | Editor de código | | ✓ | ✓ | | Depurador, refactorizaciones, extensiones | | | ✓ | ---- ===== 1. Puesta en marcha ===== ==== Instalar ==== * Linux: el AppImage, que se actualiza solo. wget https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage chmod +x orca-linux.AppImage ./orca-linux.AppImage * macOS brew install --cask stablyai/orca/orca * Windows: ''orca-windows-setup.exe'' de la [[https://github.com/stablyai/orca/releases/latest|última versión]]. Si el AppImage no arranca en Ubuntu, le falta FUSE: ''sudo apt install libfuse2''. ==== Primer arranque ==== Pide acceso a tu carpeta personal, para poder añadir repositorios, y ofrece importar la configuración de ''~/.claude'' y ''~/.codex''. Di que sí a las dos cosas. 📷 **Captura pendiente** ''orca-primer-arranque.png'': la pregunta de acceso a la carpeta personal y de importar ''~/.claude''. ==== Los permisos del agente ==== Orca lanza los agentes **con todos los permisos**: a Claude Code le añade ''--dangerously-skip-permissions'', así que no te pregunta antes de ejecutar órdenes ni de tocar ficheros. Si no lo quieres, en **Settings → Agents** se despliega el agente y se borra el parámetro de sus //launch arguments//. **Reset** lo vuelve a dejar como venía. 📷 **Captura pendiente** ''orca-permisos-agente.png'': //Settings → Agents// con los //launch arguments// de Claude Code desplegados. En la misma pantalla se elige el **agente por defecto**, el que se lanza al crear cada worktree. ==== Actualizar ==== Se actualiza solo. Con ''brew'', ''brew upgrade --cask orca''. ---- ===== 2. Repositorios, worktrees, pestañas y paneles ===== Orca organiza el trabajo en cuatro niveles: ^ Nivel ^ Qué es ^ Para qué se usa ^ | **Repositorio** | Un repositorio Git de tu disco | Uno por proyecto | | **Worktree** | Un worktree de Git del repositorio, con su rama | Uno por tarea o por spec, con su agente | | **Pestaña** | Una sola cosa: una terminal, un fichero, el navegador, un diff o una PR | Lo que necesitas de esa tarea | | **Panel** | Un trozo de la ventana en el que se ven pestañas **a la vez** | El agente a un lado y su diff o su web al otro | Comparado con [[cursos:sdd:03-herdr#espacios_de_trabajo_pestanas_y_paneles|herdr]]: el worktree hace el papel del espacio de trabajo, y en Orca **todo worktree es un worktree de Git**. Trabajar sin rama propia es usar el worktree principal del repositorio. 📷 **Captura pendiente** ''orca-niveles.png'': la ventana entera con el repositorio, un worktree, las pestañas y dos paneles señalados. Los ejemplos son dos proyectos: ''reservas-api'' (una API REST) y ''tienda-web'' (su web). ==== Añadir un repositorio ==== Se pulsa **Add Repo** en la barra lateral y se elige la carpeta del repositorio. Orca toma la rama por defecto (''main'') como //base ref//: de ahí salen los worktrees nuevos. 📷 **Captura pendiente** ''orca-add-repo-1.png'': el botón **Add Repo**, con círculo rojo. 📷 **Captura pendiente** ''orca-add-repo-2.png'': ''reservas-api'' ya en la barra lateral. ==== Worktree nuevo ==== Se pulsa el **''+''** junto al nombre del repositorio y se rellena: * **Nombre**: el de la tarea, que es también el de la rama. Aquí, ''login''. * **Start from**: de dónde sale la rama. Lo normal, ''origin/main''. * **Agent**: el agente que se lanza en el worktree. Orca crea la rama y el worktree y abre el agente en su carpeta. 📷 **Captura pendiente** ''orca-worktree-nuevo-1.png'': el ''+'' junto a ''reservas-api'', con círculo rojo. 📷 **Captura pendiente** ''orca-worktree-nuevo-2.png'': el diálogo con el nombre ''login'', //start from// ''origin/main'' y el agente. El agente se lanza **desde el desplegable**, no escribiendo ''claude'' en la terminal. Si lo lanzas a mano, Orca no sabe en qué estado está y no te avisa cuando te necesita. El worktree se renombra con **doble clic** sobre su nombre. ==== Lo que no está en Git ==== El worktree es una carpeta nueva con lo que hay en Git, así que **no tiene ni el ''.env'' ni ''node_modules''**: el agente arranca, los tests fallan y no sabe por qué. Se arregla en el repositorio principal: * ''.worktreeinclude'': ficheros que se **copian** a cada worktree nuevo, uno por línea. .env * ''orca.yaml'': carpetas que se **comparten** entre todos los worktrees, sin copiarlas. worktree: sharedDirectories: - node_modules Los dos solo valen para ficheros y carpetas que estén en el ''.gitignore''. ==== Paneles ==== Para ver dos pestañas a la vez se **arrastra una pestaña al borde** del panel: al borde derecho, se ponen una al lado de la otra; al de abajo, una encima de la otra. En una terminal también vale botón derecho sobre la pestaña → **Split terminal right** o **Split terminal down**. 📷 **Captura pendiente** ''orca-panel-dividir-1.png'': la pestaña arrastrada hasta el borde derecho, con círculo rojo. 📷 **Captura pendiente** ''orca-panel-dividir-2.png'': el agente a la izquierda y su diff a la derecha. Cada worktree guarda su distribución de paneles. ==== Borrar un worktree ==== Botón derecho sobre el worktree → **Delete**. Borrar un worktree borra **la carpeta y también la rama**. Si la rama tiene trabajo que no has subido ni fusionado, Orca la conserva y te avisa, pero lo que no esté en un commit se pierde. Antes de borrar, haz commit y push de lo que quieras guardar. 📷 **Captura pendiente** ''orca-worktree-borrar.png'': el aviso al borrar un worktree, donde dice que se borra la rama. ---- ===== 3. Usando Orca ===== ==== El estado de cada agente ==== En la barra lateral, cada worktree lleva el estado de su agente: ^ Marca ^ Estado ^ Qué haces tú ^ | Gira | Trabajando | Nada, déjalo | | ? Interrogación ámbar | Te espera: un permiso, una pregunta, una decisión | **Ir a contestarle** | | ● Punto esmeralda | Ha terminado | Revisar el resultado | | ● Punto rojo | Bloqueado, interrumpido o con error | Mirar qué ha pasado | | ● Punto gris | Parado | Darle la siguiente tarea | Los worktrees en **negrita** tienen algo que no has visto. Para ir a uno, clic en él, o ''Ctrl+J'' y escribir parte de su nombre. 📷 **Captura pendiente** ''orca-estados.png'': la barra lateral con worktrees en varios estados, uno esperando respuesta. Que haya terminado **no quiere decir que haya hecho bien el trabajo**, solo que ha vuelto al prompt. Antes de darle la siguiente tarea, mira su diff ([[#revisar_el_trabajo_del_agente|sección 5]]). ==== Los avisos ==== Cuando un agente termina, Orca saca una notificación del sistema y suena. La **campana** de arriba guarda los avisos de todos los worktrees: clic en uno y estás en el panel de ese agente. Se ajustan en **Settings → Notifications**. 📷 **Captura pendiente** ''orca-campana.png'': la campana con la lista de avisos desplegada. ==== Cerrar Orca ==== Los agentes corren en un **proceso aparte**, así que se puede cerrar la ventana cuando quieras: siguen trabajando y, al abrir Orca, todo está como lo dejaste, incluida la salida que han escrito mientras tanto. Si reinicias el ordenador vuelven los worktrees, las pestañas y los paneles, pero los agentes hay que lanzarlos otra vez. ---- ===== 4. Orca en el móvil ===== La app de Orca para el móvil sirve para lo que más tiempo hace perder con los agentes: **el agente te pregunta algo cuando no estás delante y se queda parado hasta que vuelves**. Con la app te llega el aviso y le contestas desde el móvil. No es un editor: es un mando a distancia del Orca de tu ordenador. ==== Instalar en Android ==== - En el móvil, con Chrome, abrir [[https://www.onorca.dev/download/android|onorca.dev/download/android]] y bajar el APK. - Abrir ''app-release.apk'' desde las descargas. - Android pide permiso para instalar apps desconocidas: dárselo solo a Chrome y **quitárselo después de instalar**. En los Samsung, el **Auto Blocker** impide la instalación. Se desactiva en //Ajustes → Seguridad y privacidad → Auto Blocker//, se instala y se vuelve a activar. En iPhone está en la App Store como //Orca IDE//. ==== Emparejar el móvil con el ordenador ==== - En el Orca del ordenador, abrir el emparejamiento desde el menú de la cuenta: sale un código de un solo uso, que caduca en unos minutos. - En la app, **Pair** y pegar el código. La conexión va por el servidor de Orca (//Relay//), así que funciona fuera de casa. Hay que tener sesión iniciada en Orca **con la misma cuenta** en el móvil y en el ordenador. 📷 **Captura pendiente** ''orca-movil-emparejar.png'': el código de emparejamiento en el Orca del ordenador. ==== Qué se hace desde el móvil ==== * **Ver los agentes**: todos los worktrees con su estado, igual que en la barra lateral. * **Recibir el aviso**: una notificación cuando un agente termina. * **Contestar al agente**: un texto, una respuesta dictada o una foto, y aceptar los permisos que pide. * **Leer su terminal**: lo último que ha escrito, para saber qué ha hecho antes de contestarle. 📷 **Captura pendiente** ''orca-movil-agentes.png'': la app con la lista de agentes y uno esperando respuesta. 📷 **Captura pendiente** ''orca-movil-responder.png'': contestando desde el móvil a la pregunta del agente. El móvil habla con el Orca **del ordenador**: si cierras la aplicación o el ordenador se suspende, el móvil se queda sin nada. Si vas a dejar trabajando a los agentes, que el ordenador no se suspenda. Y las dos partes tienen que estar actualizadas: con versiones que no casan, la app no se conecta hasta que se actualizan las dos. ---- ===== 5. Revisar el trabajo del agente ===== Es lo que Orca añade a herdr. Cada worktree tiene su **diff**: lo que ha cambiado el agente respecto a la rama de la que salió. ==== Comentar el diff ==== - Sobre la línea, clic en el **''+''** del margen o, con el cursor en ella, la tecla ''c''. Para varias líneas, se arrastra por encima. - Se escribe el comentario y ''Enter'' para guardarlo. - Cuando están todos, **Send to agent**, arriba en el diff, y se elige el agente. Orca junta todos los comentarios en un único prompt, cada uno con su fichero y su línea, y el agente los corrige de una vez. 📷 **Captura pendiente** ''orca-diff-comentar-1.png'': el ''+'' en el margen de una línea del diff, con círculo rojo. 📷 **Captura pendiente** ''orca-diff-comentar-2.png'': el comentario escrito sobre esa línea. 📷 **Captura pendiente** ''orca-diff-enviar.png'': **Send to agent** con el menú //Send notes to// desplegado. Repasa el diff entero y manda todos los comentarios juntos, no uno a uno: el agente hace una sola pasada coherente en vez de ir parcheando. Los comentarios se quedan en su línea para comprobar el arreglo. **Resolve** cierra los que ya están bien; los que no cierres se vuelven a mandar la próxima vez. ==== Commit, push y PR ==== En el panel **Source Control** del worktree: * **Commit**: se escribe el mensaje, o **Generate with AI** lo redacta a partir de los cambios. ''Ctrl+Enter'' hace el commit. * **Push**: sube la rama a ''origin''. * **PR**: tras el push, se abre la PR desde el mismo panel; **Generate pull request details with AI** rellena el título y la descripción. Si falla un hook de pre-commit, **Fix with AI** le pasa la salida al agente para que lo arregle. ---- ===== 6. Editor ===== Los ficheros se abren en un editor como el de VS Code, con autoguardado, para retocar algo sin salir de Orca: * ''Ctrl+P'': abrir un fichero del worktree por su nombre. * Los ''.md'' se ven ya formateados: es lo cómodo para leer el ''requirements.md'' o el ''design.md'' de una spec mientras el agente trabaja al lado. * Arrastrar un fichero o una imagen al prompt del agente se lo pasa como contexto. 📷 **Captura pendiente** ''orca-editor.png'': un ''design.md'' formateado en un panel y el agente en el otro. ---- ===== 7. Navegador y Design Mode ===== Cada worktree tiene su propio **navegador**, en una pestaña más, para ver la web que está haciendo su agente. Con **Design Mode** se le señala al agente qué elemento hay que cambiar, en vez de describírselo: - En la barra del navegador, el botón de **Design Mode**. - Clic en el elemento que está mal. - Escribir qué hay que cambiar y mandarlo. Al agente le llegan el HTML del elemento, sus estilos calculados, un recorte de pantalla y, si la web corre en modo desarrollo, el fichero y la línea de donde sale. Por ejemplo, en ''tienda-web'', clic en el botón de //Comprar// que se sale de la tarjeta en móvil y «que no se salga de la tarjeta por debajo de 400px». 📷 **Captura pendiente** ''orca-design-mode-1.png'': el botón de Design Mode en la barra del navegador, con círculo rojo. 📷 **Captura pendiente** ''orca-design-mode-2.png'': el botón de //Comprar// de ''tienda-web'' resaltado y la nota escrita. ---- ===== 8. GitHub ===== Se conecta en **Settings → Integrations**. A partir de ahí, en Orca: * **Worktree desde una issue**: se crea el worktree desde la issue y Orca le pone su nombre y la deja enlazada. * **PR**: sus comentarios y sus //checks// se ven en una pestaña. * **Fix broken checks**: en la PR, le pasa al agente los //checks// que fallan para que los arregle. 📷 **Captura pendiente** ''orca-github-issue.png'': crear un worktree desde una issue de ''reservas-api''. ---- ===== 9. Varios agentes con la misma tarea ===== Como cada worktree es independiente, se puede dar **la misma tarea a varios agentes** y quedarse con la mejor solución: - Tres worktrees desde ''origin/main'': ''login'', ''login-2'' y ''login-3'', cada uno con un agente distinto. - El mismo prompt en los tres, por ejemplo «implementa specs/login según su tasks.md». - Cuando terminan, revisar los tres diffs. - Seguir con el mejor y borrar los otros dos worktrees. Merece la pena en tareas en las que hay que decidir un diseño, donde ver tres soluciones ayuda a elegir. En tareas mecánicas es gastar tres veces lo mismo. ---- ===== 10. El skill de Orca: que el agente maneje Orca ===== Con el skill de Orca, el agente puede crear worktrees, leer otras terminales y mandarles órdenes, igual que el [[cursos:sdd:03-herdr#el_skill_de_herdrque_el_agente_maneje_herdr|skill de herdr]]. Primero se activa la orden ''orca'' en **Settings → General → Orca CLI** (en Linux se llama ''orca-ide'', para no chocar con el lector de pantalla Orca de GNOME), y después se instala el skill: npx skills add https://github.com/stablyai/orca --skill orca-cli -g Desde el agente, dentro de Orca, se le pide por ejemplo: * Lanzar los tests en otra terminal sin quitarte el foco: en orca, abre una terminal en este worktree, lanza npm test y avísame cuando acabe * Leer la salida de otro agente y actuar sobre ella: lee en orca la terminal del worktree login y dime en qué tarea de tasks.md va * Arrancar otro agente que revise el trabajo: en orca, crea un worktree revisa-login desde esta rama con otro claude que revise specs/login/design.md contra requirements.md, espera a que termine y resúmeme lo que encuentre El skill es para pedirle cosas **a mano mientras trabajas**. Instálalo solo con ''-g'', en tu usuario y nunca en el proyecto, y que **ningún skill ni comando del proyecto dependa de Orca**: en CI no hay Orca y esa parte no se ejecutaría. ---- ===== 11. Atajos de teclado ===== Orca se maneja con el ratón; estos son los atajos que merece la pena saber. En macOS, ''Cmd'' en lugar de ''Ctrl''. Se cambian en **Settings → Shortcuts**. ^ Tecla ^ Orden ^ | ''Ctrl+J'' | **Ir a cualquier worktree o pestaña** escribiendo parte de su nombre. Esta es muy útil | | ''Ctrl+P'' | Abrir un fichero del worktree | | ''Ctrl+Tab'' | Volver a la pestaña anterior | | ''Ctrl+Shift+]'' / ''Ctrl+Shift+['' | Pestaña siguiente / anterior | | ''Ctrl+Shift+Backspace'' | Borrar el worktree (pide confirmación) | | ''c'' | En el diff, comentar la línea del cursor | ---- ===== 12. Más información ===== * [[https://www.onorca.dev|onorca.dev]]: web oficial. * [[https://www.onorca.dev/docs|Documentación]]: guía de todas las funciones, con recetas paso a paso. * [[https://www.onorca.dev/docs/cli/reference|Referencia de la CLI]]: todas las órdenes de ''orca'' que usa el skill. * [[https://github.com/stablyai/orca|Repositorio]]: código y versiones publicadas.