Agentes CLI

Si ya usas Claude Code o Codex, puedes ejecutarlos dentro de Perch. Elige uno en el selector de modelos, dale una carpeta y trabaja ahí con sus propias herramientas, con tu propia sesión. Tus chats de Perch y tus agentes están en una misma barra lateral, así que puedes seguirlos a todos desde un solo lugar.

Cada agente trabaja en su propia copia de tu repositorio, en una rama propia, así que varios pueden trabajar a la vez sin tocar tu checkout. Cuando uno termina, ves lo que cambió y lo fusionas en tu carpeta con un clic, o abres un pull request.

Antes de empezar

• Perch Desktop 2.5.4 o posterior, con la sesión iniciada en una cuenta Pro o Ultra. Los agentes CLI no están en Perch en la web.
• Claude Code o Codex instalado en esta computadora y con la sesión iniciada. Si claude o codex se ejecuta en tu terminal, Perch puede iniciarlo. Perch usa tu instalación y tu sesión, y no incluye ninguno de los dos.
• Git. En Windows, instala Git for Windows. Para fusionar se necesita git 2.40 o posterior.
• Una carpeta que agregaste a Perch y que esté en un repositorio de git con al menos un commit, para que el agente pueda tener su propia copia.

Inicia un agente

La barra del chat muestra lo que está haciendo el agente, su nombre, la carpeta y su rama, como agent/add-a-dark-mode-toggle-t-7q2m.

Un chat se queda con el agente con el que empezó. Para volver a los modelos propios de Perch, inicia un chat nuevo.

Mientras trabaja

• Las aprobaciones llegan a ti. Cuando el agente pide permiso para algo, aparece una tarjeta que dice Claude asks to go ahead con las opciones que ofrece.
• Mode define los modos propios del agente, los mismos que tiene en su CLI, como Accept edits en Claude.
• Envía mensajes de seguimiento cuando quieras. Mientras trabaja, lo que envías espera y sale cuando termina el turno. Puedes adjuntar imágenes PNG, JPEG, GIF o WebP de hasta 5 MB cada una.
• Diff abre el panel Changes con cada archivo que el agente cambió en su copia.
• Open terminal abre una terminal al lado del chat, en la copia del repositorio del agente.
• Ejecuta varios a la vez. Hasta cuatro agentes pueden ejecutarse al mismo tiempo, cada uno en su propia copia. La barra lateral muestra cuáles están trabajando.

Su propia copia de tu repositorio

De forma predeterminada, cada agente trabaja en un worktree de git: un segundo checkout de tu repositorio, en su propia carpeta y en su propia rama. Tu carpeta, la rama en la que está y todo lo que no hayas incluido en un commit se quedan como están mientras el agente trabaja, y dos agentes nunca editan los mismos archivos.

Un worktree solo tiene los archivos que git rastrea. Perch también lleva a la copia lo que la mayoría de los proyectos necesita para ejecutarse:

• Archivos de configuración locales. Los archivos .env y .env.*, en cualquier nivel de carpetas, se copian cuando git los ignora. Para copiar otros archivos ignorados, como configuraciones locales o certificados, enuméralos en un archivo .worktreeinclude en la raíz del repositorio, con la sintaxis de .gitignore. Un archivo solo se copia si git también lo ignora en la copia, así nunca termina en un commit. Hasta 200 archivos, 10 MB cada uno y 50 MB en total. Los enlaces simbólicos se omiten.
• Copy node_modules, en Options en macOS, clona tu node_modules en la copia. Es un clon copy-on-write: casi instantáneo y sin espacio adicional en disco.
• Setup command, en Options, ejecuta un comando como npm install en la copia antes de que empiece el agente, en tu shell (PowerShell en Windows). Perch lo recuerda para ese repositorio. Si falla o tarda más de 15 minutos, el agente empieza de todos modos y el chat lo indica. Setup log, en la barra del chat, muestra su salida.

Options también tiene Worktree folder, donde se crean las copias, y Account folder: si inicias sesión en Claude Code o Codex con varias cuentas, elige la carpeta de la que quieras usar. Ambas tienen que estar dentro de tu carpeta personal.

Desactiva Worktree para que el agente trabaje directamente en tu carpeta. Así, sus cambios llegan a tu carpeta a medida que los hace, y no hay paso de diff ni de fusión.

Trae el trabajo de vuelta

