Comandos de Sessão

O VelaTerm adiciona um conjunto de comandos curtos a todas as sessões que inicia. Você e seus agentes usam esses comandos para iniciar outras sessões, abrir arquivos, ler e pesquisar outras conversas, verificar quais sessões estão ocupadas, enviar mensagens entre sessões e aguardar comandos demorados. Este capítulo é uma referência de cada comando e das habilidades de agente correspondentes.

1. Onde os comandos funcionam

Os comandos estão no PATH de todas as sessões iniciadas pelo VelaTerm: terminais comuns e sessões de agente, tanto na visão de terminal quanto na visão de conversa, inclusive as sessões em um servidor VelaTerm remoto. Eles não precisam de instalação. Fora dessas sessões, eles são interrompidos com a mensagem "not inside a VelaTerm session".

Execute um comando com --help para exibir as instruções de uso.

Vários comandos recebem uma referência de sessão: o ID completo da sessão, um prefixo do ID com pelo menos 8 caracteres, o nome exato da sessão ou uma parte exclusiva do nome. Coloque entre aspas os nomes que contêm espaços. Quando uma referência corresponde a várias sessões, o comando lista as candidatas.

2. Habilidades de agente (Vela Skills)

Configurações ▸ Geral ▸ "Vela Skills" instala as habilidades correspondentes no Claude Code e no Codex; "Reinstall" as atualiza. Depois, inicie uma nova conversa do Claude ou do Codex para que o agente passe a reconhecê-las. No Claude Code, uma habilidade é chamada com /name; no Codex, com $name.

As habilidades marcadas com "Você" só são executadas quando você as chama; as demais também podem ser usadas pelo próprio agente quando você menciona outra sessão ou um trabalho anterior. vask existe apenas como habilidade; ela executa vrefer <session> --ask "<question>".

3. vspawn e vspawn-tree

vspawn [--worktree] [--cwd <path>] [--yes] [--claude|--codex|--copilot|--kiro] [--model <name>] [--effort <level>] <task description...>

Inicia uma nova sessão abaixo da atual e envia a tarefa como a primeira mensagem dela. vspawn-tree é o mesmo comando com um worktree Git separado.

Detalhes: Criação de Sessões e Colaboração no Git e Planejamento e Execução.

4. vopen

vopen <file|url>...

Abre cada argumento no painel central. Arquivos Markdown abrem no editor Markdown, imagens no visualizador de imagens e os demais arquivos no editor de código. Endereços da web (http ou https) abrem em uma aba de navegador, recurso disponível apenas no aplicativo desktop. Caminhos relativos são resolvidos a partir do diretório atual. Consulte Abas de Documento e Navegador.

5. vrefer e vask

vrefer <session> [--last N] [--range A:B] [--json]
vrefer <session> --ask "<question>" [--with <agent>] [--timeout N]
vrefer --list [--json]

Exibe a conversa de outra sessão. A outra sessão não precisa estar em execução, e nada é enviado a ela.

--ask inicia um processo de agente separado para a resposta e traz de volta apenas a resposta, para que uma conversa longa não ocupe o contexto atual. Configurações ▸ Comportamento ▸ "Contexto de referências de sessão" define como a conversa é entregue ao agente que responde: "Transcrição completa" (padrão) ou "Resumir primeiro", que antes condensa a conversa com o "Agente de resumo", o modelo e o esforço escolhidos ali. Se não for possível produzir uma resposta, vrefer explica o motivo e exibe a conversa.

É possível ler conversas de Claude Code, Codex, OpenCode, Pi, OMP, Grok Build e Kiro (somente registros de texto). Outros tipos de sessão, assim como as sessões cuja conversa com o agente ainda não foi registrada, não podem ser lidos.

6. vsearch

vsearch <words...> [--session <session>] [--all|--archived] [--limit N] [--json]

Pesquisa as conversas de todas as sessões no VelaTerm conectado. Todas as palavras precisam corresponder, em qualquer ordem.

Cada resultado mostra o nome da sessão, o prefixo do ID, o número de ocorrências, alguns trechos com os números das mensagens e o comando vrefer que lê a conversa inteira. O número de uma mensagem pode ser usado com vrefer --range. Os resultados vêm apenas das conversas com agentes; as ocorrências que existem somente nas gravações de terminal não são retornadas. "no matches" é um resultado normal.

