Gerenciamento de Interface e Sessões

Este capítulo trata do modelo de organização do VelaTerm: o layout da janela, o gerenciamento da árvore, o comportamento das abas e dos painéis divididos, os pontos de status e a filtragem, o arquivamento, a busca global e o salvamento do espaço de trabalho ao sair. Os demais capítulos partem desses conceitos.

1. O layout

Acesso remoto e Conectar a servidor remoto aparecem no aplicativo desktop; consulte Desenvolvimento e Gerenciamento Remoto. Feedback abre a página de feedback do VelaTerm no navegador. No Windows e no Linux, pressionar Alt mostra uma barra de menus com Arquivo, Terminal e Ajuda.

Os dois painéis laterais podem ser ocultados pelos botões da barra de título e redimensionados arrastando as bordas.

2. A árvore: projetos, coleções, grupos e sessões

• Um projeto é um diretório no disco e a raiz de uma subárvore. Para criar um, use "Criar projeto" (cria uma nova pasta), "Importar projeto" (abre uma pasta existente, ⌘O) ou "Clonar do Git".
• Uma coleção é um contêiner de nível superior sem pasta, para sessões que não pertencem a um único projeto. Para criar uma, use o botão "Nova coleção" na parte inferior da barra lateral.
• Um grupo é um nó de organização e pode ser aninhado em qualquer profundidade.
• Uma sessão é a unidade de trabalho: um agente, uma página de navegador ou um terminal. O diretório de trabalho é, por padrão, a raiz do projeto e pode ser alterado no formulário "Editar" da sessão.

Ao passar o cursor sobre uma linha, aparece um botão ＋ ("Nova sessão" em projetos e grupos, "Nova sessão filha" em sessões) e, em projetos e grupos, também um botão para criar um novo grupo.

A maioria das operações fica nos menus de contexto:

Os menus de projeto e de grupo começam pelos itens de criação:

• "Nova página de navegador" (aplicativo desktop) e "Novo terminal", que abre um terminal temporário nesse diretório (§5).
• Três itens diretos "Nova sessão …" para os agentes usados recentemente e "Mais sessões de agente", com todos os agentes, as predefinições salvas, "Nova sessão de agente" (o seletor com busca) e "Novo com argumentos…".
• "Nova sessão de worktree…" e "Nova sessão de planejamento/execução…"; consulte Criação de Sessões e Colaboração no Git e Planejamento e Execução.
• "Importar sessões…" (somente em projetos) e "Retomar sessão…"; consulte Sessões do Agente de IA §4.

Em seguida, o menu de projeto oferece "Novo grupo", "Marca", "Experimental" (Grafo de código e Auditoria de código), "Informações do projeto" (ou "Informações da coleção"), "Renomear" e "Remover projeto" (ou "Excluir coleção"). O menu de grupo oferece o submenu "Git", "Novo subgrupo", "Mover para um worktree…", "Marca", "Renomear", "Arquivar grupo" e "Excluir grupo".

Os menus de sessão mostram os itens adequados ao tipo e ao estado da sessão:

• "Abrir", "Abrir em nova aba", "Abrir em divisão à direita", "Abrir em divisão abaixo", "Abrir no painel ativo" (§4).
• "Nova sessão filha", "Bifurcar sessão", "Exportar sessão…", "Organizar na base de conhecimento de sessões" e o submenu "Git".
• "Marca", "Informações da sessão" (mantenha Option/Alt pressionada para ver o comando de inicialização completo), "Editar", "Renomear", "Mover para…".
• "Encerrar processo" (enquanto a sessão está em execução), "Arquivar sessão", "Excluir sessão".

Outras operações na árvore:

• Mover: arraste os nós ou use "Mover para…". Uma sessão pode ser movida para dentro de outra sessão e se tornar filha dela.
• Renomear: "Renomear" edita o nome diretamente na árvore. Uma sessão que você não nomeou recebe o nome a partir da sua primeira mensagem.
• Marcas: "Marca" adiciona um marcador emoji a um projeto, grupo ou sessão: 🔥 Urgente, ⭐ Importante, 🐛 Bug, ✅ Concluído, 🚧 Em andamento, 📌 Fixado, 💡 Ideia, ⚠️ Atenção. Escolher novamente o marcador atual o remove.
• Seleção múltipla: ⌘/Ctrl+clique marca ou desmarca sessões, e Shift+clique seleciona um intervalo. O menu de contexto passa a oferecer "Abrir sessões selecionadas", "Organizar sessões selecionadas lado a lado" (de duas a quatro sessões), "Mover selecionados para…", "Arquivar sessões selecionadas" e "Excluir N itens selecionados". Arrastar uma seleção move todos os itens dela.
• O estado de recolhimento dos nós é mantido entre reinicializações.