Cuando un turno cambia archivos, una tarjeta debajo de la conversación lo indica, por ejemplo: "Claude changed 4 files in its own copy of perch-app. They're not in your folder yet." La barra del chat lleva la cuenta hasta que los traes de vuelta. Review changes abre el diff.

Fusiona en tu rama

Merge into main, que lleva el nombre de la rama en la que está tu carpeta, pone todos los cambios del agente en tu rama como un solo commit. El mensaje del commit empieza siendo el título del chat, y puedes editarlo. Después, Remove the copy elimina el worktree y la rama del agente.

Para fusionar, Perch nunca hace stash ni reset, ni sobrescribe nada en tu carpeta. En su lugar, se detiene y te lo indica cuando:

• Tu carpeta tiene cambios sin commit. Haz commit de ellos primero y luego fusiona.
• Los mismos archivos cambiaron en tu rama y en la copia del agente. Ask Claude to fix le envía al agente un mensaje para que lo resuelva en su copia. Cuando termine, vuelve a fusionar.
• Tu carpeta no está en una rama, o git es anterior a 2.40.

Otras formas de terminar

El menú al lado del botón de fusionar tiene dos opciones más:

• Commit only hace commit de los cambios en la rama propia del agente. Tu carpeta no cambia.
• Open pull request sube la rama del agente a origin y abre un pull request. Si tienes instalado GitHub CLI (gh), Perch lo abre por ti. Si no, Perch abre la página de GitHub para crear un pull request nuevo. En otros servicios de git, sube la rama y tú abres el pull request ahí.

Cerrar un chat

Si cierras un chat cuya copia todavía tiene cambios que no están en tu carpeta, Perch te pregunta primero: Merge first, Keep the copy (su worktree y su rama se quedan donde están) o Discard (elimina la copia y su rama, con los cambios incluidos).

Tu propio plan

Los agentes CLI se ejecutan con tu propia sesión de Claude Code o Codex, así que su uso cuenta para ese plan, no para tu uso de Perch. Los mensajes que les envías no consumen tu uso incluido de Perch.

Perch muestra los límites propios de cada agente tal como el agente los informa, el 5-hour limit y el Weekly limit, con el momento en que se restablece cada uno. Los encuentras en la tarjeta del agente en el selector de modelos y en Settings › Usage, debajo de On this computer, y una nota encima del cuadro de mensaje te avisa cuando un agente está cerca de su límite. Aparecen después de la primera respuesta del agente en esta computadora.

Privacidad

• Los chats se quedan en esta computadora. Los chats de los agentes CLI no se guardan en tu cuenta de Perch, así que no aparecen en Perch en la web ni en tu celular.
• El agente se comunica con su propio servicio. Tus mensajes van de Claude Code a Anthropic, o de Codex a OpenAI, igual que cuando usas la CLI por tu cuenta. No pasan por los servidores de Perch.
• Cada agente recibe solo lo que necesita. Perch lo inicia con una lista corta de tus variables de entorno: sin las claves de otros agentes y sin nada de Perch.

Con subsesiones

Perch puede entregarle parte de un trabajo a Claude Code o Codex. Pídelo, por ejemplo "haz que Codex arregle la prueba inestable en su propia sesión", y Perch sugiere una subsesión que corre en ese agente, en un worktree nuevo de la carpeta del chat. Como cualquier subsesión, empieza solo cuando seleccionas Start, y le informa al chat que la inició. Las aprobaciones del agente siguen llegando a ti.

Solución de problemas

No veo On this computer en el selector de modelos. Comprueba que iniciaste sesión con una cuenta Pro o Ultra en Perch Desktop 2.5.4 o posterior.

Un agente dice Not installed. Instálalo para que claude o codex esté en tu PATH, y luego cierra Perch y vuelve a abrirlo.

Dice Needs sign-in. Selecciona Sign in in a terminal, que ejecuta claude o codex login por ti. Termina de iniciar sesión y luego selecciona Try again.

Dice que su CLI es más antigua de lo que Perch necesita. Actualízala. Para Claude Code, ejecuta claude update. Actualiza Codex de la misma forma en que lo instalaste, con npm o Homebrew.

Dice que necesita Node 22. Ese mensaje viene de las versiones de la app de escritorio anteriores a 2.5.4. Actualiza Perch Desktop, que ejecuta los agentes sin Node.

La carpeta no puede tener un worktree. Tiene que estar en un repositorio de git con al menos un commit. También puedes desactivar Worktree.

En Windows, no se puede eliminar la copia. Hay un archivo de la copia abierto en otro programa. Ciérralo y vuelve a intentarlo.