> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Experimente o Code Mode, um recurso experimental no qual Claude escreve JavaScript que faz várias chamadas de ferramenta em uma única etapa.

O Code Mode muda a forma como Claude usa suas [ferramentas](https://code.claude.com/docs/pt/tools-reference.md). 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.

> [!NOTE]
>
> 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:

```javascript theme={null}
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](https://code.claude.com/docs/pt/interactive-mode.md#transcript-viewer). 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](#permission-checks)
* **Código de longa duração**: a menos que [o código possa ser executado em segundo plano](#long-running-code), você espera que ele termine, e ele é interrompido após dez minutos
* **Hooks**: você pode ver [chamadas de ferramenta recusadas](#tool-call-refused-by-a-hook) quando um hook `PreToolUse` não consegue ser executado ou atinge o timeout, e [saída de código bloqueada](#code-output-withheld-by-a-hook) por um hook `UserPromptSubmit`
* **Recursos indisponíveis**: você não pode usar [Remote Control](https://code.claude.com/docs/pt/remote-control.md), [Claude in Chrome](https://code.claude.com/docs/pt/chrome.md) nem [uso do computador](https://code.claude.com/docs/pt/computer-use.md)
* **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](https://code.claude.com/docs/pt/agent-view.md), 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](https://code.claude.com/docs/pt/setup.md#configure-release-channel). 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](https://code.claude.com/docs/pt/hipaa-setup.md) nem [retenção zero de dados](https://code.claude.com/docs/pt/zero-data-retention.md)
* **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](https://code.claude.com/docs/pt/setup.md) do Claude Code
* **Windows**: o [Git for Windows](https://git-scm.com/downloads/win) 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](#code-mode-doesnt-start).

## Experimente o Code Mode

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

**1. 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`](https://code.claude.com/docs/pt/setup#configure-release-channel).

**2. Inicie o Claude Code com o Code Mode ativado**

Defina a variável de ambiente [`CLAUDE_CODE_EXPERIMENTAL_CODE_MODE`](https://code.claude.com/docs/pt/env-vars#variables) 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.

> [tab] macOS, Linux, WSL
>
> ```bash theme={null}
> CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
> claude
> ```

> [tab] settings.json
>
> Salve este bloco `env` em `~/.claude/settings.json` e inicie o `claude`:
>
> ```json theme={null}
> {
>   "env": {
>     "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
>   }
> }
> ```
>
> O Claude Code [ignora esta variável nos arquivos de configuração de um projeto](https://code.claude.com/docs/pt/settings-reference.md#variables-claude-code-ignores-in-env), portanto um repositório que você clona não pode ativar o Code Mode por você.

**3. 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:

```text theme={null}
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](#code-mode-doesnt-start).

**4. Dê a Claude uma tarefa com muitas chamadas de ferramenta**

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

```text theme={null}
Read every Markdown file in this project and list the links that point to local files that don't exist.
```

**5. 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.

> [!WARNING]
>
> 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](https://code.claude.com/docs/pt/managed-settings.md) para que ninguém na sua organização possa usar o Code Mode:

```json theme={null}
{
  "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](https://code.claude.com/docs/pt/permissions.md) `deny` e `ask` e pelos seus [hooks `PreToolUse`](https://code.claude.com/docs/pt/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](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode)**: 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](#permission-prompt-with-a-countdown)
* **Outros [modos de permissão](https://code.claude.com/docs/pt/permission-modes.md)**: 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`.

> [!WARNING]
>
> 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](https://code.claude.com/docs/pt/permissions.md#bash-rule-limits), com ou sem o Code Mode. Para limites que não dependem do texto do comando, consulte [sandboxing](https://code.claude.com/docs/pt/sandboxing.md).

### 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](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) 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](#requirements).

| O motivo inclui | O que fazer |
| :- | :- |
| `it isn't open to your account yet` | Se sua versão for anterior à v2.1.323, [atualize](#try-code-mode). 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](#requirements), 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](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching), 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](https://code.claude.com/docs/pt/monitoring-usage.md) |
| `it doesn't yet work with an installed mod` | Desative o [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) 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](#block-code-mode-for-your-organization) |

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:

```text theme={null}
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`](https://code.claude.com/docs/pt/hooks#block-the-action-when-a-hook-fails) 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`](https://code.claude.com/docs/pt/hooks#common-fields) 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`](https://code.claude.com/docs/pt/hooks#userpromptsubmit). Quando [o código pode ser executado em segundo plano](#long-running-code), 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`.

## Recursos relacionados

* [Modos de permissão](https://code.claude.com/docs/pt/permission-modes.md): compare o modo auto com os modos que pedem sua confirmação
* [Referência de hooks](https://code.claude.com/docs/pt/hooks.md): escreva hooks `PreToolUse` e `UserPromptSubmit`
* [Configurações gerenciadas](https://code.claude.com/docs/pt/managed-settings.md): aplique uma configuração em toda uma organização