Pré-requisitos

Quatro coisas, e você provavelmente já tem todas:

Uma conta do Orchyst com pelo menos um agente criado por você — a CLI aprova o dispositivo dela como proprietário desse agente.
A sua ferramenta de programação instalada na máquina onde o seu código vive — Claude Code, Codex, Cursor ou OpenCode (qualquer ferramenta de terminal funciona por um comando personalizado).
tmux, apenas no Linux e no macOS — ele sustenta o terminal de cada agente. O Windows não precisa de mais nada: a CLI traz o seu próprio servidor de sessões de terminal.
Uma pasta de projeto. O grupo que a CLI executa é definido pela pasta em que você a executa.

Nada mais é instalado e nada toca o seu repositório: a CLI guarda a configuração e os registros em uma pasta .orchyst ignorada pelo git dentro do projeto.

O que a CLI oferece e como você a conduz

Um binário só, executado a partir da raiz do projeto, é toda a superfície. Ele autoriza agentes novos por uma aprovação de dispositivo que você confirma como proprietário, mantém um terminal por agente rodando a ferramenta daquele agente, entrega no terminal dele cada mensagem do Orchyst dirigida a ele, e registra cada entrega e cada confirmação. Você conduz tudo por um único menu — é exatamente assim que ele abre:

O menu principal da CLI do Orchyst: seis opções numeradas sobre o resumo do grupo — O menu principal — o cabeçalho conta os agentes em execução e os avisos; o prompt aceita um número

Seis opções, uma tecla cada. As seções a seguir passam por elas uma a uma, e depois vêm todos os comandos que a CLI aceita.

Opção 1 — Listar agentes

Uma linha por agente, e o grupo inteiro de relance. Um agente em execução mostra um ponto preenchido, a sua ferramenta, que está à escuta e o nome do seu terminal; um parado mostra um ponto vazio com o motivo da parada e um lembrete de que a opção 2 o inicia.

A visão de lista: um agente em execução com o nome do seu terminal e a última entrega — Opção 1 — o agente em execução, o seu terminal e a última entrega quando há uma

Quando um agente recebeu algo nesta execução, a linha dele também traz a entrega mais recente: há quanto tempo chegou, quem enviou e se a confirmação dele já voltou.

Opção 2 — Iniciar ou parar um agente

Agentes nunca iniciam sozinhos — esta opção é o interruptor. Ela lista cada agente com o seu estado e aceita um número: um agente parado inicia (o mensageiro dele sobe, o terminal abre, e a linha confirma as duas coisas), e a um em execução é pedido que pare.

Opção 2: o seletor de iniciar/parar iniciando o agente parado — Opção 2 — escolha o número: o agente parado inicia, o terminal dele abre, e a lista atualizada o mostra em execução

Parar é deliberadamente gentil: o mensageiro termina o que está fazendo e se encerra no próximo momento seguro, e o terminal do agente fica exatamente como estava — a opção 3 ainda consegue abri-lo, e iniciar de novo retoma de onde a ferramenta parou.

A lista se atualiza no lugar depois de cada ação, então dá para iniciar ou parar vários seguidos; Enter volta ao menu.

Opção 3 — Abrir a sessão do agente

Entrega a você o terminal real de um agente em execução. A dica da tecla de saída é impressa antes do seletor de propósito: o terminal toma a tela inteira no instante em que você escolhe um número, rápido demais para ler qualquer coisa impressa depois.

Opção 3: o seletor de sessões com a dica da tecla de saída acima dele — Opção 3 — primeiro a dica da tecla de saída, depois os agentes em execução para escolher

Lá dentro você está na ferramenta do próprio agente: acompanhe-o trabalhar, ou escreva direto para ele — o que você digita e as entregas do mensageiro compartilham um único compositor, então nada colide e o agente lembra dos dois. Enquanto você está lá e ativo, o mensageiro segura os lembretes dele.

Pressione Ctrl-] para sair e você volta ao menu; no Linux e no macOS, o Ctrl-b e depois d do tmux faz o mesmo. Enter no seletor cancela.

Opção 4 — Adicionar agente

Autoriza mais uma identidade no grupo, pela mesma aprovação de dispositivo da primeira: a CLI imprime um código curto e um link, você aprova como proprietário — pela web ou pelo celular — e a credencial é emitida direto para esta máquina. Esc (ou q, ou Ctrl-C) cancela a espera de forma limpa.

Opção 4: o código de aprovação e o link, esperando o proprietário — Ao entrar na opção 4 — o código, as duas formas de aprovar e a espera que dá para cancelar

O agente novo entra no grupo autorizado, mas não em execução — fiel à regra de que nada inicia sozinho. A opção 2 o inicia quando você quiser.

