Claude Code no macOS: Meu Setup de Terminal Funcional (Status, Custos, Limites)

Se você quer que Claude Code no macOS seja realmente usável no desenvolvimento do dia a dia, o setup que importa é: oh-my-zsh para contexto do terminal, /terminal-setup para tratamento de entrada, e /statusline com um script customizado para visibilidade em tempo real de custo, modelo e limites de taxa. Tudo o mais é opcional. Este setup funciona igual no Linux e dentro do WSL no Windows, com apenas diferenças menores em caminhos de instalação.

Depois de configurar isso em múltiplos projetos WordPress de produção e fluxos de trabalho de desenvolvimento, a diferença é imediata: você para de adivinhar quanto está gastando, qual modelo está usando e quando vai bater nos limites. É um ganho claro em produtividade, com ganhos reais e economia real. E todo o setup leva menos de 10 minutos.

A primeira vez que rodei Claude Code, meu terminal se parecia exatamente com todos os screenshots que eu havia visto de pessoas reclamando sobre isso: um prompt em branco, nenhum contexto, nenhuma ideia sobre qual modelo estava rodando ou quanto de sessão restava. Só um cursor.

Isso durou cerca de dois dias até eu começar a realmente ler a documentação — e depois ir além dela.

O que segue é o setup real que eu rodo — oh-my-zsh, os comandos Claude Code built-in, e um script de statusline customizado que te dá custo em tempo real, estado da janela de contexto, identidade do modelo e barras de limite de taxa. Nenhum pacote npm para nada disso.

Comece com oh-my-zsh

macOS vem com zsh, e a maioria das distribuições Linux modernas suportam isso nativamente ou via gerenciadores de pacotes, ou você pode tentar iTerm2 no macOS. <a href="https://ohmyz.sh/" rel="nofollow">Oh-my-zsh</a> é o framework que torna isso usável. Instale com:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Abra ~/.zshrc e configure seus plugins. Os que realmente importam para um fluxo de trabalho Claude Code:

plugins=(git zsh-autosuggestions zsh-syntax-highlighting)

zsh-autosuggestions e zsh-syntax-highlighting não vêm agrupados, então você precisa instalá-los primeiro:

git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-syntax-highlighting ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

O que cada um faz: o plugin git coloca seu branch atual no prompt do shell, então você nunca faz troca de contexto para rodar git branch enquanto está dentro de uma sessão Claude. zsh-autosuggestions traz à tona comandos do histórico conforme você digita — útil quando suas invocações claude começam a acumular flags. zsh-syntax-highlighting colore comandos enquanto você digita; caminhos ruins ficam vermelhos antes de você pressionar Enter.

Para um tema, <a href="https://github.com/romkatv/powerlevel10k/" rel="nofollow">Powerlevel10k</a> é a escolha prática: renderização rápida, altamente configurável, e não conflita com o próprio output de status do Claude Code na base do terminal.

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

Então configure ZSH_THEME="powerlevel10k/powerlevel10k" em seu .zshrc e execute source ~/.zshrc para ativar o wizard de configuração.

Você também sempre pode executar o setup com p10k configure.

Instale Claude Code no macOS

Anthropic fornece um instalador nativo que não requer Node.js:

curl -fsSL https://claude.ai/install.sh | sh

Ele se adiciona ao seu PATH dropando uma linha em ~/.zshrc. Source sua config ou abra um novo terminal:

source ~/.zshrc

(No Linux, o mesmo script funciona. No Windows, execute isso dentro do WSL — Claude Code não tem alvo nativo para ambientes PowerShell)

Depois claude em qualquer diretório de projeto. Primeira execução pede autenticação de conta Anthropic. Depois disso, você está dentro.

O caminho npm (npm install -g @anthropic-ai/claude-code) ainda funciona se você já está em um ambiente Node, mas o instalador nativo é o que Anthropic testa e suporta primeiro. Menos dependências significa menos coisas que silenciosamente quebram entre atualizações do macOS.

/terminal-setup: faça isso antes de qualquer coisa

Uma vez que Claude Code está rodando, digite:

/terminal-setup

Isso configura seu emulador de terminal para lidar corretamente com os atalhos de teclado do Claude Code. Os críticos: Shift+Enter para quebras de linha dentro de um prompt sem submeter, e @ como gatilho de referência de arquivo ao invés de um caractere cru.

Antes de executar isso, @ em muitas configurações de terminal ou não fazia nada ou passava como um token de shell. Depois, abre o seletor de arquivo do Claude Code. Você referencia arquivos em seu codebase sem copiar caminhos manualmente.

Um comando, e você fez Claude Code ainda mais poderoso.

/statusline: tornando Claude Code ainda mais inteligente

Agora, execute isso dentro de uma sessão Claude Code:

/statusline

Isso escreve a configuração da statusline para ~/.claude/settings.json e configura um script em ~/.claude/statusline-command.sh. Esse script é o que realmente renderiza a barra de status: Claude Code canaliza dados de sessão para ele como JSON, e ele formata o output.

O output padrão parece OK, mas você pode torná-lo ainda melhor, adicionando algumas instruções ao comando

