Usar a TUI

A TUI (interface de terminal) traz o agente completo para dentro do seu terminal, rodando localmente com acesso aos seus arquivos. Esta página cobre o uso do dia a dia. Para instalar, veja Instalar TUI; para a referência seca de todos os comandos, veja Comandos da TUI.

Iniciar

Abra a TUI com:

imaginne

imaginne chat é equivalente. Na primeira execução, sem assistente de configuração, o login abre no navegador automaticamente — conclua e volte ao terminal. A TUI requer um terminal com TTY; se você vir requires a TTY-capable terminal, use um emulador de terminal de verdade.

Canal DEV

O canal DEV usa o binário imaginne-dev e a pasta ~/.imaginne-dev (não compartilha config com o PROD). Use o build que sua organização indicar.

O layout e a barra de status

A tela tem um cabeçalho (TUI — [N]umbers), o viewport da conversa, o prompt > com a caixa de texto e, na base, a barra de status:

EXECUTE · nnumbers · 1.2k tokens · ctx:▓▓▓░░ 38%

A barra mostra o modo atual (EXECUTE / PLAN / ASK), o modelo, o uso de tokens e a barra de contexto (usado/limite). Veja Sessões para entender contexto e compactação.

Enviar e escrever em várias linhas

• Enviar — Enter.
• Multilinha — cole um texto com várias linhas (paste) para enviá-lo de uma vez.

Modos de trabalho: Exec, Plan, Ask

O agente opera em um de três modos, alternados com Shift+Tab (ou pelos comandos abaixo):

Modo	Comportamento
EXECUTE	Planeja e age (edita arquivos, roda comandos e skills).
PLAN	Apenas planeja; não executa ações com efeito.
ASK	Conversa/responde, sem alterar nada.

Comandos equivalentes: /exe (/execute), /plan, /ask.

Comandos de barra

Digite / para abrir o menu. Lista completa:

Comando (aliases)	O que faz
/help (/h, /?)	Lista os comandos.
/quit (/q, /exit)	Sai da TUI.
/clear (/cls)	Limpa a conversa.
/context clear	Limpa o contexto (recomeça o raciocínio do modelo).
/model (/m)	Abre o seletor de modelo.
/autonomy (/a)	Ajusta o nível de autonomia.
/verbose (/v)	Ajusta o nível de detalhe da saída.
/version	Mostra a versão.
/update	Atualiza o binário.
/diagnostics	Coleta informações de diagnóstico.
/status	Mostra o estado da sessão.
/project (/p)	Operações de projeto.
/skill (/skills)	Gerencia skills (ver subcomandos).
/sessions	Gerencia sessões (ver subcomandos).
/plan · /exe (/execute) · /ask	Alterna o modo de trabalho.
/lang (/language, /idioma)	Muda o idioma.
/remote	Pareamento de sessão remota (ver abaixo).
/init	Inicializa o projeto.
/iterate (/iter)	Itera sobre a última saída.
/agent	Subagentes (ver subcomandos).
/login · /logout · /whoami	Identidade.
/policy	Mostra a política efetiva.
/memory	Abre a memória.
/feedback (/fb)	Envia feedback.
/todo	Lista de tarefas da sessão.

Subcomandos de /skill

Subcomando	O que faz
list	Lista as skills disponíveis.
info <nome>	Detalhes de uma skill.
validate [path|key]	Valida o manifesto de uma skill.
groups [--search q]	Lista grupos de skills.
publish <key|--skill-path p> --group <slug|id> [--mode]	Publica uma skill.
status	Estado da sincronização de skills.

Subcomandos de /sessions

Subcomando	O que faz
list	Lista as sessões.
new <título>	Cria uma sessão.
switch <id>	Troca de sessão.
archive <id>	Arquiva uma sessão.
rename <id> <título>	Renomeia uma sessão.

Você não troca de sessão enquanto o agente está respondendo, e não dá para arquivar a sessão ativa. Veja Sessões.

Subcomandos de /agent

A TUI pode delegar tarefas a subagentes especializados:

Subcomando	O que faz
list	Lista os subagentes.
spawn <tipo> <tarefa>	Cria um subagente para uma tarefa.
status	Estado dos subagentes.
cancel <id>	Cancela um subagente.
metrics · cost	Métricas e custo.

