Assistente de IA¶

Um assistente dentro do editor que comanda o agente de IA de linha de comando que você já tem instalado — explicar, refatorar, corrigir, escrever testes, resumir, traduzir e conversar, com cada edição proposta exibida como um diff revisável que você aplica de propósito.

Traga o seu próprio agente¶

O assistente não pede uma chave de API nem faz login em nada. Em vez disso, ele executa como auxiliar um agente de IA de linha de comando instalado localmente e envia a saída dele para o editor. Autenticação, sua assinatura e a escolha do modelo pertencem todas àquela ferramenta.

Hoje: Claude Code (claude) e Codex CLI (codex). Instale um deles e faça login uma vez (de modo que claude ou codex funcione a partir de um terminal); o editor o detecta automaticamente. O Gemini também é oferecido, mas a integração de linha de comando dele ainda não foi verificada.
A detecção é automática e não bloqueia. O editor sonda o agente em segundo plano logo após iniciar — a janela nunca espera por ele. Enquanto a sondagem roda, Exibir → Chat de IA fica brevemente desativado com uma dica Detectando o mecanismo de IA…; alguns segundos depois ele ou é ativado (agente encontrado) ou permanece esmaecido com uma dica dizendo o que instalar.

O agente é um programa separado que você instala

O editor não embute nem baixa nenhum agente de IA, e também não envia seu texto para lugar algum por conta própria — é o agente de linha de comando que você instalou que faz a requisição usando a própria conta e a própria conexão de rede. Se o agente não estiver instalado ou logado, os recursos de IA simplesmente ficam desativados e nada mais no editor é afetado.

Requisitos¶

O assistente tem um requisito obrigatório: um agente de IA de linha de comando suportado, instalado e logado, no PATH do seu sistema.

Instale um agente suportado. Hoje é o Claude Code (claude) ou o Codex CLI (codex).
Faça login uma vez. Execute o agente a partir de um terminal e complete o login dele, para que depois funcione sem interação. O editor nunca pede nem armazena uma chave de API — sua assinatura e seu login vivem inteiramente naquela ferramenta.
Garanta que ele está no seu PATH. Se o editor não conseguir executá-lo, Exibir → Chat de IA fica esmaecido com uma dica explicativa.

O painel Chat de IA¶

Não há um menu de IA de primeiro nível — tudo fica em um único painel inferior, alternado em Exibir → Chat de IA. Se o painel estava aberto quando você fechou o editor pela última vez, ele reabre na próxima inicialização (assim que o mecanismo for detectado).

De cima para baixo, o painel mostra:

uma lista suspensa Mecanismo (sua escolha é lembrada entre sessões) e a caixa de seleção Permitir edições de arquivo (veja abaixo);
uma linha de status — o mecanismo detectado e a versão, uma nota de sondagem/progresso, ou a dica de "instale e faça login". Depois da primeira resposta ela também nomeia o modelo que o agente realmente usou, por exemplo Engine: Claude (2.1.200) · claude-sonnet-5 — vale uma olhada, já que o modelo decide quanto cada execução custa a você (veja Escolhendo o modelo);
uma barra de atividade fina com um botão Parar enquanto o agente trabalha;
o console — a conversa inteira em uma única visualização;
uma linha de dicas listando os comandos disponíveis como links clicáveis.

O console¶

A conversa funciona como um terminal: o histórico acima, e você digita no final, depois do prompt ›.

Enter envia; Shift+Enter insere uma quebra de linha, então pedidos de várias linhas funcionam.
Clicar ou digitar em qualquer ponto do histórico devolve o cursor ao prompt — o histórico pode ser selecionado e copiado, mas nunca editado.
Esc cancela a requisição em andamento; quando nada está rodando, ele limpa o que você digitou depois de ›. O Esc funciona com o foco em qualquer parte do painel.
Ctrl+A seleciona apenas a pergunta que você está compondo, de modo que o que você digitar em seguida a substitua; sem nada digitado, ele seleciona toda a transcrição, pronta para copiar.
Cima e Baixo recuperam o que você perguntou antes, como faz um shell. Cima na primeira linha do que você está digitando retrocede pelas perguntas anteriores; Baixo avança de novo, e passar da mais recente devolve a linha pela metade de onde você partiu. Dentro de um pedido de várias linhas, eles simplesmente se movem entre as linhas dele, e assim que você edita uma pergunta recuperada ela vira o seu novo rascunho. O histórico é por painel e não é mantido entre sessões.
Enquanto uma resposta chega em fluxo, a visualização acompanha se você está no fim; role para cima para ler e ela fica parada. Quando a resposta está completa, a visualização a posiciona de propósito: uma resposta curta rola até o fim para que você a veja junto com o prompt abaixo, enquanto uma longa alinha o cabeçalho Assistente com o topo do painel, para que você possa ler desde o começo.
O Markdown de cada resposta é renderizado por conta própria, então listas numeradas começam em 1 toda vez, em vez de continuar a numeração da resposta anterior.

