Trabajar con agentes de IA

La automatización de Zshell está pensada principalmente para agentes de programación con IA. Les ofrece una forma segura de trabajar con los paneles de Zshell y coordinar otros agentes; no es otro lenguaje de comandos que tengas que aprender.

La integración con IA está activada de forma predeterminada. Habla con tu agente de programación como siempre. Puede crear un panel en segundo plano, iniciar un agente delegado, ejecutar un comando, esperar el resultado y traerte la respuesta sin quitar el foco al panel que estás usando.

Esperar los resultados de un comandoCopiar enlace

Para comandos que terminan, como pruebas o compilaciones, tu agente puede esperar su propio código de salida y duración y después leer la salida reciente guardada del terminal. Si se agota la espera, el comando sigue ejecutándose y puedes volver a esperar la misma tarea sin cambiar el foco. Se requiere un indicador vacío en el zsh local original que inició Zshell; no se admiten shells anidados, SSH ni programas de inicio personalizados. La salida reciente es limitada y puede incluir comandos o indicadores anteriores. Pide al agente que guarde la salida completa en un archivo cuando lo necesites.

Se rechazan las llamadas directas a exit, logout y exec porque terminan o reemplazan el shell original; usa /bin/sh -c para ejecutarlas en un subproceso.

Configuración inicialCopiar enlace

Revisa Ajustes → Automatización → IA. La opción está activada de forma predeterminada; si la desactivaste, vuelve a activarla y después abre un terminal nuevo o reinicia el agente que ya estuviera en ejecución.

Zshell admite Codex, Claude Code, Gemini CLI, Grok Build, OpenCode, Cursor Agent, Aider, Amp y Pi. Si detecta una configuración de agente existente que entra en conflicto con esta función, la deja intacta, devuelve el interruptor a su estado anterior y muestra el error en Ajustes.

Pide lo que necesitas con tus propias palabrasCopiar enlace

Explica a tu agente qué resultado quieres. Por ejemplo:

Ejecuta las pruebas pertinentes en un panel en segundo plano y dime cuáles fallan.

Delega este error a otro agente de Codex y después revisa su resultado.

Pregunta al agente que trabaja en la API si el esquema está listo y pasa la respuesta al agente que ejecuta las pruebas.

Inicia el servidor de desarrollo a nuestro lado, espera a que esté listo y dame la URL.

Comprueba si el agente en segundo plano ha terminado. Si está bloqueado, dime qué necesita.

El agente utiliza la interfaz de automatización de Zshell por ti. No necesitas escribir ni memorizar comandos de automatización de Zshell.

Deja que los agentes se coordinen entre panelesCopiar enlace

Puedes repartir trabajo relacionado entre varios paneles de Zshell y pedir a tu agente principal que lo coordine. Por ejemplo, un agente puede trabajar en una API mientras otro actualiza las pruebas. El agente coordinador puede pedir sus hallazgos a un agente concreto, enviarle una instrucción adicional, pasar el resultado útil a otro agente y devolverte una respuesta conjunta. Los agentes delegados pueden usar distintas herramientas de programación compatibles.

Así se elimina el paso de copiar y pegar en el trabajo en paralelo. Cada agente mantiene su propia conversación en su panel, mientras el coordinador transmite solo la pregunta, la actualización o el resultado que necesita el otro agente.

Enviar una instrucción adicional no significa que el trabajo haya terminado. El coordinador sigue esperando al agente, lee su resultado y comprueba lo conseguido. Un mensaje de otro agente tampoco se considera nunca tu aprobación. Los permisos, las credenciales, las decisiones de confianza y las acciones destructivas siguen requiriendo tu intervención.

Sigue trabajando mientras se ejecutaCopiar enlace

Los paneles delegados permanecen en segundo plano salvo que pidas verlos. Cuando una integración nativa del proveedor informa del estado del ciclo de vida, Zshell lo muestra en el panel y la pestaña del agente:

Zshell da prioridad a los eventos nativos de Codex, Claude Code, Pi, OpenCode y Grok, y después a los informes explícitos de programas. Pasa el cursor por el indicador o abre Agents para ver origen, motivo de espera, porcentaje y subtareas. Los hooks de Codex deben revisarse y marcarse como fiables en /hooks; Zshell no omite este paso.

Sin informe nativo, solo se examina una parte limitada del pie de la pantalla actual de un agente reconocido. La inferencia de pantalla se identifica, nunca indica finalización, envía notificaciones ni satisface zshell +agent wait. Tampoco concede aprobaciones. Revisa el panel y el resultado real.

Los programas informan con zshell +agent report y borran su propio informe con zshell +agent clear. El informe caduca tras 120 segundos sin actualizar o al salir el proceso propietario.

Cuando una integración informa de que un agente ha terminado o necesita información, Zshell también puede enviar una notificación. Pulsa Cmd+Shift+A para ir al siguiente agente que haya indicado que necesita tu atención.

Uso y límites de la cuentaCopiar enlace

Ajustes → Automatización → Uso de la cuenta muestra los límites de cuenta disponibles para Claude Code y Codex, incluido el porcentaje utilizado, la hora de restablecimiento cuando se informa de ella y la hora de la última actualización. Usa Actualizar uso para cargar los datos más recientes disponibles.

Codex necesita una CLI instalada, con sesión iniciada y capaz de informar de los límites de cuenta. El uso de Claude Code aparece cuando Zshell recibe del proveedor un informe de uso a través de la línea de estado. La sección solo aparece cuando hay datos de uso; los periodos disponibles dependen del proveedor y de la cuenta. Son límites de la cuenta, no un total de tokens de la sesión con el foco.

Un flujo de trabajo habitualCopiar enlace

1. Inicia tu agente de programación habitual en un terminal de Zshell.
2. Pídele que delegue una tarea acotada, ejecute algo en segundo plano o coordine otro agente.
3. Sigue trabajando en el panel actual mientras Zshell mantiene visible el trabajo delegado en la distribución del proyecto.
4. Consulta el indicador Trabajando, Bloqueado o Terminado comunicado por el proveedor cuando esté disponible. Si la herramienta no informa de su ciclo de vida, abre el panel para revisar su conversación o la salida del terminal.
5. Revisa los archivos resultantes en el panel de Git, examina las diferencias y decide qué conservar.

Tú mantienes el controlCopiar enlace

• La automatización de agentes se limita al proyecto actual de Zshell y no puede acceder a paneles de otro proyecto o ventana.
• El trabajo en segundo plano no toma el foco salvo que lo pidas explícitamente.
• Zshell nunca responde por ti a solicitudes de permisos, credenciales, confianza o acciones destructivas. Si el proveedor comunica que un agente está bloqueado, esa decisión vuelve a ti.
• Una finalización comunicada es una señal para revisar el resultado, no una aprobación automática de los cambios del agente.

Si un agente no utiliza ZshellCopiar enlace

• Confirma que Ajustes → Automatización → IA está activado.
• Abre un terminal nuevo de Zshell si el actual ya existía antes de activar la opción.
• Reinicia el agente si ya estaba en ejecución cuando la activaste.
• Comprueba si Ajustes muestra un error de configuración junto a la opción.
• Pide expresamente un «panel de Zshell en segundo plano» o un «agente delegado de Zshell» si quieres que el agente use este flujo de trabajo para una tarea.

Reanudar la conversación originalCopiar enlace

Con Reanudar conversaciones de agentes, un panel cuyo PTY original no esté disponible retoma su conversación registrada de Claude Code, Codex, Pi u OpenCode. Los paneles del mismo directorio mantienen conversaciones independientes.

Zshell instala hooks SessionStart para Claude Code y Codex, una extensión Pi y un plugin TUI de OpenCode en la configuración existente. Conserva otros hooks, plugins, ajustes y comentarios JSONC. Cuando el proveedor lo pida, active los hooks en la confirmación de confianza de Claude Code y apruebe los nuevos hooks de Codex en /hooks. Reinicie los agentes que ya estaban en ejecución.

