Execute chamadas de ferramenta a partir de código com o Code Mode

O Code Mode muda a forma como Claude usa suas ferramentas. Sem o Code Mode, Claude solicita chamadas de ferramenta como Bash, Read ou Edit diretamente e lê cada resultado antes de decidir o que fazer em seguida. Com o Code Mode, Claude escreve um trecho de JavaScript que faz as chamadas de ferramenta, e o Claude Code executa esse código na sua sessão.

O Code Mode é experimental e fica desativado por padrão. Ele pode mudar ou ser removido em qualquer versão. Para compartilhar feedback, execute /feedback.

Como o Code Mode funciona

Em uma sessão do Code Mode, você ainda descreve sua tarefa em um prompt, e Claude escreve JavaScript para realizá-la. Um único trecho de código pode executar comandos em paralelo, usar um resultado na chamada seguinte e retornar a parte da saída que Claude precisa ler. Por exemplo, se você pedir a Claude para aumentar um limite de novas tentativas, Claude pode escrever este código para encontrar o arquivo, editá-lo e executar os testes. A última linha retorna a Claude o caminho do arquivo e a saída dos testes:

const files = await $`rg -l "function retryPolicy" src`.text();
const target = files.trim().split("\n")[0];
await edit(target, "maxAttempts: 3", "maxAttempts: 5");
({ edited: target, tests: $`npm test -- retryPolicy`.nothrow() });

Na conversa, você vê as chamadas de ferramenta, como o diff da edição, e não o código. Para ler o código, pressione Ctrl+O para abrir o visualizador de transcrição. Cada trecho de código aparece ali como uma linha Code recolhida, com uma dica de como expandi-la.

Quando usar o Code Mode

Experimente o Code Mode em tarefas que exigem muitas chamadas de ferramenta relacionadas, como:

Uma alteração que se repete em muitos arquivos
Uma pesquisa cujos resultados precisam ser filtrados antes que Claude os leia
Vários comandos independentes que podem ser executados ao mesmo tempo

Limitações do Code Mode

Antes de ativar o Code Mode, verifique se você pode aceitar estas limitações:

Retomada: você pode retomar uma sessão do Code Mode apenas no terminal, com o Code Mode ativado
Modo auto: o classificador do modo auto revisa o código, não cada chamada de ferramenta
Código de longa duração: a menos que o código possa ser executado em segundo plano, você espera que ele termine, e ele é interrompido após dez minutos
Hooks: você pode ver chamadas de ferramenta recusadas quando um hook PreToolUse não consegue ser executado ou atinge o timeout, e saída de código bloqueada por um hook UserPromptSubmit
Recursos indisponíveis: você não pode usar Remote Control, Claude in Chrome nem uso do computador
Mover a sessão: você não pode mover a sessão para o aplicativo Desktop nem transformá-la em uma sessão em segundo plano, e /fork não consegue iniciar uma cópia em segundo plano

Requisitos

Versão: Claude Code v2.1.323 ou posterior, em qualquer um dos canais de lançamento. Uma versão mais antiga inicia sem o Code Mode, com ou sem o motivo it isn't open to your account yet
Conta: uma assinatura do Claude ou uma conta do Console. Você não pode usar o Code Mode por meio de um gateway, Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud ou Microsoft Foundry
Organização: sua organização não usa a configuração HIPAA nem retenção zero de dados
Modelo: Claude Opus 5.5, Sonnet 5.5, Haiku 5.5 ou Fable 5.2
Superfície: uma sessão interativa do claude em um terminal. O Code Mode não funciona com -p, o Agent SDK, o painel do VS Code, o aplicativo Desktop ou sessões na nuvem
Instalação: o build nativo do Claude Code
Windows: o Git for Windows está instalado

Você também não pode iniciar o Code Mode com algumas configurações ativadas, como um auxiliar de chave de API, equipes de agentes, exportação do OpenTelemetry ou DISABLE_TELEMETRY. Para a correção de cada uma, consulte O Code Mode não inicia.

Experimente o Code Mode

Ative o Code Mode, dê uma tarefa a Claude e veja o código que Claude escreveu.

Verifique sua versão

Execute claude --version. Se a versão for anterior à v2.1.323, execute claude update. Se você estiver no canal stable e a atualização não chegar à v2.1.323, aguarde o stable alcançá-la ou mude para latest.

Inicie o Claude Code com o Code Mode ativado

Defina a variável de ambiente CLAUDE_CODE_EXPERIMENTAL_CODE_MODE como 1. Para experimentar o Code Mode, defina-a no seu shell. Para ativar o Code Mode em todas as novas sessões, defina-a nas suas configurações de usuário.

macOS, Linux, WSL
Windows PowerShell
settings.json

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

$env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
claude

Salve este bloco env em ~/.claude/settings.json e inicie o claude:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
  }
}

O Claude Code ignora esta variável nos arquivos de configuração de um projeto, portanto um repositório que você clona não pode ativar o Code Mode por você.

Confirme que você quer o Code Mode

O Claude Code pede que você confirme antes da sua primeira sessão do Code Mode. Selecione Yes, turn on Code Mode. O Claude Code é reiniciado e mostra esta linha perto do topo da sessão:

