Usar no VS Code
A extensão Imaginne (nnumbers.imaginne) traz o agente para dentro do editor: ele lê o seu workspace, propõe edições como diffs revisáveis e roda testes e revisões sem você sair do VS Code. Por baixo, a extensão sobe o CLI local (imaginne serve) — então o binário imaginne precisa estar instalado. Para instalar, veja Instalar VS Code; para a referência seca de comandos e settings, veja Comandos do VS Code.
A extensão não fala direto com o modelo — ela conversa com o Engine que o CLI sobe localmente. Se você vir "Engine disconnected" ou "cloud API key is required for model nnumbers", rode Imaginne: Run Health Check, faça /login e, se necessário, aponte imaginne.binaryPath para o executável. Veja Solução de problemas.
O painel de chat
Abra o chat com Ctrl/Cmd+Shift+I. O painel tem:
- uma barra de status com o seletor de autonomia (Ask / Fix / Agent / Bypass), os botões Retry / Retry+ / Stop e o selo do modelo ativo;
- as pílulas de contexto (o que foi anexado nesta mensagem);
- o campo de entrada "Ask Imaginne… (@file, /command)".
Foque no campo de entrada com Ctrl/Cmd+Shift+L.
Comandos de barra no chat
| Comando | O que faz |
|---|---|
/new · /clear | Nova conversa / limpar. |
/status · /compact | Estado da sessão / compactar contexto. |
/model | Mostra o modelo ativo. |
/cancel | Cancela a execução. |
/autonomy | Ajusta o nível de autonomia. |
/login · /logout · /whoami | Identidade. |
/help | Ajuda. |
Diretivas de ação (equivalentes aos comandos da paleta): /fix, /explain, /test, /refactor, /review, /plan.
Contexto inteligente
Por padrão, a extensão anexa contexto automaticamente a cada mensagem para que o agente entenda o seu código sem você colar nada:
- a raiz do workspace;
- o arquivo ativo (inteiro quando não há seleção, até ~32 KB);
- a seleção atual;
- os diagnósticos (erros/avisos);
- as abas abertas e arquivos vizinhos rankeados;
- o git diff (opcional, desligado por padrão).
As pílulas de contexto mostram exatamente o que foi anexado e se limpam a cada turno. Para verificar antes de enviar, use Imaginne: Preview Context.
@file e pins
@arquivo— digite no campo de entrada para injetar o conteúdo de um arquivo específico.- Pins — fixe um arquivo ou seleção no contexto de forma persistente com Pin Active File / Pin Selection (limites de 8 itens, 16 KB por item e 64 KB no total). Gerencie com Unpin / Show Pinned Context / Clear Pinned Context.
Comandos principais
Todos os comandos ficam na categoria "Imaginne:" na paleta (Ctrl/Cmd+Shift+P). Os mais usados:
| Comando | Para que serve | Onde fica |
|---|---|---|
| Open Chat | Abrir o painel de chat | Paleta · Ctrl/Cmd+Shift+I |
| Ask / Fix / Explain / Refactor Selection | Agir sobre o trecho selecionado | Paleta · menu de contexto do editor |
| Explain File | Explicar o arquivo inteiro | Paleta |
| Generate Tests | Gerar testes | Paleta |
| Run Test for File · Run Test at Cursor | Rodar testes | Explorer / menu do editor |
| Review Current Changes · Review Staged Changes | Revisar mudanças | Paleta · menu do SCM |
| Review Branch vs Base · Review File | Revisar branch ou arquivo | Paleta · Explorer |
| Generate Commit Message | Redigir a mensagem de commit | Menu do SCM |
| Explain Diff | Explicar um diff | Paleta |
| Pin Active File / Selection | Fixar contexto | Paleta · menus de contexto |
| Start / Stop / Resume Agent Task | Modo de tarefa autônoma | Paleta |
| Run Health Check | Diagnosticar a conexão com o Engine | Paleta |
| Login · Logout · Whoami | Identidade | Paleta |
| Configure Binary Path | Apontar o CLI | Paleta |
A extensão registra cerca de 77 comandos no total; a lista completa está em Comandos do VS Code.
Atalhos
| Atalho | Ação |
|---|---|
| Ctrl/Cmd+Shift+I | Abrir o chat |
| Ctrl/Cmd+Shift+L | Focar o campo de entrada |
| Esc | Cancelar a execução (com a barra lateral visível) |
| Ctrl/Cmd+L | Limpar o chat |
Proposed Changes (Composer)
Esta é a peça central da extensão: toda edição proposta passa pelo Composer antes de tocar o disco. Você revisa cada mudança e decide o que aplicar.
No painel Proposed Changes você tem:
- Apply All / Discard All — aplicar ou descartar tudo de uma vez;
- por arquivo: Diff (ver a alteração), Apply, Reject e Hunks (aplicar/rejeitar trecho a trecho).
Cada arquivo mostra um selo de estado — pending, applied, rejected ou conflict — e a origem da mudança (from failing test, from review, from task).
Se um arquivo mudou no disco desde que a proposta foi gerada, a extensão sinaliza conflito e não sobrescreve cegamente — você revisa antes de aplicar. Esse é o mecanismo de "ver o diff antes" do VS Code descrito em Autonomia & permissões.
Modais de permissão
Antes de uma ação sensível, a extensão pede confirmação explícita:
- "Imaginne wants to modify:
<path>" — Accept / Reject; - "Imaginne wants to run:
<tool>" — Allow / Deny.
Fix with Imaginne
Em qualquer diagnóstico (sublinhado de erro/aviso), abra as ações de código (a lâmpada 💡) e escolha Fix with Imaginne. A extensão envia um /fix já com o contexto do erro, e a correção volta como uma Proposed Change para você revisar.
Autonomia
A extensão tem quatro níveis, no seletor da barra de status:
| Nível | Comportamento |
|---|---|
| Ask | Só lê e responde; não altera nada. |
| Fix (padrão) | Propõe mudanças e confirma cada uma. |
| Agent | Confirma cada uma, com Apply All disponível e allowlist de comandos em um clique. |
| Bypass | Aplica automaticamente dentro do workspace; ações destrutivas ainda confirmam. Expira após 30 min e ao trocar/fechar. |
Independentemente do nível, há uma denylist fixa — rm -rf, sudo, curl|sh etc. nunca rodam — e escrever fora do workspace sempre pede confirmação. Veja Autonomia & permissões.
Painéis: Tests, Review e Task Mode
- Tests — resultados dos testes, com rerun e fix dos que falharam (as correções entram como Proposed Changes).
- Review — os achados de uma revisão agrupados por severidade, com "Copy & fill SCM" para levar a mensagem de commit sugerida direto ao painel de controle de versão.
- Task Mode — uma tarefa autônoma: Start Agent Task gera um plano, executa passo a passo e entrega um relatório. Controle com Stop, Continue e Apply & Continue.
Existe um recurso de Remote Task atrás de uma flag (loopback), desligado por padrão. Trate-o apenas como experimental.
Painel Dev Studio
Além do chat, a extensão traz o painel Dev Studio (ícone próprio na barra de atividades) que conecta você aos recursos da sua organização na Platform:
| Item | Comando | Para que serve |
|---|---|---|
| Tools Catalog | Imaginne: Tools Catalog | As ferramentas disponíveis para o agente na sua organização (escopo de desenvolvimento). |
| MCP Servers (Tools) | Imaginne: Show MCP Servers (Tools) | Os servidores MCP conectados e as ferramentas que expõem. Veja MCP. |
| Agents Dashboard | Imaginne: Agents Dashboard | Os runs do agente da sua organização — histórico e estado. |
| Usage & Admin Summary | Imaginne: Usage & Admin Summary | Um resumo de uso da sua organização. |
| Cloud Runs | Imaginne: Cloud Runs | Executar um run no servidor em vez de localmente (opt-in). |
Esses painéis são org-scoped (usam a sua sessão do Imaginne). Cloud Runs é opt-in e desligado por padrão — nada roda no servidor até que a sua organização habilite e você ligue o setting. Veja Cloud Runs no VS Code.
Modelos
A extensão tem um seletor de modelo: rode Imaginne: Select Model ou clique no selo do modelo na barra de status. Os modelos oferecidos dependem da política da sua organização — tipicamente nnumbers (versátil), nnumbers-flash (rápido) e nnumbers-code (focado em código, planos full-tier). A escolha é persistida por workspace e a barra de status mostra o modelo ativo. Veja Modelos.
Settings úteis
A extensão expõe cerca de 32 configurações. As mais relevantes:
| Setting | Padrão | Para que serve |
|---|---|---|
imaginne.binaryPath | — | Caminho do CLI, se não estiver no PATH. |
imaginne.platformUrl | — | URL da Platform. |
imaginne.cloudRuns.enabled | false | Liga o dispatch de Cloud Runs (executar um run no servidor). Desligado = tudo roda local, sem requisição ao servidor. Veja Cloud Runs. |
imaginne.context.smart | true | Liga o contexto inteligente. |
imaginne.context.includeGitDiff | false | Inclui o git diff no contexto. |
imaginne.context.includeDiagnostics | true | Inclui erros/avisos. |
imaginne.context.includeOpenTabs | true | Inclui as abas abertas. |
imaginne.autonomy.defaultLevel | fix | Nível de autonomia inicial. |
imaginne.autonomy.allowApplyAll | true | Habilita o Apply All. |
imaginne.autonomy.requireConfirmationForDestructive | true | Sempre confirma o destrutivo. |
imaginne.autonomy.commandAllowlist | — | Comandos liberados sem confirmar. |
imaginne.autonomy.commandDenylist | — | Comandos sempre bloqueados. |
imaginne.autonomy.bypassTimeoutMinutes | 30 | Duração do modo Bypass. |
imaginne.extraArgs | — | Argumentos extras para o CLI. |
A tabela completa está em Comandos do VS Code.
Veja também
Executar um run do agente no servidor, num pod quente e isolado por usuário.
Abrir →Comandos do VS CodeA referência completa de comandos, atalhos e settings.
Abrir →Autonomia & permissõesOs modos Ask/Fix/Agent/Bypass e o cofre de workspace.
Abrir →Revisão de códigoReceita ponta a ponta: revisar, corrigir e gerar o commit.
Abrir →ModelosPor que a extensão não tem seletor de modelo.
Abrir →SkillsO que o agente sabe fazer.
Abrir →Esta página ajudou?
Reportar um problema nesta páginaNão envie senhas, chaves, tokens ou dados de clientes.