3. Abas

Configurações ▸ Comportamento ▸ "Abas" define como as sessões são abertas:

• Única (padrão): clicar em uma sessão de agente na árvore reutiliza a aba de sessão atual, como ao seguir um link em um navegador. A aba que você deixa vai para o segundo plano com todos os seus painéis, e os processos dela continuam em execução. As sessões de terminal abrem em abas próprias.
• Múltiplas: cada sessão abre em sua própria aba.

"Abrir em nova aba" sempre abre uma nova aba. Nos dois modos, mudar para outra aba não interrompe nada; fechar uma aba (⌘W ou ×) encerra os processos dela. Para sessões de agente, isso é seguro: a conversa é mantida e, ao abrir o nó novamente, ela é retomada.

As abas em segundo plano aparecem na barra de status como "Fundo N/M"; clique nesse item para trazer uma aba de volta ou encerrá-la. No modo Única, "Background limit" (padrão: 32) define a quantidade máxima delas. Acima desse limite, a aba em segundo plano inativa mais antiga é encerrada automaticamente. Se todas as abas em segundo plano estiverem trabalhando ou aguardando você, o VelaTerm pergunta qual delas deve ser encerrada.

Detalhes da barra de abas:

• ⌘1–9 (Ctrl+1–9 no Windows e no Linux) muda para a aba na posição correspondente. Um clique com o botão do meio fecha a aba.
• O ＋ depois das abas abre um terminal temporário. Os botões à direita abrem um novo terminal, um novo documento, uma aba do navegador integrado (aplicativo desktop) e a Central de jogos.
• O menu de contexto de uma aba tem "Fechar aba", "Fechar outras abas", "Fechar abas à direita", "Fechar todas as abas", "Enviar para segundo plano" (mantém os processos da aba em execução) e os mesmos itens de sessão da árvore.

As abas de documento e de navegador são descritas em Abas de Documento e Navegador.

4. Painéis divididos

Uma aba pode conter vários painéis:

• ⌘D divide à direita e ⌘⇧D divide para baixo (Ctrl+Alt+D e Ctrl+Alt+E no Windows e no Linux); o cabeçalho do painel tem os mesmos botões. O novo painel é um terminal temporário que começa no diretório de trabalho do painel atual.
• Para mostrar uma sessão existente na aba atual, use "Abrir em divisão à direita", "Abrir em divisão abaixo" ou "Abrir no painel ativo" no menu dela, ou arraste-a da barra lateral para o painel central.
• "Organizar sessões selecionadas lado a lado" dispõe de duas a quatro sessões selecionadas em uma única aba.
• As sessões exibidas em outro painel da aba atual ficam destacadas na barra lateral.

Os divisores podem ser arrastados. A manutenção em segundo plano vale para a aba inteira, então sair de uma aba e voltar a ela preserva o layout. ⌘W fecha o painel atual; fechar o último painel fecha a aba.

5. Terminais temporários

"Novo terminal", ⌘T e o ＋ da barra de abas abrem um terminal temporário. Ele existe apenas como aba: nunca se torna um nó da árvore e é descartado ao ser fechado. A aba recebe a marca "temp". Use terminais temporários para comandos rápidos e mantenha o trabalho de longa duração em sessões de agente. O menu de um terminal temporário é curto: "Abrir", "Abrir em nova aba", os itens de divisão, "Renomear", "Informações da sessão" e "Fechar rascunho".

6. Pontos de status e filtragem

O ponto ao lado de cada sessão de agente mostra o estado dela: verde enquanto trabalha, amarelo quando precisa de você e magenta depois que respondeu e você já viu a resposta. A legenda completa está em Sessões do Agente de IA §3.

A barra de status mostra os contadores "Em andamento", "Pendente" (sessões que precisam de você) e "Visto"; um contador sem sessões fica oculto. Clique em um contador para mostrar apenas essas sessões na barra lateral; clique novamente para limpar o filtro.

A barra lateral tem ferramentas próprias:

• A caixa de busca ("Buscar sessões / grupos…") filtra a árvore pelo nome.
• O botão de filtro ("Filtrar por status") seleciona um ou mais estados e, separadamente, uma marca.
• Um filtro de status mantém as sessões que correspondiam a ele no momento em que foi definido, para que a lista não se reorganize enquanto você trabalha. Com "Inclusão dinâmica no filtro de status" (Configurações ▸ Comportamento, ativada por padrão), as sessões que passam a corresponder ao filtro são adicionadas. "Atualizar filtro de status", na parte inferior da barra lateral, verifica novamente todas as sessões; "Atualizar status", no menu de uma sessão, verifica apenas essa sessão.
• "Dividir a visualização em árvore abaixo", na parte inferior da barra lateral, adiciona uma segunda visualização da árvore com busca e filtros próprios, por exemplo uma para as sessões que precisam de você e outra para a árvore completa. Cada visualização adicional pode ser fechada.

7. Painel direito

• Arquivos: a árvore de arquivos do diretório de trabalho da sessão. Clique duas vezes em um arquivo para abri-lo em uma aba de documento.
• Informações: detalhes da sessão, uso da conta, o turno atual e o uso de recursos; consulte Sessões do Agente de IA §8.
• Git: branch, alterações preparadas e não preparadas, arquivos não rastreados, criação de commits e o histórico de commits.
• Base de conhecimento: a base de conhecimento de sessões, as sessões arquivadas e suas bases de conhecimento locais; consulte Bases de Conhecimento Locais e Base de Conhecimento de Sessões.

8. Arquivamento: guardar em vez de excluir

O trabalho concluído não precisa ser excluído. Clique com o botão direito em uma sessão → "Arquivar sessão" para ocultá-la: a sessão e as filhas dela saem da árvore e os processos delas são encerrados, mas todos os dados são mantidos. "Arquivar grupo" arquiva todas as sessões de um grupo, e "Arquivar sessões selecionadas" arquiva uma seleção.

As sessões arquivadas ficam na base de conhecimento. Para abri-las, use o botão "Sessões arquivadas" no cabeçalho da barra lateral. Elas são agrupadas por projeto, e a caixa de busca ("Buscar conteúdo arquivado…") pesquisa o conteúdo delas. Para cada sessão arquivada:

• A conversa pode ser lida. As sessões de agente mostram suas mensagens; quando não há conversa disponível, a gravação do terminal é exibida, se existir. Uma segunda aba lista as entradas de conhecimento geradas a partir da sessão.
• "Restaurar como sessão normal" devolve a sessão ao seu lugar na árvore com o ID da conversa intacto; assim, ao abri-la, a conversa original é retomada.
• "Organizar na base de conhecimento de sessões" extrai dela conhecimento reutilizável.
• "Exportar contexto completo como Markdown" (Claude e Codex) grava a conversa inteira em um arquivo.
• "Excluir permanentemente (com a gravação)" é a única ação que remove os dados.

9. Busca global (⌘⇧F)

"Pesquisar em todas as sessões" (⌘⇧F; Ctrl+Alt+G no Windows e no Linux) pesquisa o conteúdo de todas as sessões: as conversas com agentes e a saída gravada dos terminais, não apenas os nomes.

• É possível combinar várias palavras em qualquer ordem; palavras parciais e textos em chinês, japonês ou coreano também são encontrados. Os resultados são ordenados por relevância.
• Os resultados ficam agrupados por sessão à esquerda; a pré-visualização à direita destaca a ocorrência atual. ↑/↓ e Enter percorrem as ocorrências de todas as sessões.
• "Abrir sessão" abre a sessão no espaço de trabalho.
• As sessões arquivadas ficam de fora, a menos que você marque "Incluir arquivadas".

A saída do terminal só pode ser pesquisada quando a gravação de sessões está ativada (Configurações ▸ Avançado ▸ "Gravar registros de sessão", desativada por padrão). As conversas com agentes sempre podem ser pesquisadas.

10. Exclusão segura

Excluir uma sessão a remove permanentemente, junto com a gravação dela. Quando você exclui um grupo ou projeto que contém sessões arquivadas, essas sessões arquivadas são mantidas, e restaurar uma delas traz de volta o projeto e o grupo correspondentes. Na dúvida, arquive primeiro: o conteúdo arquivado sempre pode ser restaurado.

11. Sair e restaurar o espaço de trabalho

Ao sair, o VelaTerm pergunta "Sair do VelaTerm?" e encerra as sessões de terminal e de agente em execução. Com "Salvar espaço de trabalho" marcado, a próxima inicialização reabre as mesmas abas e divisões. As sessões restauradas não são iniciadas automaticamente: cada painel mostra "Restaurado do espaço de trabalho salvo. Nenhum processo em execução ainda." com um botão "Iniciar". A caixa de seleção lembra sua última escolha.