Sessões do Agente de IA

Este capítulo explica como o VelaTerm executa agentes de programação com IA em sessões dedicadas: agentes compatíveis, status em tempo real, retomada automática de conversas, importação e bifurcação de conversas, modos de permissão, configurações de inicialização, orientações de instalação e o painel Informações. A visão de conversa tem um capítulo próprio: Visão de Conversa.

1. Agentes compatíveis

O VelaTerm pode iniciar estes agentes: Claude Code (exibido como "Claude"), Codex, OpenCode, Copilot, Cursor, Antigravity, Cline, Pi, OMP, Crush, Kimi Code, Kiro, Grok Build e Zoo Code. A CLI de cada agente precisa estar instalada e autenticada.

Os recursos variam conforme o agente:

• Informado pelo agente significa que o próprio agente avisa o VelaTerm quando começa a trabalhar, quando precisa de você e quando termina, por isso o status é exato. O Codex informa todas as etapas quando a versão instalada oferece suporte a hooks de ciclo de vida; versões mais antigas do Codex informam apenas o fim de cada turno. Quando a coluna "Precisa de você" mostra ✗, o agente não informa perguntas nem pedidos de permissão, e a sessão aparece como "Em andamento" até o fim do turno.
• Lido da tela significa que o VelaTerm reconhece o estado do agente pela interface de terminal dele.
• Para Copilot, Cursor, Antigravity, Kimi Code, Kiro e Grok Build, o VelaTerm adiciona entradas próprias à configuração de usuário do agente na primeira vez que você inicia uma sessão desse tipo. Essas entradas não têm efeito quando o agente é executado fora do VelaTerm.
• Os agentes que você mesmo inicia em um terminal comum não são afetados; o informe de status vale apenas para as sessões de agente iniciadas pelo VelaTerm.

2. Como criar uma sessão de agente

• Menu de contexto. Clique com o botão direito em um projeto, grupo ou sessão. O primeiro nível do menu oferece três agentes: no início, Claude, Codex e OpenCode; depois, os três tipos de agente que você criou mais recentemente. "Mais sessões de agente" lista todos os agentes, suas predefinições salvas, "Novo com argumentos…" e "Nova sessão de agente" (o seletor com busca).
• Seletor de nova sessão de agente. ⌘N no macOS (Ctrl+Alt+N no Windows, no Linux e em navegadores comuns) abre uma lista pesquisável de agentes e predefinições, com as escolhas recentes marcadas como "Último usado". Consulte Configurações e Atalhos §9.
• Sessões filhas. O submenu "Nova sessão filha" de uma sessão cria a nova sessão abaixo dela. As sessões também podem ser iniciadas de dentro de uma conversa; consulte Criação de Sessões e Colaboração no Git.

Novo com argumentos… abre uma caixa de diálogo com o tipo de agente ("Tipo de agente"), um nome opcional ("Nome da sessão (vazio = automático)"), "Argumentos de inicialização (opcional)", "Executável (opcional)" para um executável substituto usado apenas por essa sessão, a configuração de permissão, "Abre em" ("Visão de terminal" ou "Visão de conversa") para os agentes compatíveis com as duas visões e uma opção "Worktree". "Salvar como predefinição" guarda as configurações com um nome e, opcionalmente, um ícone. As predefinições aparecem no menu e no seletor e são iniciadas com o executável, os argumentos e a configuração de permissão salvos.

As sessões de Claude, Codex, OpenCode, Pi e OMP abrem na visão de conversa por padrão; os demais agentes abrem na visão de terminal. Configurações ▸ Agentes ▸ "Visão padrão" altera isso para cada agente.

3. Pontos de status: quem está trabalhando e quem precisa de você

O ponto ao lado de cada sessão de agente é atualizado em tempo real:

Quando um agente para e fica aguardando você (uma pergunta, uma solicitação de permissão ou o fim de um turno), você recebe uma notificação do sistema, a sessão é marcada como não lida e o marcador no ícone do Dock passa a contá-la. Se você já estiver olhando para essa sessão, nenhuma notificação aparece. Na versão assinada para macOS, clicar em uma notificação abre a sessão. O item "Notify: On/Off" da barra de status ativa ou desativa as notificações do sistema; as marcas de não lida e os marcadores continuam. Quando há marcadores, o cabeçalho da barra lateral mostra um botão que limpa todos eles.

