Diferencias

Muestra las diferencias entre dos versiones de la página.

--- cursos:sdd:06-orca [2026/11/05 21:14] – borrado - editor externo (Fecha desconocida) 127.0.0.1
+++ cursos:sdd:06-orca [2026/11/05 21:15] (actual) – ↷ Enlaces adaptados debido a una operación de mover claude
@@ Línea 1: / Línea 1: @@
+====== 6. 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:05-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.
+<sxh bash>
+wget https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage
+chmod +x orca-linux.AppImage
+./orca-linux.AppImage
+</sxh>
+  * macOS
+<sxh bash>
+brew install --cask stablyai/orca/orca
+</sxh>
+  * Windows: ''orca-windows-setup.exe'' de la [[https://github.com/stablyai/orca/releases/latest|última versión]].
+<note>Si el AppImage no arranca en Ubuntu, le falta FUSE: ''sudo apt install libfuse2''.</note>
+==== 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.
+<note>📷 **Captura pendiente** ''orca-primer-arranque.png'': la pregunta de acceso a la carpeta personal y de importar ''~/.claude''.</note>
+==== Los permisos del agente ====
+<note warning>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.</note>
+<note>📷 **Captura pendiente** ''orca-permisos-agente.png'': //Settings → Agents// con los //launch arguments// de Claude Code desplegados.</note>
+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:05-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.
+<note>📷 **Captura pendiente** ''orca-niveles.png'': la ventana entera con el repositorio, un worktree, las pestañas y dos paneles señalados.</note>
+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.
+<note>📷 **Captura pendiente** ''orca-add-repo-1.png'': el botón **Add Repo**, con círculo rojo.</note>
+<note>📷 **Captura pendiente** ''orca-add-repo-2.png'': ''reservas-api'' ya en la barra lateral.</note>
+==== 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.
+<note>📷 **Captura pendiente** ''orca-worktree-nuevo-1.png'': el ''+'' junto a ''reservas-api'', con círculo rojo.</note>
+<note>📷 **Captura pendiente** ''orca-worktree-nuevo-2.png'': el diálogo con el nombre ''login'', //start from// ''origin/main'' y el agente.</note>
+<note important>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.</note>
+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.
+<sxh plain; title: .worktreeinclude>
+.env
+</sxh>
+  * ''orca.yaml'': carpetas que se **comparten** entre todos los worktrees, sin copiarlas.
+<sxh yaml; title: orca.yaml>
+worktree:
+  sharedDirectories:
+    - node_modules
+</sxh>
+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**.
+<note>📷 **Captura pendiente** ''orca-panel-dividir-1.png'': la pestaña arrastrada hasta el borde derecho, con círculo rojo.</note>
+<note>📷 **Captura pendiente** ''orca-panel-dividir-2.png'': el agente a la izquierda y su diff a la derecha.</note>
+Cada worktree guarda su distribución de paneles.
+==== Borrar un worktree ====
+Botón derecho sobre el worktree → **Delete**.
+<note warning>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.</note>
+<note>📷 **Captura pendiente** ''orca-worktree-borrar.png'': el aviso al borrar un worktree, donde dice que se borra la rama.</note>
+----
+===== 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 |
+| <color #df8e1d>?</color> Interrogación ámbar | Te espera: un permiso, una pregunta, una decisión | **Ir a contestarle** |
+| <color #40a02b>●</color> Punto esmeralda | Ha terminado | Revisar el resultado |
+| <color red>●</color> Punto rojo | Bloqueado, interrumpido o con error | Mirar qué ha pasado |
+| <color gray>●</color> 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.
+<note>📷 **Captura pendiente** ''orca-estados.png'': la barra lateral con worktrees en varios estados, uno esperando respuesta.</note>
+<note warning>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]]).</note>
+==== 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**.
+<note>📷 **Captura pendiente** ''orca-campana.png'': la campana con la lista de avisos desplegada.</note>
+==== 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**.
+<note important>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.</note>
+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.
+<note>📷 **Captura pendiente** ''orca-movil-emparejar.png'': el código de emparejamiento en el Orca del ordenador.</note>
+==== 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.
+<note>📷 **Captura pendiente** ''orca-movil-agentes.png'': la app con la lista de agentes y uno esperando respuesta.</note>
+<note>📷 **Captura pendiente** ''orca-movil-responder.png'': contestando desde el móvil a la pregunta del agente.</note>
+<note warning>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.</note>
+----
+===== 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.
+<note>📷 **Captura pendiente** ''orca-diff-comentar-1.png'': el ''+'' en el margen de una línea del diff, con círculo rojo.</note>
+<note>📷 **Captura pendiente** ''orca-diff-comentar-2.png'': el comentario escrito sobre esa línea.</note>
+<note>📷 **Captura pendiente** ''orca-diff-enviar.png'': **Send to agent** con el menú //Send notes to// desplegado.</note>
+<note tip>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.</note>
+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.
+<note>📷 **Captura pendiente** ''orca-editor.png'': un ''design.md'' formateado en un panel y el agente en el otro.</note>
+----
+===== 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».
+<note>📷 **Captura pendiente** ''orca-design-mode-1.png'': el botón de Design Mode en la barra del navegador, con círculo rojo.</note>
+<note>📷 **Captura pendiente** ''orca-design-mode-2.png'': el botón de //Comprar// de ''tienda-web'' resaltado y la nota escrita.</note>
+----
+===== 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.
+<note>📷 **Captura pendiente** ''orca-github-issue.png'': crear un worktree desde una issue de ''reservas-api''.</note>
+----
+===== 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.
+<note tip>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.</note>
+----
+===== 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:05-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:
+<sxh bash>
+npx skills add https://github.com/stablyai/orca --skill orca-cli -g
+</sxh>
+Desde el agente, dentro de Orca, se le pide por ejemplo:
+  * Lanzar los tests en otra terminal sin quitarte el foco:
+<sxh plain>
+en orca, abre una terminal en este worktree, lanza npm test y avísame cuando acabe
+</sxh>
+  * Leer la salida de otro agente y actuar sobre ella:
+<sxh plain>
+lee en orca la terminal del worktree login y dime en qué tarea de tasks.md va
+</sxh>
+  * Arrancar otro agente que revise el trabajo:
+<sxh plain>
+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
+</sxh>
+<note warning>
+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.
+</note>
+----
+===== 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.