7. vstat

vstat [--wait] [--follow] [--timeout N] [--json]

Mostra o estado de cada sessão: working, asking (aguardando uma permissão ou uma resposta), waiting (terminou o turno) ou unknown. O estado indica atividade, não se uma tarefa foi concluída.

Um primeiro argumento opcional filtra por um ID de orquestração de versões mais antigas do VelaTerm; os fluxos de planejamento e execução usam vflow status.

8. vtell

vtell <session> [--steer] [--message-id msg-UUID] [message...]
vtell [planner-session] --report --round N [--message-id msg-UUID] [message...]

Envia uma mensagem para outra sessão. Sem argumentos de mensagem, o texto é lido da entrada padrão. Na conversa do destinatário, aparecem o ícone do agente e o nome da sessão de quem enviou, inclusive depois que ela é reaberta.

• O destinatário precisa ser uma sessão de Claude Code, Codex, OpenCode, Pi ou OMP na visão de conversa. As sessões arquivadas e a própria sessão que envia são recusadas.
• Um destinatário ocioso inicia um novo turno. Um destinatário ocupado enfileira a mensagem até o fim do turno; com --steer, a mensagem é adicionada ao turno em andamento.
• Uma mensagem pode conter até 65.536 bytes de texto.
• O comando exibe um recibo: sent, queued ou steered. blocked significa que o destinatário está aguardando uma permissão ou uma resposta. O recibo confirma a entrega, não que o destinatário concluiu o trabalho.
• O comando exibe um ID de mensagem. Para repetir uma entrega de resultado incerto, execute o comando novamente com --message-id e o mesmo texto; a mensagem não é entregue duas vezes.
• --report --round N é usado pelas sessões de execução de um fluxo de planejamento e execução para enviar o resultado para revisão. A mensagem vai para a sessão de planejamento correspondente. Consulte Planejamento e Execução.

9. vrun

vrun [-t <seconds>] <label> <command> [arguments...]
vrun --status <label>

Inicia um comando, aguarda a conclusão e depois exibe o código de saída, o tempo decorrido e o fim do log. O código de saída do comando é repassado. vrun foi feito para builds e testes demorados: um agente que os executa com vrun fica sabendo do resultado assim que ele estiver disponível.

• -t <seconds> define quanto tempo vrun espera (padrão: 1800). Quando o tempo se esgota, vrun sai com o código 124 e o comando continua em execução.
• --status <label> informa o estado de um comando iniciado anteriormente com esse rótulo.
• Enquanto um comando é executado, a sessão mantém o status "Em andamento". Na visão de terminal, uma linha "Comandos em segundo plano" acima do terminal lista os comandos em execução com "Registro" e "Parar"; consulte Uso do Terminal §6.1.

10. vkb

vkb explore <query> | search <query> | node <symbol-id> | callers <id> [depth] | callees <id> [depth]
    | impact <id> [depth] | path <from-id> <to-id> | files [path]
    | memories <query> | memory <entry-id> | notes <query> | note <vault-id> <path> | status

Consulta o grafo de código do checkout atual e a base de conhecimento do VelaTerm conectado. As consultas de código exigem que a indexação esteja ativada na página Grafo de código do projeto. vkb apenas lê; ele não altera nenhuma entrada de conhecimento. Consulte Grafo de Código e Base de Conhecimento, Base de Conhecimento de Sessões e Bases de Conhecimento Locais.

11. vflow

vflow status|stop|propose|dispatch|accept|block <workflow-id> [--round N --message-id msg-UUID] < message.txt

Controla os fluxos de planejamento e execução. A sessão de planejamento usa propose, dispatch, accept e block como parte do fluxo. Na maioria das vezes, você vai precisar de duas ações:

• vflow status <workflow-id> mostra o estado do fluxo, as tarefas, as sessões e a rodada atual.
• vflow stop <workflow-id> impede novas rodadas e pede que as sessões em execução parem.

12. O comando vela

No macOS, Configurações ▸ Geral ▸ "Comando do shell" oferece "Instalar o comando ‘vela’". Ele adiciona vela <project-path> ao seu shell, de forma semelhante ao comando code do VS Code. Executá-lo em qualquer terminal abre o projeto no VelaTerm ou muda para ele, se já estiver aberto. O VelaTerm não sobrescreve um comando vela existente que não tenha sido instalado por ele.