/statusline Add two line, one with the model being used, the branch you are working on, costs, and session time. In the second line, add the rate limits for the 5-hour period and the week period.

Você terá algo assim:

[4.6] 📁 project | 🌿 no-branch | $0.00 | 🕐 46h 57m 56s
5-hour: [░░░░░░░░] 100% avail   Week: [█░░░░░░░] 87% avail
──────────────────────────────────────────────

Linha por linha:

Linha 1 — [Model] mostra a versão ativa do modelo (Sonnet 4.6 renderiza como 4.6, Opus 4.6 como 4.6 com uma cor diferente). Pasta é o diretório do projeto atual. Branch é o branch git ativo — ou no-branch fora de um repo. Custo é estimado a partir de contagens de tokens em tempo real. Depois temos a duração da sessão.

Linha 2 — Barras de limite de taxa. Blocos preenchidos (█) são cota consumida, blocos vazios (░) são o que sobra. Cor muda com o uso: verde abaixo de 50%, laranja de 50–80%, vermelho brilhante acima de 80%. A barra de 5 horas redefine em uma janela de rolagem; a barra semanal redefine segunda-feira.

Linha 3 — Um divisor atenuado para separar visualmente o status do prompt.

O que está realmente em settings.json

O comando /statusline conecta isso em ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash ~/.claude/statusline-command.sh"
  }
}

Claude Code executa esse comando toda vez que atualiza a barra de status, canalizando estado de sessão como JSON. O script lê com jq e gera texto formatado. Você pode editar o script diretamente para mudar o que é exibido, as cores, a largura da barra, qualquer coisa.

Por que cada elemento importa

A janela de contexto não é rastreada aqui: a statusline usa contagens de tokens para estimativa de custo, não um medidor de contexto. Para estado da janela de contexto, o footer built-in do Claude Code lida com isso separadamente. Mas custo e limites de taxa são o que a maioria das pessoas voa às cegas.

O display de custo constrói um senso de linha de base. Depois de uma semana de sessões, você sabe o que uma refatoração típica custa. Quando uma sessão roda 3x isso, você nota imediatamente, antes do final do mês na fatura.

As barras de limite de taxa existem porque Claude Code tem dois limites de throttle separados: um limite de rolagem de 5 horas e um limite semanal. Eles são independentes. Você pode queimar 80% de seu allowance de 5 horas em uma sessão longa e ainda ter 90% de sua cota semanal. Saber qual está apertando muda o que você faz a seguir: posso esperar a janela de 5 horas para testar minhas mudanças? Ou é melhor continuar mesmo assim?

O indicador de modelo detecta algo sutil: Claude Code pode automaticamente mudar modelos durante uma sessão baseado em carga ou sua categoria de plano. Ou você pode ter selecionado um modelo mais barato ou mais caro usando /models e esqueceu da mudança. Ver [4.6] versus o que você esperava te diz imediatamente se isso aconteceu.

Colocando tudo junto

Dois aliases que valem a pena adicionar ao ~/.zshrc:

alias cc="claude"
alias ccc="claude --continue"

--continue retoma a última sessão ao invés de começar nova. Para qualquer coisa além de um quick fix, é assim que o trabalho sustentado realmente roda.

A forma completa de ~/.claude/settings.json, com statusline e o setup de permissões mínimo:

{
  "statusLine": {
    "type": "command",
    "command": "bash ~/.claude/statusline-command.sh"
  },
  "permissions": {
    "defaultMode": "default"
  }
}

No Windows (WSL), adicione esses ao seu .zshrc ou .bashrc, dependendo do seu shell

Tudo o mais em settings é opcional. O bloco statusline é o que ativa o script.

Depois de rodar /terminal-setup e /statusline, seu ambiente de trabalho mostra: branch git no prompt do shell (via oh-my-zsh), modelo e branch na barra de status do Claude, custo e estado de limite de taxa visível o tempo todo. Você sabe quando encerrar uma sessão antes do contexto se degradar. Você sabe o que está gastando. Você sabe qual modelo você realmente está conversando.

O que isso não conserta

É importante deixar algo claro: nenhuma dessas mudanças fará Claude mais inteligente. O modelo é o modelo. O que faz é dar informações para trabalhar bem com ele: quando começar novo, o que uma sessão realmente está custando, e se um limite de taxa está apertando.

Trabalhar sem essas informações é como programar sem saber se suas mudanças foram salvas. Tecnicamente possível, mas você vai descobrir do jeito difícil eventualmente.

Os comandos /terminal-setup e /statusline estão na documentação oficial do Claude Code{rel="nofollow"}. O script statusline em si é um arquivo bash simples que você possui e pode modificar. Entenda o que está fazendo antes de editá-lo — o schema JSON que Claude Code canaliza muda ocasionalmente entre releases, e jq te dirá rapidamente se suas mudanças quebraram algo.

Acerte o ambiente primeiro. Tudo o mais roda em cima dele.

---

Se você está integrando Claude em fluxos de trabalho de produção ou construindo recursos assistidos por IA para clientes, é o tipo de trabalho que faço.