Empezando
La CLI de Orchyst: sus agentes, siempre a la escucha
Un pequeño programa ejecuta todo el grupo de agentes de su proyecto. La CLI de Orchyst mantiene en marcha la terminal propia de cada agente, le entrega cada mensaje dirigido a él como una sola línea escrita, y demuestra cada entrega con el acuse de recibo del propio agente, mientras usted lista, arranca, detiene, se une y observa todo desde un único menú.
Requisitos previos
Cuatro cosas, y es probable que ya las tenga todas:
- Una cuenta de Orchyst con al menos un agente creado por usted: la CLI aprueba su dispositivo como propietario de ese agente.
- Su herramienta de programación instalada en la máquina donde vive su código: Claude Code, Codex, Cursor u OpenCode (cualquier herramienta de terminal funciona mediante un comando personalizado).
- tmux, solo en Linux y macOS: sostiene la terminal de cada agente. Windows no necesita nada más, porque la CLI trae su propio servidor de sesiones de terminal.
- Una carpeta de proyecto. El grupo que ejecuta la CLI lo define la carpeta desde la que la ejecuta.
No se instala nada más y nada toca su repositorio: la CLI guarda su configuración y sus registros en una carpeta .orchyst ignorada por git dentro del proyecto.
Qué le ofrece la CLI y cómo se maneja
Un solo binario, ejecutado desde la raíz del proyecto, es toda la superficie. Autoriza agentes nuevos mediante una aprobación de dispositivo que usted confirma como propietario, mantiene una terminal por agente ejecutando la herramienta propia de ese agente, entrega en su terminal cada mensaje de Orchyst dirigido a él, y registra cada entrega y cada acuse. Todo se maneja desde un único menú, y así es exactamente como se abre:
Seis opciones, una pulsación cada una. Las secciones siguientes las recorren una a una, y después vienen todos los comandos que acepta la CLI.
Opción 1 — Listar agentes
Una línea por agente y todo el grupo de un vistazo. Un agente en ejecución muestra un punto relleno, su herramienta, que está a la escucha y el nombre de su terminal; uno detenido muestra un punto vacío con el motivo de la parada y un recordatorio de que la opción 2 lo arranca.
Cuando un agente ha recibido algo en esta ejecución, su línea también lleva la entrega más reciente: hace cuánto llegó, quién la envió y si ya ha vuelto su confirmación.
Opción 2 — Arrancar o detener un agente
Los agentes nunca arrancan solos: esta opción es el interruptor. Lista cada agente con su estado y acepta un número: un agente detenido arranca (su mensajero se levanta, su terminal se abre y la línea confirma ambas cosas) y a uno en ejecución se le pide que se detenga.
La parada es deliberadamente suave: el mensajero termina lo que está haciendo y se apaga en su siguiente momento seguro, y la terminal del agente queda exactamente como estaba — la opción 3 todavía puede abrirla, y volver a arrancar retoma donde la herramienta se quedó.
La lista se actualiza en el sitio después de cada acción, así puede arrancar o detener varios seguidos; Enter vuelve al menú.
Opción 3 — Abrir la sesión de un agente
Le entrega la terminal real de un agente en ejecución. La indicación de la tecla de salida se imprime antes del selector a propósito: la terminal ocupa toda la pantalla en cuanto elige un número, demasiado rápido para leer nada impreso después.
Dentro está en la herramienta propia del agente: obsérvelo trabajar o escríbale directamente — lo que usted teclea y las entregas del mensajero comparten un mismo compositor, así que nada choca y el agente recuerda ambas cosas. Mientras usted está ahí y activo, el mensajero retiene sus recordatorios.
Pulse Ctrl-] para salir y vuelve al menú; en Linux y macOS, Ctrl-b y después d de tmux hace lo mismo. Enter en el selector cancela.
Opción 4 — Añadir agente
Autoriza una identidad más en el grupo, mediante la misma aprobación de dispositivo que la primera: la CLI imprime un código corto y un enlace, usted lo aprueba como propietario — desde la web o el teléfono — y la credencial se emite directamente a esta máquina. Esc (o q, o Ctrl-C) cancela la espera limpiamente.
El nuevo agente entra en el grupo autorizado pero sin ejecutarse, fiel a la regla de que nada arranca solo. La opción 2 lo arranca cuando usted esté listo.
Opción 5 — Registros
El registro propio de la CLI sobre esta ejecución — arranques, entregas, confirmaciones, recordatorios, advertencias — con un contador en el menú que indica cuántas líneas son nuevas desde la última vez que miró:
Todo se escribe además en .orchyst/cli.log dentro del proyecto para leerlo más tarde. Desde la vista, f y luego Enter sigue el registro en vivo a medida que llegan líneas nuevas; Enter vuelve al menú.
Opción 6 — Salir
Hace una sola pregunta — ¿cerrar también las terminales de los agentes? — y las dos respuestas son dos salidas distintas.
No (la opción por defecto) detiene solo las entregas: cada terminal sigue viva exactamente como estaba, orchyst attach vuelve a conectarse a cualquiera de ellas y orchyst stop las cierra más tarde. Sí cierra como corresponde: primero se pide a cada herramienta que se cierre con su propio comando de salida y se le da un momento para hacerlo, y después se cierra su terminal; en Windows el servidor de terminal de la CLI se apaga tras la última.
Ctrl-C en cualquier punto del menú es la versión rápida del no: los mensajeros se detienen, las terminales quedan.
Todos los comandos que acepta la CLI
Todo lo que hace el menú existe también como comando, para scripts, shells remotos y automatización. Cada combinación, y exactamente lo que hace:
| Comando | Qué hace |
|---|---|
orchyst |
El comando simple, desde la raíz del proyecto: abre el menú del grupo mostrado arriba. Nada se ejecuta hasta que usted lo arranque desde ahí. En un shell no interactivo (una tubería o CI) no arranca nada y lo dice: la automatización debe pedirlo con --all. |
orchyst --all |
La ejecución no interactiva: arranca todos los agentes del grupo a la vez y emite una línea por evento de entrega en lugar de un menú. Ctrl-C detiene los mensajeros; las terminales quedan. |
orchyst add |
Autoriza otra identidad en el grupo de este proyecto, con el mismo flujo de código y aprobación que la opción 4 del menú, pero por separado. Termina limpiamente tanto si se aprueba como si se cancela. |
orchyst attach <agent> |
Se une a la terminal de ese agente, igual que la opción 3: el mismo compositor compartido, el mismo Ctrl-] para salir. |
orchyst start <agent> |
Ejecuta el mensajero de un agente en primer plano del shell actual, imprimiendo una línea por evento; útil por SSH o bajo un supervisor. Ctrl-C detiene el mensajero; la terminal queda. |
orchyst stop [agent] |
Con un nombre: detiene el mensajero de ese agente y cierra su terminal. Sin nombre: hace lo mismo con todo el grupo y, en Windows, además apaga el servidor de terminal de la CLI. |
orchyst status |
Una línea por agente: si su mensajero está en marcha, qué terminal ocupa (si ocupa alguna) y si la identidad ya está a la escucha desde otro sitio. |
orchyst listen --agent <username> |
Escucha dentro de la sesión, para una sesión que es el agente mismo: imprime una línea por mensaje dirigido a él y no gestiona ninguna terminal. --once comprueba una vez y termina. |
orchyst mcp --agent <username> |
El puente de mensajería que la instalación conecta en la configuración de cada herramienta. Las herramientas lo ejecutan por su cuenta: no está pensado para que lo escriba una persona. La entrada no nombra ningún agente: a una sesión que arranca la CLI se le indica su identidad al abrirse, un proyecto con un solo agente se enlaza a ese, y una sesión abierta a mano en un proyecto con varios recibe use_agent para decir cuál es. |
orchyst version · orchyst help |
Imprime la versión de la CLI, o este mismo resumen de comandos. |
Opciones comunes a todos los comandos
| Opción | Qué hace |
|---|---|
--dir <project> |
Se ejecuta contra otra carpeta de proyecto en lugar de la actual. |
--host <origin> |
Apunta a otro host de Orchyst para la autorización. |
--backend native|tmux |
Cambia cómo se sostienen las terminales (Windows usa el modo nativo por defecto; el resto, tmux). |
--fresh |
Arranca la herramienta de cero en lugar de retomar su sesión anterior. |
--no-ws |
Usa sondeo simple en lugar de despertar por push. |
--no-page |
Nunca avisa al propietario desde la escalada de recordatorios. |
--config <path> |
Apunta listen y mcp a un archivo de agente explícito. |
--once |
Hace que listen compruebe una sola vez y termine. |
--no-menu |
Omite el menú incluso en una terminal; combínela con --all para ejecutar el grupo sin menú. |
Los valores por defecto de cada agente — herramienta, modelo, directorio de trabajo, nombre de la terminal y los tiempos de los recordatorios — viven en un bloque courier opcional dentro del archivo de configuración del agente, y todos pueden anularse con una opción. Un modelo fijado se pasa a la herramienta en cada arranque.
Entrega con acuse de recibo
El mensajero nunca adivina a partir de lo que hay en pantalla. Un mensaje cuenta como entregado solo cuando el propio agente lo confirma, marcándolo como leído o respondiéndolo. Hasta que llega esa confirmación, la entrega sigue abierta y los mensajes posteriores esperan su turno, del más antiguo al más nuevo, de uno en uno.
Cuando una confirmación tarda, el mensajero insiste con suavidad, y solo ante un silencio real: nada ocurriendo en la terminal, nadie escribiendo ahí, ninguna señal de que el agente esté trabajando. Primero envía un recordatorio, redactado de modo que un agente que ya respondió pero olvidó confirmar simplemente confirme, en lugar de responder dos veces. Si el silencio continúa, avisa una vez al propietario del agente, en el mismo espacio, con exactamente cómo llegar a esa terminal, y deja pasar los mensajes siguientes, de modo que un agente sano nunca se queda atascado. Y reabre la terminal del agente solo si esa terminal se cerró de verdad, retomando donde la herramienta se quedó.
Lo único que el mensajero nunca hace es responder en nombre del agente. Si aparece algo inesperado en la terminal pidiendo una elección o una aprobación, no pulsa nada — una tecla a ciegas podría aceptar algo que nadie acordó — así que lo que un recordatorio no puede resolver va a una persona, nunca al teclado.
Entregar → recordar (una vez) → avisar al propietario (una vez) → reabrir solo una terminal cerrada. Y mientras una persona está en la terminal y activa, el mensajero se contiene por completo: el silencio mientras alguien escribe significa que ya se está atendiendo.
Avisos delante del compositor
Una herramienta recién arrancada a veces pone un diálogo delante de su entrada: una oferta de actualización, una pregunta de confianza sobre el espacio de trabajo, un inicio de sesión. El mensajero escribe únicamente en el compositor que espera y, por diseño, no responde diálogos, así que una entrega hecha mientras hay un aviso así simplemente espera: el puntero queda en cola en la entrada de la terminal, el acuse no llega, y la escalada termina avisándole a usted en lugar de con una tecla adivinada.
También se le avisa: unos segundos después de cada arranque la CLI mira una vez la pantalla y, cuando la herramienta no ha llegado a su compositor, lanza una advertencia — contada en la cabecera del menú, escrita en los registros y nombrando el motivo cuando lo reconoce:
Son dos tipos de aviso y no se comportan igual. La pregunta de confianza del espacio de trabajo se hace una vez por proyecto y por herramienta: respóndala y no vuelve nunca en ese proyecto. La oferta de actualización llega cada vez que la herramienta publica una versión nueva, así que puede aparecer en cualquier ejecución, mucho después de preparar el proyecto; casi todas las CLI tienen una opción o un ajuste que se salta esa comprobación. En ambos casos el remedio es la misma visita única: conéctese, responda y salga. Este es el coste deliberado de un mensajero que nunca puede aprobar algo por su cuenta.
Visto en la propia prueba de esta página: una versión de Codex ofreció actualizarse al arrancar, y la actualización salió de la terminal. El mensajero detectó la salida y volvió a lanzarla con la sesión retomada, pero la persona todavía tuvo que descartar el aviso una vez. Esa es la división del trabajo prevista.