Comandos¶

Digite um comando no prompt, ou clique nele na linha de dicas (comandos que levam um argumento ganham um espaço ao final e esperam você terminar a linha):

Comando	O que faz	Resultado
`.explain`	Explica o código selecionado	resposta no chat
`.summarize`	Resume o texto selecionado	resposta no chat
`.refactor <how>`	Refatora conforme instruído (p. ex. `.refactor extract a helper`)	edição revisável
`.fix`	Corrige o código selecionado	edição revisável
`.tests`	Escreve testes de unidade para a seleção	edição revisável
`.translate <language>`	Traduz a seleção (p. ex. `.translate German`)	edição revisável
`.model <id>`	Fixa o modelo que este editor pede (veja Escolhendo o modelo)	respondido na hora, sem executar o agente

Qualquer outra coisa que você digitar é tratada naturalmente:

Texto simples é uma pergunta livre ao agente, enviada junto com o que você tem na tela (veja abaixo).
Uma linha começando com / é um dos comandos do próprio agente (como o /help do Claude) e é encaminhada exatamente como digitada — nada do editor é acrescentado a ela, e nenhum consentimento é necessário porque nada seu é enviado. Isso vale para mecanismos cujo conjunto de comandos foi verificado — hoje, o Claude; nos demais, uma linha com / é tratada como uma pergunta comum.
Um .palavra não reconhecido não é um erro; ele é enviado como um pedido.

Nem todo comando de linha de comando significa aqui o mesmo que no terminal do próprio agente: alguns precisam de uma sessão interativa que as execuções do editor não têm, alguns dizem respeito a conversas que o editor já gerencia por conta própria, e alguns — como /model — simplesmente não conseguem sobreviver a uma única requisição. Quando você envia um desses, o editor o encaminha assim mesmo e acrescenta uma nota curta dizendo por que ele pode não fazer o que você espera. Você verá cada nota uma vez por sessão.

O /model do próprio agente não pode durar — use .model

Cada pergunta executa o agente do zero, e uma execução nova sempre parte do modelo que a sua ferramenta de linha de comando está configurada para usar. /model … responde "Modelo definido como … apenas para esta sessão", mas essa sessão acaba no mesmo momento que a resposta: a próxima pergunta — mesmo uma que continue a mesma conversa — volta ao modelo configurado. Use .model <id> em vez disso; ele é um comando do próprio editor e fixa o modelo para todas as perguntas seguintes. Veja Escolhendo o modelo.

A correspondência não diferencia maiúsculas de minúsculas, e a linha de dicas se reduz enquanto você digita (.r → .refactor …).

Seleção ou documento inteiro¶

Os comandos atuam sobre a seleção atual. Sem seleção, eles operam sobre o documento inteiro — e como isso envia o arquivo completo para o agente, o editor pergunta antes: Enviar o documento inteiro "…" para o Claude? Você é perguntado uma vez por documento por sessão do editor; recusar aborta o envio e mantém o que você digitou. A pergunta pode ser desligada em Preferências → Assistente de IA, com a opção Perguntar antes de enviar um documento inteiro ao mecanismo de IA; com ela desligada, o documento inteiro é enviado sem perguntar.

O que o assistente sabe sobre o seu documento¶

O agente lê arquivos do disco. Por conta própria, portanto, ele responderia perguntas sobre um arquivo que você editou mas não salvou usando o texto antigo, e não veria um buffer sem título de forma alguma. Por isso uma pergunta livre conta a ele o que você realmente tem aberto:

Salvo e sem alterações pendentes — o assistente simplesmente nomeia o arquivo e deixa o agente lê-lo. Nada sai do editor, então nada é perguntado.
Com alterações não salvas, ou um documento nunca salvo — o texto atual é enviado junto com sua pergunta. Documentos pequenos viajam na própria pergunta; os maiores são gravados em uma cópia temporária para a qual o agente é apontado. A cópia é excluída assim que a troca termina.
Com uma pasta aberta — todos os outros documentos abertos com alterações não salvas são incluídos da mesma forma, para que o agente veja o projeto como você o vê, e não como ele foi salvo pela última vez.