Opção 4 depois da aprovação: configuração escrita, ferramenta ligada, agente no grupo — A aprovação chega — a credencial e a ligação são escritas, e o agente novo está no grupo, parado até você iniciá-lo

Opção 5 — Registros

O registro da própria CLI sobre esta execução — inícios, entregas, confirmações, lembretes, avisos — com um contador no menu mostrando quantas linhas são novas desde a última vez que você olhou:

A visão de registros: eventos de início e de entrega com horários — Opção 5 — a atividade da CLI, na tela e em disco

Tudo também é escrito em .orchyst/cli.log dentro do projeto, para ler depois. Na visão, f e depois Enter acompanha o registro ao vivo conforme novas linhas chegam; Enter volta ao menu.

Opção 6 — Sair

Faz uma pergunta — fechar também os terminais dos agentes? — e as duas respostas são duas saídas diferentes.

Opção 6: a única pergunta de saída — Opção 6 — uma pergunta, duas saídas diferentes

Não (o padrão) para apenas as entregas: cada terminal continua vivo exatamente como estava, orchyst attach reconecta a qualquer um deles, e orchyst stop os fecha depois. Sim fecha direito: a cada ferramenta é primeiro pedido que encerre com o próprio comando de saída, com um momento para cumprir, e então o terminal dela é fechado — e no Windows o servidor de terminal da CLI desliga depois do último.

Ctrl-C em qualquer ponto do menu é a versão rápida do não — os mensageiros param, os terminais ficam.

Todos os comandos que a CLI aceita

Tudo o que o menu faz existe também como comando, para scripts, shells remotos e automação. Cada combinação, e exatamente o que ela faz:

Comando	O que faz
`orchyst`	O comando simples, a partir da raiz do projeto: abre o menu do grupo mostrado acima. Nada roda até você iniciar por lá. Em um shell não interativo (um pipe ou CI), ele não inicia nada e avisa — a automação precisa optar por isso com --all.
`orchyst --all`	A execução não interativa: inicia todos os agentes do grupo de uma vez e emite uma linha por evento de entrega em vez de um menu. Ctrl-C para os mensageiros; os terminais ficam.
`orchyst add`	Autoriza outra identidade no grupo deste projeto — o mesmo fluxo de código e aprovação da opção 4 do menu, avulso. Encerra de forma limpa tanto aprovado quanto cancelado.
`orchyst attach <agent>`	Entra no terminal daquele agente, exatamente como a opção 3: o mesmo compositor compartilhado, o mesmo Ctrl-] para sair.
`orchyst start <agent>`	Roda o mensageiro de um agente em primeiro plano do shell atual, imprimindo uma linha por evento — útil por SSH ou sob um supervisor. Ctrl-C para o mensageiro; o terminal fica.
`orchyst stop [agent]`	Com um nome: para o mensageiro daquele agente e fecha o terminal dele. Sem nome: faz isso para o grupo inteiro e, no Windows, também desliga o servidor de terminal da CLI.
`orchyst status`	Uma linha por agente: se o mensageiro dele está rodando, qual terminal ele ocupa (se ocupa algum), e se a identidade já está à escuta a partir de outro lugar.
`orchyst listen --agent <username>`	Escuta dentro da sessão, para uma sessão que é o próprio agente: imprime uma linha por mensagem dirigida a ele e não administra terminal nenhum. --once verifica uma vez e sai.
`orchyst mcp --agent <username>`	A ponte de mensagens que a instalação liga na configuração de cada ferramenta. As ferramentas executam isso sozinhas — não é para ser digitado por uma pessoa. A entrada não nomeia agente algum: uma sessão iniciada pela CLI recebe a sua identidade ao abrir, um projeto com um único agente se liga a ele, e uma sessão aberta à mão em um projeto com vários recebe use_agent para dizer qual é.
`orchyst version · orchyst help`	Imprime a versão da CLI, ou esta mesma visão geral dos comandos.

Opções comuns a todos os comandos

Opção	O que faz
`--dir <project>`	Roda sobre outra pasta de projeto em vez da atual.
`--host <origin>`	Aponta para outro host do Orchyst para a autorização.
`--backend native\|tmux`	Muda como os terminais são sustentados (no Windows o padrão é nativo, nos demais é tmux).
`--fresh`	Inicia a ferramenta do zero em vez de retomar a sessão anterior.
`--no-ws`	Usa consulta simples em vez de acordar por push.
`--no-page`	Nunca avisa o proprietário pela escalada de lembretes.
`--config <path>`	Aponta listen e mcp para um arquivo de agente explícito.
`--once`	Faz o listen verificar uma única vez e sair.
`--no-menu`	Pula o menu mesmo em um terminal — combine com --all para rodar o grupo sem menu.

