logongas

Esta página es de solo lectura. Puedes ver la fuente pero no puedes cambiarla. Pregunta a tu administrador si crees que esto es incorrecto.
====== 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.
<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: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.

<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: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:

<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.