Introdução

Este guia leva você da instalação ao primeiro terminal e à primeira sessão de agente de IA. Ele basta para começar a trabalhar; cada recurso é descrito em detalhes nos outros capítulos (consulte a visão geral do manual).

1. O que é o VelaTerm

O VelaTerm é um gerenciador de terminais criado para trabalhar com agentes de programação com IA. Ele organiza as sessões de terminal e de agente em uma árvore projeto → grupo → sessão e executa agentes de programação como Claude Code e Codex em sessões dedicadas: você vê a qualquer momento se um agente está trabalhando, se precisa de uma resposta sua ou se já terminou, e reabrir uma sessão dá continuidade à conversa. Os agentes podem ser executados na própria interface de terminal ou em uma visão de conversa com mensagens, cartões de ferramentas e botões de permissão. Com o acesso remoto pelo navegador e o desenvolvimento remoto por SSH, você pode continuar suas sessões em outros dispositivos.

2. Instalação

Baixe o pacote da sua plataforma na página de download:

O VelaTerm verifica atualizações automaticamente; o item "Check for Updates…" do menu do aplicativo faz a verificação imediatamente.

3. Primeira execução: adicione um projeto

Na primeira execução, a barra lateral está vazia e oferece três formas de adicionar um projeto:

• "Criar projeto" cria uma nova pasta e a adiciona.
• "Abrir projeto" (⌘O; Ctrl+Alt+O no Windows e no Linux) adiciona uma pasta existente.
• "Clonar do Git" clona um repositório e o adiciona.

As mesmas ações estão disponíveis como botões no cabeçalho da barra lateral. Dentro de um projeto, você pode criar grupos, aninhados em quantos níveis quiser (por exemplo, frontend, backend e testes), e sessões dentro deles:

4. Abra seu primeiro terminal

Qualquer uma destas opções abre um terminal temporário:

1. Pressione ⌘T (Ctrl+Alt+T no Windows e no Linux).
2. Passe o cursor sobre um projeto, grupo ou sessão na barra lateral, clique no botão ＋ e escolha "Novo terminal". O terminal é iniciado no diretório desse nó. Os menus de contexto de projetos e grupos têm o mesmo item.
3. Quando o painel central estiver vazio, clique em "Criar terminal".

Os terminais temporários existem apenas como abas: nunca se tornam nós da árvore e são descartados quando fechados, o que os torna adequados para comandos rápidos.

5. Abra sua primeira sessão de agente de IA

Clique com o botão direito do mouse em um projeto ou grupo e escolha "Nova sessão Claude". O primeiro nível do menu oferece Claude, Codex e OpenCode; "Mais sessões de agente" lista todos os quatorze agentes compatíveis. Você também pode pressionar ⌘N (Ctrl+Alt+N no Windows, no Linux e em navegadores comuns) para abrir uma lista pesquisável de agentes.

O VelaTerm inicia o agente no diretório do projeto. As sessões de Claude, Codex, OpenCode, Pi e OMP abrem na visão de conversa: digite sua mensagem na caixa na parte inferior e pressione Enter. Os demais agentes abrem na visão de terminal, que mostra a interface de terminal do próprio agente. O botão de alternância no cabeçalho do painel troca a sessão entre as duas visões; consulte Visão de Conversa.

A partir daí, você conta com três recursos:

• Pontos de status: o ponto ao lado da sessão na barra lateral mostra o estado do agente. Verde indica que ele está trabalhando; amarelo, que precisa de você (uma pergunta ou uma solicitação de permissão); magenta, que ele respondeu e você já viu a resposta.
• Notificações do sistema: quando o agente para e fica aguardando você, uma notificação é exibida. Se você já estiver olhando para a sessão, nenhuma notificação aparece.
• Retomada automática: feche a aba ou saia do aplicativo e, na próxima vez que abrir a sessão, a conversa continuará de onde parou. Para uma conversa nova, crie uma nova sessão.

Se a CLI do agente ainda não estiver instalada, a sessão mostra um cartão de instalação com o comando recomendado para o seu sistema e um botão "Instalar agora".

6. Um tour rápido

• Barra lateral esquerda: a árvore de projetos, com uma caixa de busca e um filtro de status. Botões do cabeçalho: Criar projeto, Importar projeto, Clonar do Git, Pesquisar em todas as sessões e Sessões arquivadas.
• Painel central: a barra de abas e as sessões abertas. Por padrão, clicar em uma sessão de agente na árvore reutiliza a aba atual, e a aba anterior continua em execução em segundo plano. Fechar uma aba encerra os processos dela. As abas podem ser divididas em painéis (⌘D à direita, ⌘⇧D abaixo).
• Painel direito: acompanha a sessão atual e tem quatro abas: Arquivos, Informações (detalhes da sessão, uso da conta, contexto e uso de recursos), Git (branch, alterações e commits) e Base de conhecimento.
• Barra de status: número de sessões, tipo da sessão atual, branch do Git, modo de permissões, botão de notificações e os contadores Em andamento / Pendente / Visto. Clique em um contador para mostrar apenas essas sessões na barra lateral.
• Barra de título, lado direito: alternância de tema, Acesso remoto, Conectar a servidor remoto, Compartilhar, Configurações, Conta, Feedback e os botões que mostram ou ocultam os painéis laterais.

7. Próximos passos

• Árvore, abas, painéis divididos, arquivamento e busca global: Gerenciamento de Interface e Sessões.
• Recursos dos agentes, retomada, bifurcação e permissões: Sessões do Agente de IA.
• Trabalho na visão de conversa: Visão de Conversa.
• Agentes que iniciam sessões filhas em worktrees separados: Criação de Sessões e Colaboração no Git.
• Recursos do terminal (busca, colagem de imagens, sugestões de comandos): Uso do Terminal.
• Uso do VelaTerm em um celular ou em outro computador: Desenvolvimento e Gerenciamento Remoto.