Guia rápido de custo do Claude Code: settings, variáveis e comandos
Downshift por Tiago Vilas Boas. Atualizado em
Este Downshift é uma ferramenta em Go para agentes de código com IA, não a biblioteca React downshift de autocomplete.
Resumo
As maiores alavancas de custo são /clear entre tarefas, o modelo certo para cada trabalho, um modelo mais barato para subagentes mecânicos, esforço menor e uma janela de autocompactação menor. Esta página lista o comando, a chave de settings ou a variável exata de cada uma, com a seção da doc que a define, e mostra a única escolha que a doc deixa manual: o modelo do subagente por tarefa.
Todas as alavancas de custo do Claude Code que a Anthropic documenta, em tabelas, cada uma com link para a seção da doc. O que não está na documentação oficial ficou de fora.
Verificado em 2026-10-24 em code.claude.com/docs. Nomes, padrões e versões mínimas mudam entre releases; confirme na página linkada.
Quais comandos do Claude Code mudam o custo?
Comandos e atalhos que mudam o que você envia, qual modelo responde ou quanto contexto fica.
| Nome | Efeito | Doc |
|---|---|---|
/usage | Uso de tokens e custo estimado da sessão, a linha Prompt cache (main) e, em plano, o detalhamento com recomendações. | costs: /usage |
/clear | Começa do zero. A doc manda usar ao trocar para trabalho não relacionado, porque contexto velho gasta tokens em toda mensagem seguinte. | costs: contexto |
/compact [instruções] | Resume a conversa. Instruções como 'Focus on code samples and API usage' guiam o que fica. Em contexto grande, é uma requisição grande. | costs: contexto |
/context | Mostra o que ocupa espaço de contexto, por exemplo a listagem de ferramentas de MCP. | costs: MCP |
/model [alias|nome] | Troca o modelo no meio da sessão. Sem argumento, abre o seletor. Cada modelo tem seu cache, então a troca relê o histórico sem cache. | model-config |
/effort [nível|auto] | Define o nível de esforço. Esforço menor em tarefa simples reduz tokens de raciocínio, cobrados como saída. | model-config: esforço |
/autocompact [tamanho|auto] | Define a janela de autocompactação do modelo atual. | model-config: autocompactação |
/mcp | Lista os servidores MCP configurados para você desligar os que não usa. | costs: MCP |
/rewind | Volta conversa e código a um checkpoint anterior. O rewind aproveita uma entrada de cache antiga em vez de montar um prefixo novo. | prompt-caching: rewind |
/insights | Gera um relatório HTML sobre como você trabalha, a partir de sessões recentes. A análise em si consome tokens. | costs: insights |
Shift+Tab | Passa para o modo de plano: o Claude propõe a abordagem antes de editar. | costs: tarefas complexas |
Quais chaves de settings reduzem o custo do Claude Code?
Chaves do settings.json. As variáveis de ambiente da próxima seção sobrescrevem algumas delas.
| Nome | Efeito | Doc |
|---|---|---|
model | Modelo inicial ao abrir a sessão. É um padrão, não uma imposição. | model-config |
effortLevel | Esforço padrão para modelos sem nível salvo: low, medium, high ou xhigh. | model-config: esforço |
modelSettings | Valores salvos por modelo, incluindo esforço e janela de autocompactação. | model-config: esforço |
autoCompactWindow | Janela de autocompactação, em tokens, para todos os modelos. | model-config: autocompactação |
alwaysThinkingEnabled | Chave global de raciocínio, ajustada em /config. Não dá para desligar o raciocínio no Opus 5.5, Sonnet 5.5, Haiku 5.5 nem no Fable. | costs: raciocínio |
availableModels | Lista de modelos que o usuário pode escolher, para o time não derivar para o mais caro. | model-config: restringir |
promptCacheTtl | Duração do cache da conversa principal: 5m ou 1h (v2.1.242 ou superior). | prompt-caching: TTL |
subagentPromptCacheTtl | Duração do cache de subagentes e demais requisições fora da principal: 5m ou 1h (v2.1.242 ou superior). | prompt-caching: TTL |
idleCompaction | Com false, o Claude Code não compacta uma conversa longa ociosa antes de o cache expirar (v2.1.290 ou superior). | prompt-caching: compactação |
Quais variáveis de ambiente controlam o custo do Claude Code?
Coloque no shell ou no bloco env do settings.json. A lista completa está na página de variáveis de ambiente oficial.
Modelo e esforço
| Nome | Efeito | Doc |
|---|---|---|
ANTHROPIC_MODEL | Modelo da sessão. Sobrescreve a chave model; --model e /model sobrescrevem ela. | model-config |
ANTHROPIC_DEFAULT_OPUS_MODELANTHROPIC_DEFAULT_SONNET_MODELANTHROPIC_DEFAULT_HAIKU_MODEL | ID do modelo para o qual cada alias aponta. A do haiku também atende funções em segundo plano. | env-vars |
CLAUDE_CODE_EFFORT_LEVEL | Esforço: low, medium, high, xhigh, max ou auto. Sobrescreve --effort, /effort e as settings. | model-config: esforço |
MAX_THINKING_TOKENS | Orçamento fixo de raciocínio em modelos que usam um, por exemplo 8000. 0 desliga o raciocínio na maioria dos modelos da API. Modelos de raciocínio adaptativo ignoram valores acima de zero; use esforço neles. | costs: raciocínio |
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING | Com 1, só no Opus 4.6 e no Sonnet 4.6: volta ao orçamento de MAX_THINKING_TOKENS. | model-config: adaptativo |
CLAUDE_CODE_DISABLE_1M_CONTEXT | Com 1, remove as variantes de 1M de contexto; modelos que usam 1M por padrão caem para 200K. | model-config: 1M |
Subagentes
| Nome | Efeito | Doc |
|---|---|---|
CLAUDE_CODE_SUBAGENT_MODEL | Modelo padrão de subagentes e teammates. Fica abaixo do modelo da chamada e do campo model do agente, a menos que seja forçada (linha seguinte). | sub-agents: escolher o modelo |
CLAUDE_CODE_SUBAGENT_MODEL_FORCE | Com 1 (v2.1.257 ou superior), CLAUDE_CODE_SUBAGENT_MODEL vence todas as outras fontes, inclusive o model do frontmatter. | sub-agents: um modelo só |
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS | Limite de subagentes simultâneos por sessão (padrão 20). | env-vars |
CLAUDE_CODE_MAX_TURNS | Limita os turnos do agente quando --max-turns não é passado. | env-vars |
Compactação e tamanho da saída
| Nome | Efeito | Doc |
|---|---|---|
CLAUDE_CODE_AUTO_COMPACT_WINDOW | Janela de autocompactação, de 100000 a 1000000 tokens. Sobrescreve /autocompact, --autocompact e autoCompactWindow. | model-config: autocompactação |
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE | Porcentagem (1 a 100) da janela em que a compactação dispara. Só consegue baixar o limite e vale também para subagentes. | env-vars |
CLAUDE_CODE_MAX_OUTPUT_TOKENS | Máximo de tokens de saída por requisição. Valores altos diminuem o contexto disponível antes da autocompactação. | env-vars |
BASH_MAX_OUTPUT_LENGTH | Caracteres de saída do Bash devolvidos ao resultado (padrão 30000, máximo 150000). | env-vars |
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS | Limite de tokens na leitura de arquivos (padrão 25.000). | env-vars |
Cache de prompt
| Nome | Efeito | Doc |
|---|---|---|
CLAUDE_CODE_PROMPT_CACHE_TTL | Duração do cache da conversa principal, 5m ou 1h (v2.1.242 ou superior). | prompt-caching: TTL |
CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL | Duração do cache de subagentes, workflows, teammates e compactação, 5m ou 1h. | prompt-caching: TTL |
DISABLE_PROMPT_CACHING | Com 1, desliga o cache em todos os modelos. A doc trata como ferramenta de depuração; no uso normal, deixe ligado. | prompt-caching: desligar |
Como definir o modelo do subagente no Claude Code?
Segundo a doc, o Claude Code escolhe o modelo do subagente nesta ordem: o modelo que o Claude passa naquela chamada, depois o model do frontmatter do agente (inherit é o modelo principal), depois CLAUDE_CODE_SUBAGENT_MODEL e por fim o modelo da conversa principal. Antes da v2.1.251, a variável vinha primeiro.
| Nome | Efeito | Doc |
|---|---|---|
model: haiku | Campo do frontmatter na definição do agente. Aceita sonnet, opus, haiku, fable, um ID completo ou inherit. A página de custos sugere haiku para tarefas simples de subagente. | sub-agents: escolher o modelo |
model: inherit | Usa o modelo da conversa principal. | sub-agents: escolher o modelo |
Agente chamado Explore | Um agente de usuário ou de projeto com esse nome e model: haiku substitui o Explore embutido, que de outro modo segue o modelo principal. | sub-agents: escolher o modelo |
| Bloco env com force | Defina CLAUDE_CODE_SUBAGENT_MODEL e CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 para rodar todo subagente num modelo só. Definir só a primeira não muda o Explore nem o Plan embutidos. | sub-agents: um modelo só |
Quais hábitos reduzem o custo por tarefa no Claude Code?
Da página de custos, na ordem que costuma pesar mais.
| Nome | Efeito | Doc |
|---|---|---|
| Rode testes focados, não a suíte inteira | Peça o arquivo ou o nome do teste. Testar em incrementos pega problema cedo, e a saída longa fica fora do contexto. | costs: tarefas complexas |
| Modelo menor para subagente mecânico | Renomear, formatar e localizar arquivo raramente pedem o modelo principal. Use model: haiku no agente ou CLAUDE_CODE_SUBAGENT_MODEL. | costs: modelo certo |
| Delegue o trabalho verboso | Testes, busca em docs e leitura de log voltam como resumo e a saída fica no contexto do subagente. As requisições do subagente ainda consomem seu uso. | costs: subagentes |
| Escreva prompts específicos | Citar o arquivo e a função evita varredura ampla. | costs: prompts |
| Planeje antes em tarefa complexa | O modo de plano evita retrabalho caro quando a primeira direção está errada. | costs: tarefas complexas |
| Mantenha o CLAUDE.md curto | Ele carrega em toda abertura de sessão. Mova instruções de fluxo específico para skills, que carregam sob demanda. A doc mira menos de 200 linhas. | costs: skills |
| Escolha modelo e esforço uma vez | Trocar o modelo ou, na maioria dos modelos, o esforço no meio da sessão faz a próxima requisição reler o histórico inteiro sem cache. | prompt-caching: troca de modelo |
O que o Downshift acrescenta a essas settings?
Tudo acima é manual e não usa software extra. O Downshift automatiza a escolha que as tabelas deixam com você e mantém os números honestos.
| Parte | O que faz | Evidência e limites |
|---|---|---|
| Roteamento por subagente | Um hook PreToolUse pontua cada tarefa delegada localmente e reescreve o modelo do subagente, só quando tem confiança. Na dúvida, mantém o modelo pedido. Nenhum LLM roda no loop de roteamento. | Bateria de quatro braços em 2026-10-21, tarefas mecânicas delegadas, 46 execuções, um operador: cerca de 24% menos tokens por tarefa aceita com roteamento (16% por execução; intervalo de 95% de +2,1% a +46,7%). Não demonstrado em tarefas complexas naturais. |
| Compactor | downshift compact -- <comando> reduz a saída de testes e builds da lista permitida ao resumo de passou ou falhou e mantém o código de saída real. | Corpus de compactação de 2026-10-21, fixtures sintéticas: 82,3% menos bytes nos 26 de 248 arquivos que compactam, 23,7% nos 248. Bytes, não tokens de LLM. |
| DCI (opt-in) | Empacota só o código que a mudança toca, dentro de um orçamento em bytes. | Desligado até você ativar. Latência e tamanho da saída são medidos; a qualidade da resposta não foi validada. |
Números completos: arquivo de evidência dos quatro braços. Um operador, tarefas mecânicas: trate como medição, não como garantia.
Perguntas frequentes
Qual a forma mais rápida de reduzir o custo do Claude Code?
Rode /usage para ver onde os tokens vão, use /clear entre tarefas não relacionadas, escolha Sonnet ou Haiku onde o Opus não é necessário e baixe o esforço em trabalho simples. Defina model: haiku em subagentes que fazem tarefas mecânicas. Tudo isso está na página de custos da Anthropic.
Qual variável de ambiente define o modelo do subagente?
CLAUDE_CODE_SUBAGENT_MODEL define um padrão para os subagentes. Desde a v2.1.251, ela fica abaixo do modelo que o Claude passa na chamada e do model do frontmatter do agente. Some CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (v2.1.257 ou superior) para ela vencer todas as fontes.
Como faço a autocompactação disparar mais cedo?
Defina CLAUDE_AUTOCOMPACT_PCT_OVERRIDE com um percentual de 1 a 100; ela só consegue baixar o limite. Ou ajuste a janela direto com CLAUDE_CODE_AUTO_COMPACT_WINDOW, a chave autoCompactWindow ou /autocompact.
Trocar de modelo ou de esforço no meio da sessão custa mais?
Custa. Cada modelo tem seu cache, então o /model faz a próxima requisição reler o histórico inteiro sem cache. Na maioria dos modelos a troca de esforço também; a doc diz que Opus 5.5, Sonnet 5.5, Haiku 5.5 e Fable 5.1 mantêm o cache com chave de API ou assinatura.
Toda variável desta página está na doc oficial?
Está. O que não apareceu em code.claude.com/docs ficou de fora, e cada linha linka a sua seção. Verificado em 2026-10-24. Padrões e versões mínimas mudam, então confirme no link antes de depender de uma delas.
O Downshift substitui essas settings?
Não. Ele acrescenta roteamento do modelo do subagente por tarefa e compactação de saída por cima delas. O ganho medido é de cerca de 24% menos tokens por tarefa aceita em tarefas mecânicas delegadas (46 execuções, um operador, 2026-10-21), e não foi testado combinado com as outras alavancas.
Instalar o Downshift
Rode downshift setup --dry-run antes para ver cada mudança. downshift setup --undo restaura seus backups.
curl -fsSL https://raw.githubusercontent.com/tiagovilasboas/downshift/main/install.sh | sh && downshift setupPlugin do Claude Code
/plugin install downshift --marketplace tiagovilasboas/downshiftGuias relacionados
Fontes
- Anthropic docsoficial
code.claude.com/docs/en/costs
/usage, reduzir uso de tokens, raciocínio, subagentes (consultado em 2026-10-24) - Anthropic docsoficial
code.claude.com/docs/en/model-config
aliases, chaves de settings, esforço, janela de autocompactação (consultado em 2026-10-24) - Anthropic docsoficial
code.claude.com/docs/en/sub-agents
campo model, precedência, CLAUDE_CODE_SUBAGENT_MODEL(_FORCE) (consultado em 2026-10-24) - Anthropic docsoficial
code.claude.com/docs/en/prompt-caching
controles de TTL, variáveis de desligar, trocas de modelo e esforço (consultado em 2026-10-24) - Anthropic docsoficial
code.claude.com/docs/en/env-vars
autocompactação, esforço, raciocínio, limites de saída, tetos de subagente (consultado em 2026-10-24) - Downshift repomedido
docs/evidence/four-arm-mechanical-2026-10-21.md
números dos quatro braços, intervalo, limites