Os contadores "Em andamento", "Pendente" e "Visto" da barra de status filtram a barra lateral para mostrar as sessões nesse estado; consulte Gerenciamento de Interface e Sessões §6.

4. Retomada automática: feche, reabra e a conversa continua

O modelo mental em uma linha: cada nó de sessão de agente na árvore é uma conversa contínua.

• Na primeira execução, o VelaTerm memoriza o ID da conversa do próprio agente.
• Depois disso, quer você tenha fechado a aba ou saído do aplicativo, abrir o nó novamente dá continuidade à mesma conversa. Antes de retomar, o VelaTerm verifica se a conversa ainda existe; se ela tiver sido excluída, a sessão começa do zero em vez de falhar.
• Para uma conversa nova, crie um novo nó de sessão. Na visão de conversa, /clear substitui a sessão por uma nova sessão vazia no mesmo lugar.

Retomar sessão…, no fim do menu Nova sessão, adiciona uma conversa que você já tem, por exemplo uma que foi executada em um terminal comum. Escolha o "Tipo de agente", cole o ID da conversa do agente e escolha "Retomar e abrir". Todos os tipos de agente do §1 podem ser retomados dessa forma.

Importar sessões…, no menu de contexto de um projeto, lista as conversas existentes de Codex, Claude, OpenCode e Kiro cujo diretório de trabalho é exatamente o diretório do projeto. Use a busca ("Pesquisar por título, agente ou ID da sessão"), selecione as linhas e escolha "Importar". As conversas entram na árvore do projeto; abra uma delas para continuá-la. A importação não copia nem altera o histórico do próprio agente. As conversas que já estão no VelaTerm, incluindo as arquivadas, aparecem marcadas como "Já importada". As conversas em subdiretórios ou em worktrees separados só aparecem quando o diretório correspondente é aberto como um projeto próprio. O histórico do Kiro pode ser visualizado nos registros que contêm apenas texto. Quando você está conectado a um VelaTerm remoto, a lista vem do computador remoto.

5. Bifurcação: derive uma nova conversa

Nas sessões de Claude, Codex, Pi e OMP que já têm uma conversa, clique com o botão direito → "Bifurcar sessão". Isso cria um nó irmão que começa com o histórico atual da conversa de origem e deixa a origem inalterada, de forma semelhante a uma branch do Git. Use esse recurso para testar duas abordagens a partir do mesmo contexto.

6. Permissões

As configurações de permissão definem o quanto o agente pode fazer sem perguntar a você.

• Claude, Codex e OpenCode têm modos nomeados. Claude: "Modo plano", "Sempre perguntar", "Aceitar edições", "Modo automático", "Sem perguntar". Codex: "Somente leitura", "Modo automático", "Acesso total". OpenCode: "Sempre perguntar", "Sem perguntar".
• Copilot, Cursor, Antigravity, Cline, OMP, Crush, Kimi Code, Kiro, Grok Build e Zoo Code têm uma única opção, "Pular todas as confirmações de permissão", que inicia o agente com a opção dele para ignorar confirmações. Na visão de conversa, o OMP oferece "Sempre perguntar" e "Sem perguntar".
• Pi executa ferramentas sem perguntar, por isso não tem configuração de permissão.

Onde alterar:

• Por sessão: no formulário "Editar" da sessão ("Permissão" ou a caixa de seleção "Pular todas as confirmações de permissão"); na visão de terminal, no item de permissão da barra de status ("Permissões: Perguntar" / "Permissões: Ignorar" ou o nome do modo atual); na visão de conversa, no controle de permissão abaixo da caixa de mensagem.
• Padrão para novas sessões: Configurações ▸ Agentes ▸ "Permissão". Os menus da barra de status e da visão de conversa também oferecem "Definir como padrão".

Algumas alterações só têm efeito depois que o agente é reiniciado. Nesse caso, o VelaTerm oferece "Reiniciar agora" ou "Mais tarde"; reiniciar retoma a conversa, mas interrompe uma tarefa em andamento. "Sem perguntar", "Acesso total" e "Pular todas as confirmações de permissão" ignoram todas as confirmações, então use essas opções com cuidado.