Tipos disponíveis: explorer, analyzer, reviewer, implementer, tester, refactorer, documenter.

Mencionar arquivos: @

Aponte um arquivo com @ e a TUI lê o conteúdo e o injeta inline na sua mensagem:

resuma @relatorio.md e gere uma versão executiva

Sintaxes aceitas:

• @caminho — caminho relativo;
• @"caminho com espaços" — entre aspas;
• @/abs — caminho absoluto;
• @~/home — a partir do seu diretório de usuário.

Diretórios, binários e arquivos com mais de 100 KB são ignorados. Use Tab para completar (modo path e modo fuzzy) e ↑/↓ para navegar nas sugestões. Veja Arquivos & artefatos.

Modelo

/model (/m) abre o seletor, filtrado pela política da organização. O padrão é nnumbers. A TUI sempre roteia automaticamente por turno — selecionar um modelo funciona como uma dica/override. Veja Modelos.

Autonomia

Ajuste com /autonomy (/a) ou Ctrl+A:

• low — pergunta tudo;
• medium — equilibrado;
• high — full auto.

A preferência é salva em ~/.imaginne/prefs.json. O cofre de workspace continua ativo em qualquer nível. Veja Autonomia & permissões.

Nível de detalhe (verbose)

/verbose (/v) ou Ctrl+X alterna entre silent, medium e debug (padrão debug). Use níveis mais baixos para uma saída mais limpa.

Voz

A voz é fala→texto: Ctrl+G ou F2 inicia a captura (depende de um build com a tag voice; hoje, do release darwin-arm64). A transcrição é anexada ao prompt e não é enviada sozinha; Esc cancela. Configurável por variáveis IMAGINNE_VOICE_*. Veja Voz.

Sessão remota

/remote exibe um código de pareamento válido por 30s. No outro lado, abra <host>/remote no navegador, faça login e cole o código — os prompts rodam no seu computador e o streaming volta para as duas telas. Use /remote status e /remote stop para gerenciar. Requer login. Veja Sessão remota.

Atalhos de teclado

Atalho	Ação
Enter	Enviar
Esc	Cancelar (duplo Esc limpa)
Ctrl+C	Sair
Ctrl+G / F2	Voz
Ctrl+A	Autonomia
Ctrl+T	Painel de tarefas
Ctrl+X	Verbose
Ctrl+K	Limpar tela
Ctrl+O	Limpar contexto
Ctrl+Y / F1	Ajuda
Shift+Tab	Ciclar modo (Exec/Plan/Ask)
Tab	Completar
PgUp / PgDn	Rolar a conversa

Configuração

A TUI lê ~/.imaginne/config.yaml (YAML, permissões 0600). As chaves principais:

llm:
  model: nnumbers         # modelo padrão
  max_tokens: 16384
  temperature: 0.7
memory:
  storage_path: ~/.imaginne/memory

Você normalmente não edita esse arquivo à mão — o login preenche a identidade. Use imaginne config init para gerar um arquivo base.

Variáveis de ambiente

Variável	Efeito
IMAGINNE_DANGEROUS_BYPASS	Habilita o modo de execução perigoso (equivale a iniciar com --dangerous-bypass).
IMAGINNE_DEBUG	Liga logs de depuração.
IMAGINNE_LEGACY	Modo de compatibilidade legado.
IMAGINNE_TUI_LOCAL_STORE=off	Desativa o armazenamento local de sessões.
IMAGINNE_GLOBAL_SKILLS_DIR	Sobrescreve a pasta global de skills.
IMAGINNE_VOICE_*	Configuração da voz.

A lista completa de variáveis do cliente está em Variáveis de ambiente.

Veja também

📖Comandos da TUI

A referência completa de comandos, subcomandos e atalhos.

Abrir →🛡️Autonomia & permissões

Os níveis de autonomia e o cofre de workspace.

Abrir →🔗Sessão remota

Conduza a sua sessão local de outra tela.

Abrir →🎤Voz

Ditar pedidos por fala→texto.

Abrir →🧰Skills

O que o agente sabe fazer e como publicar novas skills.

Abrir →⚙️Variáveis de ambiente

As variáveis do cliente que afetam a TUI.

Abrir →