Sessões do Agente de IA

Este capítulo aborda o diferencial principal do VelaTerm: hospedar agentes de codificação de IA como sessões tipadas — com status em tempo real, retomada automática da conversa, criação de ramificações e controle de permissões.

1. Agentes suportados

Nove tipos de agentes locais estão disponíveis nos menus de Nova Sessão: Claude Code, Codex, OpenCode, Copilot CLI, Cursor CLI, Antigravity, Cline, Pi e Crush. As funcionalidades variam ligeiramente:

“Autoritativo” significa que o VelaTerm injeta o mecanismo oficial de callback do agente (ganchos / plugin / extensão) na inicialização, de modo que as alterações de estado são relatadas ativamente pelo agente, em vez de serem deduzidas a partir da saída do terminal. Para agentes que não relatam tudo (codex, crush), uma solução alternativa de detecção de tela preenche as lacunas. Os agentes que você executa diretamente em um terminal comum não são afetados — a injeção aplica‑se apenas às sessões iniciadas pelo VelaTerm.

2. Pontos de status: quem está trabalhando, quem está esperando por mim

O ponto ao lado de cada sessão de agente é atualizado em tempo real: verde = trabalhando; amarelo = precisa de você (pergunta, solicitação de permissão ou notificação não lida); magenta = já foi respondido e visto. Os três contadores na barra de status são filtros clicáveis — com vários agentes em execução, é assim que você encontra aqueles que estão esperando por você.

Em conjunto com as notificações do sistema: quando um agente para por sua causa (uma pergunta ou fim de turno), você recebe uma notificação, a sessão ganha um selo de “não lido” e o selo do Dock conta isso; se você já estiver olhando para aquela sessão, nada é disparado. Na versão assinada do macOS, clicar em uma notificação leva diretamente à sessão. O item “Notificar” na barra de status é o botão de ativação global.

3. Retomada automática: feche, abra novamente, a conversa continua lá

O modelo mental em uma linha: cada nó de sessão de agente na árvore = uma conversa em andamento.

• Na primeira execução, o VelaTerm lembra automaticamente o id da sessão do agente.
• Depois disso — seja você tendo fechado a aba ou encerrado o aplicativo — ao reabrir o nó, o agente é reiniciado com seu flag de retomada (por exemplo, claude --resume <id>) e o contexto volta imediatamente. Antes de retomar, o VelaTerm verifica se a conversa ainda existe; se foi excluída, ele recua silenciosamente para um início limpo em vez de travar.
• Quer uma conversa nova? Crie um novo nó. Todo o mecanismo é automático — sem interruptores, sem limpeza.

Retomada manual: se você tiver um id de sessão de agente de outro lugar (por exemplo, uma conversa que executou em um terminal comum), use “Retomar Sessão…” na parte inferior do menu Nova Sessão — escolha o tipo, cole o id e aquela conversa se junta à árvore como um nó de sessão válido.

4. Criação de ramificação: ramifique a conversa atual

Clique com o botão direito em uma sessão claude / codex / pi que tenha uma conversa → “Criar Ramificação de Sessão”. Você obtém um nó irmão que se ramifica a partir do histórico atual da conversa original, deixando a original intacta — pense em um branch do git. Ótimo para “mesmo contexto, experimente duas abordagens”.

5. Modos de permissão e argumentos de inicialização

Permissões de dois níveis: cada sessão suportada pode rodar em “Padrão” (confirmação passo a passo) ou “pular todas as confirmações de permissão” — também conhecido como modo YOLO, que inicia o agente com seu flag correspondente (por exemplo, --dangerously-skip-permissions do Claude). Ative ou desative por sessão por meio de “Pular todas as confirmações de permissão” no formulário de edição da sessão; defina o padrão global por tipo em Configurações ▸ Agentes.

Argumentos de inicialização personalizados: o campo “Argumentos de inicialização” no formulário de edição da sessão adiciona argumentos de linha de comando extras para aquela sessão; Configurações ▸ Agentes mantém um modelo padrão por tipo, e “Novo com argumentos de inicialização…” no menu Nova Sessão permite criar uma sessão parametrizada de uma única vez.

Caminho executável: se um agente estiver instalado fora do PATH, defina seu “Caminho executável” por tipo em Configurações ▸ Agentes; deixe vazio para que o comando seja procurado no PATH.

6. Não está instalado? Orientações de instalação

Iniciar um agente que não está instalado não leva a um impasse em command not found: aparece um cartão de orientação de instalação na sessão com o comando de instalação recomendado para seu SO — copie‑o ou execute‑o no local com um clique. Após a instalação, a localização do binário é detectada automaticamente e preenchida na configuração de caminho, e um botão de tentar novamente reinicia a sessão. Lembre‑se de que cada agente ainda precisa de sua própria configuração de login/chave API; o cartão leva aos documentos.

7. Painel de informações: modelo, uso e recursos

Quando uma sessão de agente está aberta, a guia Informações no painel direito exibe os detalhes de execução:

• AGENTE: nome da sessão, tipo, estado de execução, diretório de trabalho, Gitbranch, horário de início e tempo de atividade.
• MODELO / Esta rodada (Claude): modelo atual, uso do contexto e ferramenta em execução.
• USO (Claude / Codex): uso da cota oficial (janelas de 5 horas e 7 dias); o intervalo de atualização é configurável (Atualização de uso).
• RECURSOS: CPU/memória medidos da árvore de processos da sessão.

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

• Clique com o botão direito → "Exportar Sessão…" (claude / codex, exibido uma vez que a conversa foi capturada) grava todo o contexto em Markdown — incluindo o raciocínio do assistente e todas as chamadas de ferramenta com seus inputs e resultados.
• As sessões de agentes arquivadas podem ser lidas como transcrições analisadas no painel de arquivamento (não é necessário reproduzir no terminal); ao restaurá-las, é possível retomar o uso normal. Consulte Gerenciamento de Interface e Sessões §7.

9. Diversos

• Nomeação automática: sessões sem nome recebem seu nome a partir da sua primeira mensagem (claude e outros).
• Temas dinâmicos: a alteração entre modos claro/escuro atualiza instantaneamente as aparências das sessões do claude, sem necessidade de reiniciar.
• Habilidades Vela: a opção "Habilidades Vela" em Configurações ▸ Geral instala as habilidades /vspawn, /vspawn-tree e /vopen em ~/.claude/skills/, permitindo que o claude crie sub-sessões e abra documentos dentro de uma conversa (consulte Criação de Sessões e Git Colaboração).
• Windows: claude / codex têm suporte total (por meio de PowerShell); os outros tipos têm suporte limitado.