7. Configurações de inicialização e orientações de instalação

Argumentos de inicialização. O formulário "Editar" da sessão tem "Argumentos de inicialização (opcional)", que adiciona argumentos de linha de comando a essa sessão. Configurações ▸ Agentes guarda um valor padrão para cada tipo de agente.

Caminho do executável. Se um agente estiver instalado fora do seu PATH, defina o "Caminho do executável (opcional)" dele em Configurações ▸ Agentes. Quando o campo está vazio, o comando é procurado no PATH.

Agente não instalado? Ao iniciar um agente que não está instalado, a sessão mostra um cartão "<Agent> não está instalado", com o comando de instalação recomendado para o seu sistema.

• "Instalar agora" executa o comando na sessão. Quando o programa instalado é encontrado, o caminho dele é salvo nas Configurações, e uma caixa de diálogo oferece "Reiniciar agora" ou "Mais tarde".
• "Tentar novamente" inicia a sessão de novo, por exemplo depois que você mesmo instalou o agente.
• Se o agente já estiver instalado fora do PATH, informe o caminho completo em "Caminho do executável" e escolha "Usar este caminho", ou use "Procurar…".
• "Documentação" abre a documentação de instalação do agente; "Faço eu mesmo" fecha o cartão.

Mesmo depois da instalação, cada agente ainda precisa do próprio login ou de uma chave de API.

8. O painel Informações: uso, contexto e recursos

Com uma sessão de agente aberta, a aba Informações do painel direito mostra:

• Agente: o tipo de agente, o nome da sessão, o diretório de trabalho, a branch do Git, o horário de início e o tempo de execução. Nas sessões do Kiro, também há um link para uma visualização somente leitura do histórico da conversa.
• Uso (Claude, Codex, Grok Build): o consumo da cota da conta, por exemplo nas janelas de cinco horas e de sete dias, com os horários de redefinição. O botão ↻ atualiza os dados imediatamente. A atualização automática e o intervalo dela são definidos em Configurações ▸ Comportamento ("Usage auto-refresh", "Usage refresh"). Quando uma atualização falha, os últimos valores continuam visíveis com a marca "stale".
• Este turno (Claude, Codex, Grok Build, OpenCode, Pi, OMP, Kiro): o modelo, o nível de ocupação da janela de contexto e as contagens de tokens e as ferramentas do turno atual.
• Recursos: CPU e memória dos processos da sessão; a opção "system" acrescenta os números do computador inteiro.

9. Transcrições, exportação e arquivamento

• Clique com o botão direito → "Exportar sessão…" (Claude e Codex, quando já existe uma conversa) para gravar a conversa completa em um arquivo Markdown, incluindo o raciocínio e cada chamada de ferramenta com a entrada e o resultado.
• "Organizar na base de conhecimento de sessões", no menu da sessão, faz com que um agente extraia conhecimento reutilizável da conversa; consulte Base de Conhecimento de Sessões.
• As sessões arquivadas podem ser lidas na visualização "Sessões arquivadas" da base de conhecimento. As conversas de Claude, Codex, OpenCode, Pi, OMP, Grok Build e Kiro aparecem como mensagens; para os outros agentes, é exibida a gravação do terminal, quando existe. Restaurar uma sessão arquivada mantém o ID da conversa, então ela é retomada normalmente. Consulte Gerenciamento de Interface e Sessões §8.

10. Outros comportamentos

• Nomes automáticos: uma sessão que você não nomeou recebe o nome a partir da sua primeira mensagem.
• Mudança de tema: alternar entre claro e escuro atualiza as sessões Claude em execução na visão de terminal sem reiniciá-las.
• Vela Skills: Configurações ▸ Geral ▸ "Vela Skills" instala habilidades para Claude Code e Codex que iniciam sessões filhas, abrem arquivos e leem outras sessões ou enviam mensagens a elas; consulte Comandos de Sessão.
• Windows: Claude Code e Codex têm suporte completo (são executados no PowerShell); os demais agentes são oferecidos sem garantia de suporte completo.