Trabalhar com agentes de IA

A automação do Zshell é voltada principalmente a agentes de programação com IA. Ela oferece uma forma segura de trabalhar com painéis e coordenar outros agentes; você não precisa aprender outra linguagem de comandos.

A integração vem ativada. Converse normalmente com seu agente. Ele pode criar um painel em segundo plano, iniciar um executor delegado, executar um comando, aguardar o resultado e trazer a resposta sem tirar o foco do painel em uso.

Aguardar resultados de comandosCopiar link

Para comandos que terminam, como testes ou compilações, seu agente pode aguardar o próprio código de saída e a duração do comando e ler a saída recente salva do terminal. Se o tempo de espera expirar, o comando continua executando e é possível aguardar a mesma tarefa novamente, sem mudar o foco. É necessário um prompt vazio no zsh local original iniciado pelo Zshell; shells aninhados, SSH e programas de inicialização personalizados não são compatíveis. A saída recente é limitada e pode incluir comandos ou prompts anteriores. Peça ao agente para salvar a saída completa em um arquivo quando necessário.

Chamadas diretas a exit, logout e exec são rejeitadas porque encerram ou substituem o shell original; use /bin/sh -c para executá-las em um subprocesso.

ConfiguraçãoCopiar link

Confira Ajustes → Automação → IA. A opção vem ativada; se você a desativou, ative novamente e abra um terminal novo ou reinicie o agente que já estava rodando.

O Zshell suporta Codex, Claude Code, Gemini CLI, Grok Build, OpenCode, Cursor Agent, Aider, Amp e Pi. Se encontrar uma configuração de agente que conflite com o recurso, ele mantém a configuração existente, devolve a opção ao estado anterior e mostra o erro nos Ajustes.

Peça em linguagem naturalCopiar link

Diga ao agente o resultado esperado. Por exemplo:

Execute os testes relevantes em um painel de fundo e me diga quais falham.

Delegue este bug a outro agente Codex e depois revise o resultado.

Pergunte ao agente da API se o esquema está pronto e passe a resposta ao agente dos testes.

Inicie o servidor de desenvolvimento ao nosso lado, espere ficar pronto e me dê a URL.

Veja se o agente em segundo plano terminou. Se estiver bloqueado, diga do que precisa.

O agente usa a interface de automação do Zshell por você. Não é necessário digitar nem memorizar comandos de automação.

Coordenação entre painéisCopiar link

Você pode dividir tarefas relacionadas entre vários painéis e pedir que seu agente principal coordene o trabalho. Um agente pode cuidar da API enquanto outro atualiza testes. O coordenador pode pedir resultados a um executor específico, enviar um complemento, repassar informações úteis a outro e trazer a resposta combinada. Os executores podem usar ferramentas de programação diferentes, desde que compatíveis.

Isso elimina o copiar e colar na execução paralela. Cada agente mantém sua conversa em seu próprio painel, enquanto o coordenador repassa apenas a pergunta, atualização ou resultado necessário ao outro.

Enviar uma solicitação adicional não significa concluir o trabalho. O coordenador ainda aguarda o executor, lê o resultado e o verifica. Uma mensagem de outro agente nunca equivale à sua aprovação. Permissões, credenciais, decisões de confiança e ações destrutivas continuam voltando a você.

Continue trabalhando durante a execuçãoCopiar link

Painéis delegados ficam em segundo plano até você pedir para vê-los. Quando a integração nativa de ciclo de vida do provedor informa o estado, o Zshell o exibe no painel e na aba do agente:

Zshell prioriza eventos nativos de Codex, Claude Code, Pi, OpenCode e Grok, seguidos de relatórios explícitos dos programas. Passe o cursor pelo indicador ou abra Agents para ver origem, motivo da espera, porcentagem e subtarefas. Os hooks do Codex precisam ser revisados e considerados confiáveis em /hooks; Zshell não ignora essa etapa.

Sem relatório nativo, apenas uma parte limitada do rodapé da tela atual de um agente reconhecido é analisada. A inferência de tela é identificada, não informa conclusão, não envia notificações e não satisfaz zshell +agent wait. Ela não concede aprovação. Verifique o painel e o resultado real.

Programas informam progresso com zshell +agent report e removem seu próprio relatório com zshell +agent clear. O relatório expira após 120 segundos sem atualização ou quando seu processo termina.

Quando uma integração informa conclusão ou necessidade de entrada, o Zshell também pode notificar. Pressione Cmd+Shift+A para ir ao próximo agente que informou precisar da sua atenção.

Uso e limites da contaCopiar link

Ajustes → Automação → Uso da Conta mostra limites disponíveis de Claude Code e Codex, incluindo porcentagem usada, horário de renovação quando informado e horário da última atualização. Use Atualizar Uso para recarregar os dados mais recentes disponíveis.

O Codex precisa de um CLI instalado, autenticado e capaz de informar limites. O uso do Claude Code aparece quando o Zshell recebe um relatório do provedor pela linha de status. A seção só aparece com dados disponíveis; os períodos dependem do provedor e da conta. São limites da conta, não o total de tokens da sessão em foco.

Um fluxo comumCopiar link

1. Inicie seu agente habitual em um terminal Zshell.
2. Peça para delegar uma tarefa delimitada, executar algo em segundo plano ou coordenar outro agente.
3. Continue no painel atual enquanto o trabalho delegado permanece visível no layout do projeto.
4. Acompanhe os indicadores Trabalhando, Bloqueado ou Concluído quando o provedor os fornecer. Caso contrário, abra o painel para examinar a conversa ou saída do terminal.
5. Revise os arquivos no painel Git, confira o diff e decida o que manter.