Code Mode (experimental) is on · this session can be resumed only with Code Mode on

Se você vir uma linha diferente ou nenhuma, consulte O Code Mode não inicia.

Dê a Claude uma tarefa com muitas chamadas de ferramenta

Em um projeto que você conhece, envie um prompt como este:

Read every Markdown file in this project and list the links that point to local files that don't exist.

Leia o código que Claude escreveu

Pressione Ctrl+O e expanda uma linha Code para ver o JavaScript por trás das chamadas de ferramenta. Pressione Ctrl+O novamente para voltar à conversa.

Para retomar uma sessão do Code Mode depois, mantenha CLAUDE_CODE_EXPERIMENTAL_CODE_MODE definida como 1 ao executar claude --continue ou claude --resume. Com o Code Mode desativado, o Claude Code se recusa a retomar a sessão. Sessões que você iniciou sem o Code Mode são retomadas sem o Code Mode, mesmo com a variável definida.

Desativar o Code Mode

Remova CLAUDE_CODE_EXPERIMENTAL_CODE_MODE do seu shell e de ~/.claude/settings.json e, em seguida, inicie uma nova sessão. Você também pode manter a variável e alterar seu valor para 0 em qualquer um dos dois lugares. Com um 0 em um dos lugares, o Code Mode permanece desativado mesmo que você defina 1 no outro.

Bloquear o Code Mode para sua organização

Adicione CLAUDE_CODE_EXPERIMENTAL_CODE_MODE com o valor 0 às suas configurações gerenciadas para que ninguém na sua organização possa usar o Code Mode:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0"
  }
}

Usuários que estão em uma sessão do Code Mode permanecem nela até sair ou reiniciar o Claude Code. Depois disso, seus usuários iniciam sem o Code Mode e não podem retomar suas sessões do Code Mode enquanto o 0 estiver em vigor. Você não pode ativar o Code Mode para seus usuários a partir das configurações gerenciadas.

Permissões e código de longa duração

Seu modo de permissão decide como o código de Claude é verificado e se você pode conversar com Claude enquanto o código é executado.

Verificações de permissão

Cada chamada de ferramenta que o código de Claude faz passa pelas suas regras de permissão deny e ask e pelos seus hooks PreToolUse. Você não precisa alterar uma regra ou um matcher para uma ferramenta como Bash. Além das regras e dos hooks, um classificador revisa o código no modo auto, e você responde aos prompts nos modos que pedem confirmação:

Modo auto: o classificador revisa cada trecho de código antes de ser executado, não cada chamada de ferramenta. Ele não vê valores calculados em tempo de execução, como um caminho obtido da saída de uma pesquisa, portanto mantenha regras ou hooks para as chamadas que você precisa controlar. Você ainda pode receber prompts quando um novo código começa enquanto um código anterior está em execução
Outros modos de permissão: o código começa sem revisão, e você recebe um prompt para cada chamada de ferramenta que solicitaria sua confirmação nesse modo

Para verificar o próprio código, escreva um hook PreToolUse que corresponda a REPL, a ferramenta que executa o código de Claude, e leia o JavaScript de tool_input.code.

As regras de Bash correspondem ao texto do comando, portanto Claude pode executar um comando negado em uma forma que a regra não corresponde, com ou sem o Code Mode. Para limites que não dependem do texto do comando, consulte sandboxing.

Código de longa duração

Enquanto o código executa um build ou teste demorado, Claude espera por ele ou o deixa continuar em segundo plano:

Esperando: Claude responde depois que o código termina, e o código é interrompido após dez minutos, incluindo o tempo que você passa nos prompts de permissão
Segundo plano: você pode continuar conversando com Claude, e o código pode ser executado por até duas horas

Para código em segundo plano, inicie sua sessão no modo auto ou bypassPermissions. Se Claude ainda esperar, verifique seu modo atual e como você iniciou a sessão:

Você mudou para outro modo: pressione Shift+Tab até voltar ao modo em que você começou
Você começou em outro modo ou escolheu a sessão na lista do claude --resume: se o modo auto estiver disponível para você, saia e, em seguida, execute claude --continue --permission-mode auto com o Code Mode ativado
Você passou nomes de ferramentas para --tools: comece novamente no modo auto sem essa flag

Solução de problemas

O Code Mode não inicia

Code Mode (experimental) isn't available perto do topo da sessão significa que o Claude Code foi iniciado sem o Code Mode. O motivo aparece em seguida na mesma linha, e /status também o mostra. Encontre o motivo nesta tabela, faça a alteração e inicie uma nova sessão. Para um motivo que não está listado, verifique os requisitos.