Como isso envia texto para fora, o editor pergunta antes — uma vez por documento por sessão do editor, e uma única vez para toda a requisição, mesmo quando vários documentos estão envolvidos: O conteúdo atual, não salvo, destes documentos será enviado ao Claude: …. Continuar? Recusar abandona a requisição e mantém o que você digitou.

Uma seleção ainda tem precedência como aquilo para o que você está apontando: ela é enviada como Seleção relevante junto com o documento, não no lugar dele.

No modo somente leitura padrão, o agente também é informado de que não pode alterar seu documento e de que uma alteração deve ser sugerida pelos comandos .refactor, .fix, .tests e .translate — que mostram um diff a você.

Revisando e aplicando edições¶

Os comandos de edição nunca reescrevem seu texto em silêncio. Quando o agente termina, uma caixa de diálogo de revisão abre com um grupo de alterações marcável e colorido por modificação — linhas removidas em vermelho, linhas adicionadas em verde:

desmarque as alterações que você não quer;
Aplicar substitui a seleção (ou o documento inteiro, no caso sem seleção) apenas pelas alterações aceitas;
Descartar deixa o buffer exatamente como estava.

As alterações aplicadas são edições comuns, então Ctrl+Z as desfaz como qualquer outra coisa. O estilo de fim de linha do seu arquivo (CRLF/LF) é preservado. Se o agente se recusar a fazer uma edição, a explicação dele aparece como uma resposta normal do chat em vez de um diff falso.

Se você continuou editando enquanto o agente trabalhava, o editor nunca emenda uma alteração desatualizada por cima do seu texto mais novo. O que ele faz em vez disso depende do que ainda consegue afirmar com certeza:

o que você digitou moveu o alvo, mas o deixou intacto → a alteração é aplicada onde o texto está agora;
o comando cobria o documento inteiro e o documento mudou desde então → a proposta é comparada com o seu texto atual e você revisa aquele diff, então a resposta não é desperdiçada;
o texto original sumiu, ou agora aparece várias vezes → o editor se recusa em vez de adivinhar, e diz a você para executar o comando de novo.

As cores do diff seguem o seu tema de cores: temas podem definir cores dedicadas de Texto adicionado no diff / Texto removido no diff (editáveis em Preferências → Coloração de sintaxe → Temas), e sem elas o editor escolhe padrões legíveis para interfaces claras e escuras.

Conversas¶

As perguntas livres formam uma conversa contínua: o agente lembra suas perguntas e respostas anteriores. Há uma conversa por pasta aberta (ou por arquivo, quando nenhuma pasta está aberta), de modo que projetos sem relação não compartilham contexto. Os comandos de edição (.refactor, .fix, …) rodam de propósito de uma vez só e não contaminam o contexto do chat. As conversas não são preservadas — reiniciar o editor começa conversas novas.

Tanto o Claude quanto o Codex continuam conversas. O Codex dá nome a cada conversa por conta própria e anuncia o nome quando ela começa; as perguntas seguintes a retomam a partir daí. Se uma execução do Codex terminar sem anunciar nenhum, o chat mostra [não foi possível continuar a conversa — o mecanismo não informou nenhum identificador de sessão; a próxima mensagem inicia uma nova] — a resposta que você recebeu continua valendo, mas a sua próxima pergunta começa uma conversa nova, sem o contexto anterior.

Uma conversa também sobrevive ao que dá errado. Parar uma resposta a preserva, então uma pergunta que você interrompeu pode simplesmente ser retomada — peça "continue com a última tarefa" e o agente ainda sabe o que estava fazendo, mesmo que você o tenha parado antes de ele dizer uma palavra. Uma falha pontual (um limite de taxa, uma conexão caída) também não joga fora o histórico; apenas uma segunda falha seguida começa uma conversa nova.

Parando uma execução¶

Enquanto o agente trabalha, aparece uma barra de atividade com um botão Parar — clique nele (ou pressione Esc em qualquer parte do painel) para cancelar. O que tiver chegado em fluxo até então permanece na transcrição, a execução é marcada como [Cancelada] e nenhuma edição é aplicada. A conversa é preservada, então sua próxima pergunta a continua (veja Conversas). Pressionar Enter no meio de uma execução não enfileira nada; a linha de status lembra que o agente ainda está trabalhando.

Deixando o agente editar arquivos¶

Por padrão o assistente é somente leitura: cada execução lança o agente com as ferramentas de edição de arquivos, o acesso ao shell e os subagentes desativados, de modo que as alterações chegam a você apenas como propostas revisáveis. Para mecanismos com sinalizadores de permissão verificados, esse é um bloqueio rígido imposto pelo próprio agente, não importa como sua ferramenta de linha de comando esteja configurada:

O Claude roda com as ferramentas de edição de arquivos, o acesso ao shell e os subagentes desligados.
O Codex roda na sua sandbox somente leitura (-s read-only). A sandbox funciona de outro jeito: ela não desliga os comandos do shell, ela os confina — o Codex ainda pode rodar comandos para dar uma olhada, mas eles não conseguem gravar nada. Por enquanto, o editor também pede ao Codex, com todas as letras, que permaneça somente leitura.

O somente leitura não é garantido em todos os mecanismos

O bloqueio rígido depende dos sinalizadores de permissão do próprio mecanismo. O Gemini ainda não tem sinalizadores verificados, então o editor só pode pedir a ele — como uma instrução de melhor esforço — que permaneça somente leitura; ele não pode forçá-lo. Trate o somente leitura como não garantido no Gemini: ele ainda pode gravar no disco, e o comportamento dele é regido, em última instância, pela configuração da sua própria ferramenta de linha de comando. Se isso importa para você, mantenha esse trabalho em uma pasta sob controle de versão.

A caixa de seleção Permitir edições de arquivo (ao lado da lista suspensa de mecanismo, desligada por padrão, lembrada entre sessões) habilita a edição pelo agente:

as edições de arquivo do agente são aceitas automaticamente e ele pode modificar arquivos da pasta aberta durante uma execução;
cada gravação é reportada na conversa como [o agente modificou um arquivo: …], e os documentos abertos captam as alterações pelo monitoramento normal de arquivos do editor;
quando a execução termina, uma única linha de resumo lista todo o conjunto de arquivos tocados com uma contagem, por exemplo [arquivos modificados (3): …];
o acesso do Claude ao shell e os subagentes dele continuam bloqueados mesmo com a opção ligada.

Com o Codex, a opção muda a sandbox dele para -s workspace-write: o Codex pode então editar arquivos, e rodar comandos do shell, dentro da pasta aberta e do diretório temporário. O Codex não informa suas edições ao editor, então o chat não lista os arquivos que ele alterou e não há linha de resumo; os documentos abertos ainda captam as alterações pelo monitoramento de arquivos. As gravações em si são feitas pela própria sandbox do Codex: se o Codex responder que não conseguiu iniciar o executor de comandos dele, essa sandbox não está funcionando na sua máquina — verifique os diagnósticos dele (codex doctor), não o editor.

A mesma chave também está em Preferências → Assistente de IA, como Permitir que o mecanismo de IA edite arquivos. Elas são uma única configuração, não duas: aplicá-la nas Preferências marca ou desmarca a caixa do painel na hora, e o que você definir no painel é o que as Preferências mostram na próxima vez que você as abrir.

Documentos com alterações não salvas são tratados por você. O agente não pode editar o arquivo em disco de um documento que você alterou mas não salvou — aquela cópia está desatualizada, e gravar nela deixaria o arquivo e o seu editor em desacordo. Por isso o agente recebe a cópia temporária do seu texto atual para editar, e quando a execução termina o editor traz o resultado de volta ao seu documento aberto como uma edição comum e reversível. Documentos sem título funcionam da mesma forma, mesmo não tendo arquivo algum. Se por acaso você mesmo editou o documento enquanto o agente trabalhava, o editor não sobrescreve você: ele abre a caixa de diálogo de revisão habitual contra o seu texto atual, para que você decida alteração por alteração. Fechar o documento durante a execução simplesmente descarta o trabalho do agente, com uma nota na conversa.

Permitir edições de arquivo pode sobrescrever ou apagar seu trabalho

Com a opção ativada, o agente grava direto no disco e essas gravações são aceitas automaticamente — não há caixa de diálogo de revisão por alteração. O agente pode sobrescrever, apagar ou corromper arquivos da pasta aberta, e edições em arquivos que você não tem abertos não são mostradas como diffs. Ative isso apenas para uma pasta sob controle de versão (Git, SVN, …): faça commit ou stash do seu trabalho primeiro e depois use o diff do controle de versão para inspecionar cada alteração e reverter o que não quiser — trate o controle de versão como o seu desfazer para as edições do agente. O Gemini, cujos sinalizadores de permissão ainda não foram verificados, ignora essa opção por completo, então as edições dele são regidas somente pela configuração da sua própria ferramenta de linha de comando.

Trocando de mecanismo¶

Ao iniciar, o editor procura todos os mecanismos que conhece, e a lista suspensa Mecanismo mostra apenas os instalados nesta máquina. Se o mecanismo que você escolheu da última vez não estiver mais lá, o primeiro instalado toma o lugar dele automaticamente. Um mecanismo que você instalar com o editor aberto aparece depois de reiniciar. Sem nenhum mecanismo instalado, a lista mostra todos os mecanismos que o editor conhece, e o painel fica esmaecido com a dica de instalar e fazer login.