Você mantém o controleCopiar link

• A automação fica no projeto Zshell atual e não alcança painéis de outro projeto ou janela.
• Trabalho em segundo plano não toma o foco sem seu pedido explícito.
• O Zshell não responde por você a solicitações de permissão, credenciais, confiança ou ações destrutivas. Um agente bloqueado conforme o provedor devolve a decisão a você.
• Conclusão informada é um sinal para revisar, não aprovação automática das alterações.

Se o agente não usar o ZshellCopiar link

• Confirme que Ajustes → Automação → IA está ativado.
• Abra um terminal Zshell novo se o atual já existia antes da ativação.
• Reinicie o agente que estava rodando quando você ativou a opção.
• Confira os Ajustes para erros de configuração mostrados junto ao controle.
• Peça explicitamente um “painel Zshell em segundo plano” ou um “agente Zshell delegado” para usar esse fluxo na tarefa.

Retomar a conversa originalCopiar link

Com Retomar conversas de agentes, um painel cujo PTY original está indisponível retoma a conversa registrada de Claude Code, Codex, Pi ou OpenCode. Painéis no mesmo diretório mantêm suas próprias conversas.

O Zshell instala hooks SessionStart para Claude Code e Codex, uma extensão Pi e um plugin TUI do OpenCode na configuração existente. Outros hooks, plugins, ajustes e comentários JSONC são preservados. Quando solicitado pelo provedor, ative os hooks na confirmação de confiança do Claude Code e aprove os novos hooks do Codex em /hooks. Reinicie agentes que já estavam em execução.

Somente conversas raiz verificadas informadas pelas integrações são retomadas. As sessões compartilhadas do app-server do Codex são suportadas quando um ID de conversa verificado corresponde ao painel; correspondências ambíguas ficam sem vínculo. Para conversas em hosts remotos, consulte sessões remotas compartilhadas. O OpenCode requer a API de plugins TUI; versões antigas, sessões de servidor sem interface e opencode attach não são suportados. Um agente filho não substitui a conversa do painel pai. O Pi precisa do arquivo de sessão salvo.

Sem identidade verificada, diretório original ou arquivo Pi, abre-se um novo shell. Se o CLI não for encontrado, também se retorna ao shell. O Zshell não repete comandos de início arbitrários nem escolhe a conversa mais recente. Erros do provedor, como conversas excluídas, aparecem no CLI.

Encontrar e retomar conversas salvasCopiar link

Abra Agentes → Histórico de conversas dos agentes, clique no relógio no topo da barra lateral de projetos. Pesquise entre projetos por título, provedor, projeto, ID da conversa ou diretórios de trabalho e configuração. O Zshell mantém as 200 conversas locais verificadas mais recentes após fechar agentes e painéis e reiniciar o app. Recentes mostra 20 resultados não arquivados; Todas inclui os arquivados; Arquivadas mostra somente estes.

Escolha Mostrar conversa se ela estiver aberta ou Retomar conversa se estiver salva. O Zshell reutiliza um painel aberto, reconecta um PTY ainda ativo ou retoma a conversa exata do provedor com seu diretório e configuração originais. A retomada manual requer integração de IA, mesmo com a restauração automática desativada. Diretórios ausentes e arquivos Pi ausentes ou que não correspondem à conversa geram um erro antes da criação de um painel.

Arquivar oculta o registro em Recentes; Desarquivar o traz de volta. Excluir… remove apenas o registro do Zshell e mantém os arquivos do provedor.

Em um painel Zshell, zshell +agent history --all e zshell +agent resume --id HISTORY_UUID se limitam ao projeto do painel. Em um terminal externo comum, mantenha o Zshell aberto, encontre o UUID do projeto e selecione-o explicitamente:

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

A CLI retoma em segundo plano, a menos que você acrescente --focus. Para um projeto em várias janelas, escolha --window WINDOW_UUID retornado por history projects. Com várias instâncias do app, use --connection PATH com o caminho absoluto do arquivo privado de conexão informado pela CLI. Essas opções são para terminais externos; processos dos painéis mantêm seu projeto original.

Acompanhar eventos do projetoCopiar link

Execute zshell +events em um terminal Zshell para receber em NDJSON as mudanças futuras do projeto e da janela desse terminal, sem consultas periódicas. Opções: --pane UUID, --event NAME repetível, --once e --timeout MS (0 aguarda indefinidamente).

Inclui criação e fechamento de sessões e painéis, foco, progresso, atenção e conclusão de agentes e comandos concluídos. stream.ready começa em sequence 0; cada evento correspondente incrementa a sequência. Cada linha contém version, event, stream_id, sequence, time em milissegundos Unix, project_id e data. Não há repetição do histórico. Leia os resultados com +pane wait --task UUID.

Limites: 32 assinaturas, 256 quadros e 1 MiB por fila, 64 KiB por quadro. Um leitor lento recebe stream.lagged quando possível e é desconectado; dois segundos sem escrita também fecham a conexão. Atraso, desconexão inesperada ou erro de sequência encerram com código diferente de zero. Assine novamente e leia o estado atual. Fechar o terminal, renovar o token ou mover para outro projeto ou janela encerra a assinatura. Sem controle externo nem --project; remover variáveis não amplia permissões. --once sem correspondência retorna 124 no tempo limite; o limite normal retorna 0.

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

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