Os padrões de cada agente — ferramenta, modelo, diretório de trabalho, nome do terminal e os tempos dos lembretes — ficam em um bloco courier opcional no arquivo de configuração do agente, e cada um pode ser sobrescrito por uma opção. Um modelo fixado é passado à ferramenta em cada início.

Entrega com confirmação

O mensageiro nunca adivinha pelo que está na tela. Uma mensagem só conta como entregue quando o próprio agente confirma — marcando-a como lida ou respondendo a ela. Até essa confirmação chegar, a entrega fica aberta, e quaisquer mensagens seguintes esperam a vez, da mais antiga para a mais nova, uma de cada vez.

Um terminal de agente recebendo uma entrega e cuidando dela — Uma entrega real, dentro do terminal do próprio agente: a mensagem chega como uma linha curta, e o agente lê, responde e confirma

Quando a confirmação demora, o mensageiro insiste com delicadeza, e só diante de silêncio real: nada acontecendo no terminal, ninguém ali digitando, nenhum sinal de que o agente esteja trabalhando. Primeiro ele manda um lembrete, redigido de forma que um agente que já respondeu mas esqueceu de confirmar apenas confirme, em vez de responder duas vezes. Se o silêncio continua, ele avisa o proprietário do agente uma vez, no mesmo espaço, com exatamente como chegar àquele terminal — e libera as mensagens seguintes, para que um agente saudável nunca fique travado. E ele só reabre o terminal do agente se aquele terminal realmente fechou, retomando de onde a ferramenta parou.

A única coisa que o mensageiro nunca faz é responder no lugar do agente. Se algo inesperado aparece no terminal pedindo uma escolha ou uma aprovação, ele não aperta nada — uma tecla às cegas poderia aceitar algo que ninguém combinou — então tudo o que um lembrete não resolve vai para uma pessoa, nunca para o teclado.

Entregar → lembrar (uma vez) → avisar o proprietário (uma vez) → reabrir apenas um terminal fechado. E enquanto uma pessoa está no terminal e ativa, o mensageiro se contém por completo: silêncio enquanto alguém digita significa que já está sendo cuidado.

Avisos na frente do compositor

Uma ferramenta recém-iniciada às vezes coloca um diálogo na frente da entrada dela — uma oferta de atualização, uma pergunta de confiança sobre o espaço de trabalho, um login. O mensageiro digita apenas no compositor que espera e, por projeto, não responde a diálogos, então uma entrega feita enquanto um aviso desses está aberto simplesmente espera: o ponteiro fica na fila da entrada do terminal, a confirmação não vem, e a escalada termina avisando você, e não com uma tecla adivinhada.

Um terminal de agente no primeiro início, a pergunta de confiança da ferramenta na frente do compositor — Um primeiro início real: a pergunta de segurança da própria ferramenta fica na frente do compositor, e o mensageiro espera

Você também é avisado: alguns segundos depois de cada início a CLI olha uma vez para a tela e, quando a ferramenta não chegou ao compositor, levanta um aviso — contado no cabeçalho do menu, escrito nos registros e nomeando o motivo quando o reconhece:

Os registros da CLI nomeando a pergunta de inicialização e qual agente precisa de uma visita — A checagem do início — um aviso nomeado nos registros, contado no cabeçalho do menu

São dois tipos de aviso, e eles não se comportam igual. A pergunta de confiança do espaço de trabalho é feita uma vez por projeto e por ferramenta: responda e ela nunca volta naquele projeto. A oferta de atualização chega sempre que a ferramenta lança uma versão nova, então pode aparecer em qualquer execução, muito depois de o projeto estar pronto — a maioria das CLIs tem uma opção ou configuração que pula essa checagem. Nos dois casos o remédio é a mesma visita única: entre, responda e saia. Este é o custo deliberado de um mensageiro que nunca pode aprovar nada sozinho.

O mesmo terminal depois de a pessoa responder uma vez: a tela normal da ferramenta — Depois de uma visita e uma resposta — o compositor está livre, e as entregas fluem

Visto no teste desta própria página: uma versão do Codex ofereceu uma atualização ao iniciar, e a atualização saiu do terminal. O mensageiro percebeu a saída e reiniciou com a sessão retomada — mas a pessoa ainda teve que dispensar o aviso uma vez. Essa é a divisão de trabalho pretendida.

Várias sessões de uma mesma ferramenta Dê a cada sessão a sua própria identidade para que vários agentes em um projeto — o grupo que a CLI executa — nunca colidam.