O motivo inclui	O que fazer
`it isn't open to your account yet`	Se sua versão for anterior à v2.1.323, atualize. Caso contrário, verifique sua conexão de rede e comece novamente. Se o motivo persistir, tente novamente em outro dia
`it only works with the Anthropic API`	Remova as configurações que encaminham requisições por meio de um provedor de nuvem, um gateway ou um `ANTHROPIC_BASE_URL` personalizado
`it doesn't work with an API key helper`	Remova `apiKeyHelper`, `ANTHROPIC_AUTH_TOKEN` e qualquer cabeçalho `Authorization` ou `X-Api-Key` em `ANTHROPIC_CUSTOM_HEADERS`. Em seguida, faça login ou defina `ANTHROPIC_API_KEY`
`it only works with Opus 5.5, Sonnet 5.5 and later models`	Comece com um modelo compatível, por exemplo com `--model opus`. Haiku 5.5 e Fable 5.2 também funcionam
`it doesn't work in background jobs`	Comece em primeiro plano, sem `--remote-control`
`it needs settings that Claude Code downloads from Anthropic`	Remova a definição da variável que desativa a busca de feature flags, como `DISABLE_TELEMETRY`
`OpenTelemetry is on`	Remova a definição de `CLAUDE_CODE_ENABLE_TELEMETRY` e `ENABLE_BETA_TRACING_DETAILED` se você puder trabalhar sem a exportação do OpenTelemetry
`it doesn't yet work with an installed mod`	Desative o mod que verifica as chamadas de ferramenta
`it can't be used together with agent teams yet`	Remova a definição de `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`
`this launch's tool options`	Comece sem `--restricted`, adicione `REPL` a `--tools` e remova `REPL` de `--disallowedTools` e das suas regras `deny`
`couldn't save your answer`	Torne `~/.claude.json` gravável
`your organization's settings don't allow it`	Pergunte ao seu administrador sobre a configuração gerenciada

Se você não vir nenhuma linha sobre o Code Mode, execute claude --version. Se sua versão for anterior à v2.1.323, atualize. Em seguida, verifique se CLAUDE_CODE_EXPERIMENTAL_CODE_MODE está como 1 no seu shell ou nas suas configurações de usuário e remova qualquer 0 desses lugares e de qualquer arquivo --settings.

Prompt de permissão com uma contagem regressiva

Quando Claude inicia mais código no modo auto enquanto um código anterior ainda está em execução, o código anterior perde a revisão do classificador. O Claude Code então pergunta a você sobre as chamadas restantes do código anterior que precisariam de revisão. Sem um IDE conectado, o prompt mostra uma contagem regressiva:

Claude Code will automatically block this request in 1:59, to avoid holding up an unattended session

Responda antes que a contagem regressiva termine. Caso contrário, essa chamada é recusada, e as chamadas posteriores que mostrariam uma contagem regressiva são recusadas sem prompt. Para ver os prompts novamente, envie uma mensagem a Claude.

Chamada de ferramenta recusada por um hook

Se Claude relatar uma chamada de ferramenta recusada, peça a ele o texto do erro. Estes erros significam que um hook PreToolUse não deu uma decisão, o que recusa a chamada mesmo quando onFailure não está definido:

the hook failed: em uma chamada do código de Claude, seu hook não conseguiu iniciar, foi encerrado, saiu com 126, 127 ou um código acima de 128, ou retornou um erro HTTP ou uma saída inválida. Corrija o hook
the hook did not finish: seu hook atingiu o timeout em uma chamada do código de Claude, ou em qualquer outra chamada de ferramenta depois que Claude executou código na sessão. Aumente o timeout do hook

Para permitir que as chamadas prossigam quando um hook command ou http falha ou atinge o timeout, defina "onFailure": "continue" nele. Se um hook command sair com um código comum, como 1, a chamada prossegue, a menos que você defina "onFailure": "block".

Saída de código retida por um hook

Se Claude relatar o motivo de bloqueio de um hook onde você esperava a saída do código de Claude, verifique seus hooks UserPromptSubmit. Quando o código pode ser executado em segundo plano, os hooks command, http e mcp_tool nesse evento também são executados sobre a saída do código. Para deixar a saída passar, altere o hook para que ele não bloqueie quando source na sua entrada for poll_event.

Modos de permissão: compare o modo auto com os modos que pedem sua confirmação
Referência de hooks: escreva hooks PreToolUse e UserPromptSubmit
Configurações gerenciadas: aplique uma configuração em toda uma organização

Configurações

Permissões e sandboxing

Ambientes

Modelo e respostas

Interface

Execute chamadas de ferramenta a partir de código com o Code Mode

Como o Code Mode funciona

Quando usar o Code Mode

Limitações do Code Mode

Requisitos

Experimente o Code Mode

Desativar o Code Mode

Bloquear o Code Mode para sua organização

Permissões e código de longa duração

Verificações de permissão

Código de longa duração

Solução de problemas

O Code Mode não inicia

Prompt de permissão com uma contagem regressiva

Chamada de ferramenta recusada por um hook

Saída de código retida por um hook

Como o Code Mode funciona

Quando usar o Code Mode

Limitações do Code Mode

Requisitos

Experimente o Code Mode

Desativar o Code Mode

Bloquear o Code Mode para sua organização

Permissões e código de longa duração

Verificações de permissão

Código de longa duração

Solução de problemas

O Code Mode não inicia

Prompt de permissão com uma contagem regressiva

Chamada de ferramenta recusada por um hook

Saída de código retida por um hook

Recursos relacionados