Escolha outro agente na lista suspensa Mecanismo quando quiser (ela fica desativada enquanto uma execução está ativa). Trocar cancela a detecção do mecanismo anterior, sonda o novo em segundo plano e inicia conversas novas — um chat começado com um mecanismo não pode ser continuado por outro. Trocar também limpa a transcrição, já que aquela conversa pertencia ao outro mecanismo; o que você tiver digitado no prompt é mantido.

Escolhendo o modelo¶

Por padrão o editor não pede um modelo, então cada execução usa aquele que o seu agente de linha de comando está configurado para usar — no Claude Code, o model do seu ~/.claude/settings.json pessoal. Isso muitas vezes não é o que você quer para o editor: é uma preferência global, pode mudar sem você perceber, e o modelo decide quanto cada requisição custa.

A linha de status diz o que foi usado de fato, então você sempre pode conferir. Para fixar um modelo para o próprio editor, digite-o no chat:

Você digita	O que acontece
`.model claude-sonnet-5`	toda pergunta seguinte pede aquele modelo
`.model`	informa o modelo fixado e o modelo realmente usado por último
`.model default`	remove a fixação; o padrão do próprio agente volta a valer

O .model é tratado pelo editor — ele nunca lança o agente, então responde na hora e não custa nada. Uma fixação passa a valer a partir da sua próxima pergunta, e a linha de status confirma quando a resposta chega.

O mesmo pode ser definido manualmente, por mecanismo, no arquivo de configurações do OctoEdit:

Chave	Valor	Efeito
`ai/model/<engine>`	um id de modelo, p. ex. `claude-sonnet-5`	toda execução usa aquele modelo
`ai/model/<engine>`	vazio / ausente (padrão)	o padrão do próprio agente de linha de comando

<engine> é o id do mecanismo como aparece na lista suspensa, em minúsculas — por exemplo ai/model/claude ou ai/model/codex. É preciso que o painel faça a próxima requisição para que isso valha; depois confirme na linha de status. O Gemini, cujo sinalizador de modelo ainda não foi verificado, ignora a configuração.

Configuração avançada relacionada

ai/programPath/<engine> faz o mesmo trabalho com o binário: defina um caminho absoluto quando o agente estiver instalado em um lugar que a busca por PATH do editor não enxerga. As duas chaves são, de propósito, válvulas de escape apenas por arquivo — um valor errado falha alto em vez de ser ignorado em silêncio.

Quando uma execução falha¶

Se o agente terminar com erro, o chat mostra [agent exited with code N seguido das próprias linhas de erro do agente e de um ] de fechamento — no caso do Codex, o banner de inicialização e as linhas ERROR: … dele, como o 401 Unauthorized que você recebe quando não fez login. Em geral isso basta para saber o que deu errado; rodar o agente uma vez a partir de um terminal conta o resto.

O log do editor (mte.log, veja Registro e diagnóstico) registra cada execução em linhas que começam com AI: — quais mecanismos foram encontrados, o programa e os argumentos de cada execução, o código de saída e as últimas linhas de erro do agente quando uma execução falha; iniciar o editor com --log=debug acrescenta o resto da saída de diagnóstico do agente. A sua pergunta e a resposta nunca aparecem na mensagem de erro e nunca são gravadas no log: o log informa apenas o tamanho da pergunta em bytes.

Privacidade e custo¶

As requisições são enviadas pelo agente de linha de comando que você escolheu, usando a conta e a conexão de rede dele — o editor não acrescenta telemetria nem endpoints próprios. (O Codex repete toda a troca na saída de diagnóstico dele; o editor descarta essa cópia e nunca a grava no log.) O que é enviado (sua instrução, sua seleção ou documento, e o texto não salvo dos documentos abertos quando uma pergunta precisa disso) e quanto custa são regidos pela assinatura ou pelo plano daquele agente. Nada sai do editor sem o aviso de consentimento descrito acima, e a linha de status nomeia o modelo que cada requisição realmente usou.

O que está disponível hoje

Os comandos agem sobre a seleção atual (ou sobre o documento inteiro, com consentimento) e, quando aceitos, a substituem. Há dois níveis de autoridade: o fluxo somente leitura que apenas propõe, descrito acima, ou a adesão explícita por Permitir edições de arquivo. Não existe uma revisão separada, dentro do editor, das edições que o próprio agente faz no disco — com Permitir edições de arquivo ligado, confie no seu controle de versão; a única exceção é um documento aberto com alterações não salvas, cujas edições voltam pelo editor.