Solo se reanudan conversaciones raíz verificadas notificadas por estas integraciones. Las sesiones compartidas del app-server de Codex son compatibles cuando un ID de conversación verificado coincide con el panel; las coincidencias ambiguas no se vinculan. Para conversaciones en hosts remotos, consulta sesiones remotas compartidas. OpenCode requiere la API de plugins TUI; no admite versiones antiguas, sesiones de servidor sin interfaz ni opencode attach. Un agente hijo no sustituye la conversación del panel padre. Pi necesita su archivo de sesión guardado.

Sin identidad verificada, directorio original o archivo Pi, se abre una nueva shell. Si no se encuentra el CLI, también se vuelve a la shell. Zshell no repite comandos de inicio arbitrarios ni elige una conversación reciente. El CLI muestra los errores del proveedor, como una conversación eliminada.

Buscar y reanudar conversaciones guardadasCopiar enlace

Abre Agentes → Historial de conversaciones de agentes, pulsa el reloj de la parte superior de la barra lateral de proyectos. Busca entre proyectos por título, proveedor, proyecto, ID de conversación o directorios de trabajo y configuración. Zshell conserva las 200 conversaciones locales verificadas más recientes después de cerrar agentes y paneles y de reiniciar la aplicación. Recientes muestra 20 coincidencias sin archivar; Todas incluye las archivadas; Archivadas solo muestra estas últimas.

Elige Mostrar conversación si está abierta o Reanudar conversación si está guardada. Zshell reutiliza un panel abierto, reconecta un PTY activo o reanuda la conversación exacta del proveedor con su directorio y configuración originales. La reanudación manual requiere la integración de IA, aunque la restauración automática esté desactivada. Si falta un directorio o el archivo Pi falta o no corresponde a la conversación, se muestra un error antes de crear un panel.

Archivar oculta el registro en Recientes; Desarchivar lo devuelve. Eliminar… solo elimina el registro de Zshell y conserva los archivos del proveedor.

Dentro de un panel Zshell, zshell +agent history --all y zshell +agent resume --id HISTORY_UUID se limitan a su proyecto. Desde un terminal externo normal, mantén Zshell abierto, obtén el UUID del proyecto y selecciónalo explícitamente:

zshell +agent history projects
zshell +agent history --project PROJECT_UUID --all
zshell +agent resume --project PROJECT_UUID --id HISTORY_UUID --focus

La CLI reanuda en segundo plano salvo que añadas --focus. Si el proyecto está abierto en varias ventanas, elige --window WINDOW_UUID de history projects. Si hay varias instancias de la aplicación, usa --connection PATH con la ruta absoluta del archivo de conexión privado indicada por la CLI. Estas opciones son para terminales externos; los procesos de los paneles conservan su proyecto original.

Seguir eventos del proyectoCopiar enlace

Ejecuta zshell +events dentro de Zshell para recibir en NDJSON los cambios futuros de su proyecto y ventana, sin sondeo. Opciones: --pane UUID, --event NAME repetible, --once y --timeout MS (0 espera indefinidamente).

Incluye creación y cierre de sesiones y paneles, foco, progreso, atención y finalización de agentes, y comandos terminados. stream.ready comienza en sequence 0; cada evento coincidente la incrementa. Cada línea incluye version, event, stream_id, sequence, time en milisegundos Unix, project_id y data. No se reproduce el historial. Lee los resultados con +pane wait --task UUID.

Límites: 32 suscripciones, 256 tramas y 1 MiB por cola, 64 KiB por trama. Un lector lento recibe stream.lagged cuando es posible y se desconecta; dos segundos sin poder escribir también cierran la conexión. El retraso, la desconexión inesperada o un error de secuencia terminan con código no nulo. Suscríbete de nuevo y consulta el estado actual. Cerrar el terminal, renovar el token o moverlo a otro proyecto o ventana finaliza la suscripción. Sin control externo ni --project; borrar variables no amplía permisos. --once sin coincidencias devuelve 124 al vencer; el tiempo de espera normal devuelve 0.

zshell +events --event command.task.finished --once --timeout 30000

pane.updated: data.from → data (tab_id, pane_id, terminal_id, content).