Configure seu terminal para Claude Code

Corrija Shift+Enter para novas linhas, obtenha um sinal sonoro do terminal quando Claude terminar, configure tmux, corresponda ao tema de cores e ative o modo Vim na CLI do Claude Code.

Claude Code funciona em qualquer terminal sem configuração. Esta página é para quando algo específico não está se comportando da forma que você espera. Encontre seu sintoma abaixo. Se tudo já se sentir certo, você não precisa desta página.

• Shift+Enter envia em vez de inserir uma nova linha
• Atalhos de tecla Option não funcionam no macOS
• Sem som ou alerta quando Claude termina
• Você executa Claude Code dentro do tmux
• Backspace deleta uma palavra inteira no Windows
• A exibição cintila ou o scrollback salta
• Você quer teclas Vim no prompt

Esta página é sobre fazer seu terminal enviar os sinais corretos para Claude Code. Para alterar quais teclas Claude Code responde, consulte atalhos de teclado em vez disso.

Inserir prompts multilinhas

Pressionar Enter envia sua mensagem. Para adicionar uma quebra de linha sem enviar, pressione Ctrl+J, ou digite \ e depois pressione Enter. Ambos funcionam em todo terminal sem necessidade de configuração.

Na maioria dos terminais você também pode pressionar Shift+Enter, mas o suporte varia de acordo com o emulador de terminal:

Para VS Code, Cursor, Devin Desktop, Alacritty anterior a 0.16 e Zed, /terminal-setup escreve um atalho de teclado Shift+Enter no arquivo de configuração do terminal. Na primeira execução você vê uma confirmação como Installed VSCode terminal Shift+Enter key binding. Os bindings existentes são mantidos no lugar; se você vir uma mensagem como VSCode terminal Shift+Enter key binding already configured, nenhuma alteração foi feita. Execute /terminal-setup diretamente no terminal do host em vez de dentro de tmux ou screen, pois ele precisa escrever na configuração do terminal do host.

No VS Code, Cursor e Devin Desktop, /terminal-setup também atualiza duas configurações do editor: define terminal.integrated.gpuAcceleration para "off" para evitar texto distorcido no terminal integrado, e define terminal.integrated.mouseWheelScrollSensitivity para rolagem mais suave no modo tela cheia. Para desfazer a alteração de aceleração de GPU, defina-a de volta para "auto" e recarregue a janela do editor.

No Zed, /terminal-setup atualiza seu keymap.json no local:

• Se o keymap já tiver bindings e nenhum deles for um Terminal shift-enter, Claude Code primeiro faz um backup para uma cópia no mesmo diretório, como keymap.json.1a2b3c4d.bak, depois mescla o binding Shift+Enter em seu keymap, mantendo seus outros atalhos de teclado e comentários
• Se Claude Code não conseguir ler ou analisar o keymap, não conseguir fazer backup, ou não conseguir verificar o resultado mesclado, ele deixa o arquivo inalterado e imprime o bloco de binding para você adicionar você mesmo

Se você está executando dentro de tmux, Shift+Enter também requer a configuração de tmux abaixo mesmo quando o terminal externo a suporta.

Para vincular nova linha a uma tecla diferente, ou para trocar o comportamento para que Enter insira uma nova linha e Shift+Enter envie, mapeie as ações chat:newline e chat:submit em seu arquivo de atalhos de teclado.

Ativar atalhos de teclado Option no macOS

Alguns atalhos de teclado do Claude Code usam a tecla Option, como Option+Enter para uma nova linha ou Option+P para alternar modelos. No macOS, a maioria dos terminais não envia Option como um modificador por padrão, portanto esses atalhos não funcionam até que você o ative. A configuração do terminal para isso geralmente é rotulada como "Use Option as Meta Key"; Meta é o nome histórico do Unix para a tecla agora rotulada como Option ou Alt.

[tab] Apple Terminal

Abra Configurações → Perfis → Teclado e marque "Use Option as Meta Key".

Se você aceitou o prompt de configuração do terminal na primeira execução do Claude Code, isso já foi feito. Esse prompt executa /terminal-setup para você, que ativa Option como Meta e desativa o sino audível no seu perfil do Apple Terminal.

No modo leitor de tela, /terminal-setup deixa a configuração do sino inalterada para que o sino do terminal permaneça audível. Se uma execução anterior desativou o sino, ative-o novamente em Configurações → Perfis → Avançado → "Audible bell".

[tab] iTerm2

Abra Configurações → Perfis → Teclas → Geral e defina a tecla Option esquerda e a tecla Option direita como "Esc+".

Executar /terminal-setup no iTerm2 ativa "Applications in terminal may access clipboard" em Configurações → Geral → Seleção para que o comando /copy possa escrever na sua área de transferência do sistema. O comando detecta iTerm2 mesmo quando executado dentro do tmux. Reinicie o iTerm2 para que a alteração tenha efeito.

[tab] VS Code

Adicione "terminal.integrated.macOptionIsMeta": true às suas configurações do VS Code.

Para Ghostty, Kitty e outros terminais, procure por uma configuração Option-as-Alt ou Option-as-Meta no arquivo de configuração do terminal.

Obtenha um sinal sonoro do terminal ou notificação

Quando Claude termina uma tarefa ou pausa para um prompt de permissão, e você parece estar longe do terminal, ele dispara um evento de notificação. Veja quando cada tipo de notificação é disparado para o tempo exato. Exibir isso como um sinal sonoro do terminal ou notificação de desktop permite que você mude para outro trabalho enquanto uma tarefa longa é executada.

Por padrão, Claude Code envia uma notificação de desktop em alguns terminais e, em outros, um caractere de sinal sonoro ou nada:

• Ghostty, Kitty e iTerm2, quando Claude Code os detecta: uma notificação de desktop, que o iTerm2 exibe somente depois que você ativa as configurações de alerta dele.
• Apple Terminal: nenhum som; um caractere de sinal sonoro silencioso quando Claude Code encontra "Audible bell" desativado no perfil da janela do Terminal em primeiro plano, caso contrário, nada. Esse caractere de sinal sonoro aparece como um piscar da janela, ou um salto no Dock enquanto o Terminal está em segundo plano, se a opção "Visual bell" ou de salto no Dock desse perfil estiver ativada.
• Outros terminais: nada.

Para fazer Claude Code enviar o caractere de sinal sonoro independentemente do terminal ou perfil, defina preferredNotifChannel como "terminal_bell". No Apple Terminal, ative também Audible bell em Settings > Profiles > Advanced para ouvi-lo. A seguinte entrada de configurações define o canal:

{
  "preferredNotifChannel": "terminal_bell"
}

Via SSH a partir de um terminal executado fora do tmux, defina preferredNotifChannel como o valor do seu terminal local, "iterm2", "kitty" ou "ghostty", na máquina que executa Claude Code. A notificação de desktop então chega à sua máquina local. Ghostty e Kitty a encaminham para seu centro de notificações do SO sem configuração adicional. iTerm2 requer que você ative o encaminhamento:

1. Abra as configurações de notificação do iTerm2

Vá para Configurações → Perfis → Terminal.

2. Ative alertas

Marque "Notification Center Alerts", depois clique em "Filter Alerts" e ative "Send escape sequence-generated alerts".

Se as notificações ainda não aparecerem, confirme que seu aplicativo de terminal tem permissão de notificação nas configurações do SO, e se você está executando dentro do tmux, ative passthrough.

Reproduza um som com um hook de Notification

Em qualquer terminal, você pode configurar um hook de Notification para reproduzir um som ou executar um comando personalizado quando Claude precisar de sua atenção. Hooks são executados junto com a notificação integrada em vez de substituí-la, portanto terminais que não recebem uma notificação de desktop, como Warp ou o terminal integrado do VS Code, podem usar um hook ou definir preferredNotifChannel como "terminal_bell" em vez disso.

O exemplo abaixo reproduz um som do sistema no macOS. O guia vinculado tem comandos de notificação de desktop para macOS, Linux e Windows.

{
  "hooks": {
    "Notification": [
      {
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
      }
    ]
  }
}

Ver o status da sessão no seu terminal

Se o seu terminal implementa o OSC 7501 Program Status Protocol, ele pode mostrar se cada sessão interativa do Claude Code está trabalhando, aguardando você ou concluída, o que ajuda quando você executa tarefas longas ou várias sessões ao mesmo tempo. Não há nada para ativar no Claude Code. Para descobrir se o seu terminal implementa o protocolo e onde ele mostra o status, consulte a documentação dele.

Se ele implementa e você não vê nenhum status para uma sessão, verifique cada uma destas causas:

• Versão do Claude Code: o relato de status requer o Claude Code v2.1.295 ou posterior. Execute claude --version no seu shell para verificar.
• tmux: dentro do tmux, o Claude Code verifica o suporte no tmux em vez de no seu terminal, e allow-passthrough não tem efeito sobre isso. Inicie a sessão fora do tmux.
• Sessão em segundo plano: uma sessão em segundo plano não relata seu status ao seu terminal, mesmo enquanto você está conectado a ela. A visualização de agentes mostra o status dela em vez disso.
• CLAUDE_CODE_DISABLE_TERMINAL_TITLE: se você definir essa variável como 1, o Claude Code não verifica o suporte nem relata o status. Remova a definição dela.

O título da aba não começa com um glifo de status em um terminal que informa suporte ao protocolo. O próprio terminal mostra o estado da sessão, então o Claude Code omite o glifo que coloca na frente do título em outros terminais.

Configurar tmux

Quando Claude Code é executado dentro do tmux, por padrão Shift+Enter envia em vez de inserir uma nova linha, e notificações de desktop não chegam ao terminal externo. Adicione estas linhas a ~/.tmux.conf, depois execute tmux source-file ~/.tmux.conf para aplicá-las ao servidor em execução:

set -g allow-passthrough on
set -g focus-events on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Para enviar notificações de um painel visível ao terminal externo, mantenha a linha allow-passthrough e defina preferredNotifChannel como "iterm2", "kitty" ou "ghostty". Com este exemplo, um painel em uma janela que você não está visualizando não envia nenhuma. As linhas extended-keys permitem que o tmux distinga Shift+Enter de Enter simples para que o atalho de nova linha funcione.

Um Image de um mod precisa das linhas allow-passthrough e focus-events, junto com os outros requisitos para desenhar dentro do tmux. Depois de adicionar as linhas, desanexe-se também do tmux, anexe-se novamente e reinicie o Claude Code.

Corrigir Backspace deletando uma palavra inteira no Windows

No Windows, Claude Code lê um Backspace que chega como ^H como Ctrl+Backspace, que deleta a palavra anterior, exceto quando TERM_PROGRAM é mintty ou TERM é cygwin. No macOS e Linux, Claude Code o lê como Backspace simples.

Se cada pressão de Backspace deleta uma palavra inteira, seu terminal envia ^H para Backspace simples. Defina CLAUDE_CODE_BS_AS_CTRL_BACKSPACE=0. Backspace e Ctrl+H então apagam um caractere cada. Se Ctrl+Backspace apaga apenas um caractere no macOS ou Linux porque seu terminal envia ^H para ele, defina a variável para 1 em vez disso.

Combinar o tema de cores

Use o comando /theme, ou o seletor de temas em /config, para escolher um tema do Claude Code que combine com o seu terminal. Selecionar a opção automática detecta o fundo claro ou escuro do seu terminal, de modo que o tema acompanha as mudanças de aparência do sistema operacional sempre que o seu terminal as acompanhar. O Claude Code não controla o esquema de cores do próprio terminal, que é definido pelo aplicativo de terminal.

Para personalizar o que aparece na parte inferior da interface, configure uma linha de status personalizada que mostre o modelo atual, o diretório de trabalho, o branch do git ou outro contexto.

Criar um tema personalizado

Além das predefinições integradas, /theme lista todos os temas personalizados que você definiu e todos os temas fornecidos por plugins instalados. Selecione New custom theme… no final da lista para criar um de forma interativa: você dá um nome ao tema e, em seguida, escolhe tokens de cor individuais para sobrescrever. Pressione Ctrl+E enquanto um tema personalizado estiver destacado para editá-lo.

Cada tema personalizado é um arquivo JSON em ~/.claude/themes/. O nome do arquivo sem a extensão .json é o slug do tema, e selecionar o tema armazena custom:<slug> como sua preferência de tema. O arquivo tem três campos opcionais:

Os valores de cor aceitam #rrggbb, #rgb, rgb(r,g,b), ansi256(n) ou ansi:<name>, onde <name> é um dos 16 nomes de cores ANSI padrão, como red ou cyanBright. Tokens desconhecidos e valores de cor inválidos são ignorados, portanto um erro de digitação não pode quebrar a renderização.

O exemplo a seguir define um tema que mantém a predefinição dark, mas muda a cor do destaque do prompt, do texto de erro e do texto de sucesso:

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

O Claude Code monitora ~/.claude/themes/ e recarrega quando um arquivo é adicionado ou alterado, de modo que as edições feitas no seu editor se aplicam a uma sessão em execução sem reinicialização. Se a pasta ~/.claude/themes/ em si não existia quando o Claude Code foi iniciado, reinicie uma vez depois de criar seu primeiro arquivo de tema. Depois disso, as alterações se aplicam sem reinicialização.

A referência abaixo aborda os tokens que você pode definir em overrides. O editor interativo em /theme mostra os mesmos tokens com uma pré-visualização ao vivo, além de alguns destaques de propósito único, como as cores da tela de integração, que são omitidos aqui.

[accordion] Referência de tokens de cor

O exemplo a seguir combina tokens de vários dos grupos abaixo: o destaque da marca, a borda do modo de planejamento, os fundos do diff e o fundo das mensagens.

{
  "name": "Midnight",
  "base": "dark",
  "overrides": {
    "claude": "#a78bfa",
    "planMode": "#38bdf8",
    "diffAdded": "#14532d",
    "diffRemoved": "#7f1d1d",
    "userMessageBackground": "#1e1b4b"
  }
}

Cores de texto e de destaque

Controlam o destaque principal da marca e os tons de texto em primeiro plano usados em toda a interface.

Token	Controla
claude	Destaque principal da marca, usado no spinner e no rótulo do assistente
text	Texto padrão em primeiro plano
inverseText	Texto desenhado sobre um fundo colorido, como selos de status
inactive	Texto secundário, como dicas, carimbos de data/hora e itens desativados
subtle	Bordas tênues e texto secundário menos enfatizado
suggestion	Sugestões de preenchimento automático e destaque de seleção nos seletores
permission	Bordas de diálogos, incluindo prompts de permissão e seletores
remember	Indicadores de memória e de CLAUDE.md

Cores de status

Sinalizam estados de sucesso, falha e aviso em mensagens e indicadores.

Token	Controla
success	Mensagens de sucesso e verificações aprovadas
error	Mensagens de erro e falhas
warning	Avisos, mensagens de cautela e o indicador do modo auto
merged	Status de pull request mesclado

Caixa de entrada e indicadores de modo

Definem a cor da borda da caixa de entrada e o destaque exibido enquanto um modo de permissão ou indicador está ativo.

Token	Controla
promptBorder	Borda da caixa de entrada
planMode	Destaque do modo de planejamento, mensagens de plano e diálogos do modo de planejamento
autoAccept	Destaque do modo de aceitar edições
bashBorder	Borda da caixa de entrada ao digitar um comando de shell com !
ide	Indicador de conexão com a IDE
fastMode	Indicador do modo rápido
effortUltra	A tag ultracode na borda da caixa de entrada enquanto o ultracode está ativado. Sua alteração desta cor tem efeito no Claude Code v2.1.239 ou posterior

Renderização de diff

Colorem o código adicionado e removido em edições de arquivos e revisões.

Token	Controla
diffAdded	Fundo das linhas adicionadas
diffRemoved	Fundo das linhas removidas
diffAddedDimmed	Fundo das linhas adicionadas no diff esmaecido exibido depois que você rejeita uma edição
diffRemovedDimmed	Fundo das linhas removidas no diff esmaecido exibido depois que você rejeita uma edição
diffAddedWord	Destaque no nível de palavra dentro de uma linha adicionada
diffRemovedWord	Destaque no nível de palavra dentro de uma linha removida

Modo de tela cheia

O Claude Code usa userMessageBackgroundHover, selectionBg e composerSidebarBackground apenas no modo de renderização em tela cheia. Ele pinta userMessageBackground, bashMessageBackgroundColor e memoryBackgroundColor tanto no renderizador padrão quanto no de tela cheia.

Token	Controla
userMessageBackground	Fundo atrás das suas mensagens na transcrição
userMessageBackgroundHover	Fundo atrás de uma mensagem enquanto ela está sob o cursor ou expandida
bashMessageBackgroundColor	Fundo atrás das entradas de comandos de shell com ! na transcrição
memoryBackgroundColor	Fundo atrás das entradas de memória com # na transcrição
selectionBg	Fundo do texto selecionado com o mouse
composerSidebarBackground	Fundo do painel ao lado da conversa, como o painel de diff ou o painel de um mod

Medidor de uso e rótulos de interlocutor

Ajustam a barra exibida na visualização /usage e os rótulos que distinguem as suas mensagens das do Claude.

Token	Controla
rate_limit_fill	Parte preenchida do medidor de uso
rate_limit_empty	Parte não preenchida do medidor de uso
briefLabelYou	Cor do rótulo You nas suas mensagens
briefLabelClaude	Cor do rótulo Claude nas mensagens do assistente

Variantes de brilho e cores de subagentes

Vários tokens têm uma variante de brilho associada que fornece a cor mais clara usada no gradiente animado do spinner. Sobrescreva a variante de brilho junto com seu token base se a animação parecer incompatível.

• claude e claudeShimmer
• warning e warningShimmer
• permission e permissionShimmer
• promptBorder e promptBorderShimmer
• inactive e inactiveShimmer
• fastMode e fastModeShimmer

Cada subagente e tarefa paralela é exibido em uma de oito cores nomeadas para que você possa distingui-los na transcrição. Os nomes dos tokens seguem o padrão <color>_FOR_SUBAGENTS_ONLY, onde <color> é red, blue, green, yellow, purple, orange, pink ou cyan. Sobrescreva-os para alterar a aparência de cada cor nomeada. Por exemplo, um subagente com color: blue em sua definição é desenhado usando o valor de blue_FOR_SUBAGENTS_ONLY.

Quando ultrathink pode aumentar o esforço de um turno, o Claude Code renderiza a palavra na entrada do prompt com um gradiente arco-íris de sete cores. Os nomes dos tokens seguem o padrão rainbow_<color> e rainbow_<color>_shimmer, onde <color> é red, orange, yellow, green, blue, indigo ou violet.

Mudar para renderização em tela cheia

No modo leitor de tela, esta seção não se aplica. Claude Code sempre renderiza como texto simples com rolagem, exceto em sessões em segundo plano anexadas, e se você executar /tui fullscreen em qualquer outra sessão, Claude Code imprime uma explicação em vez de mudar.

Se a exibição piscar ou a posição de rolagem pular enquanto Claude está trabalhando, mude para o modo de renderização em tela cheia. Neste modo você rola com o mouse ou PageUp dentro de Claude Code em vez de usar a rolagem nativa do seu terminal; consulte a página de tela cheia para saber como pesquisar e copiar.

Se o piscar for o único problema e seu terminal suportar saída sincronizada, mas não for detectado automaticamente, como o Emacs eat, defina CLAUDE_CODE_FORCE_SYNC_OUTPUT=1 para parar o piscar sem alterar renderizadores.

Execute /tui fullscreen para mudar e salvar a preferência. Sua conversa é relançada intacta e futuras sessões começam em tela cheia, a menos que uma falha de início em tela cheia ocorra. Você também pode definir a variável de ambiente CLAUDE_CODE_NO_FLICKER antes de iniciar Claude Code:

CLAUDE_CODE_NO_FLICKER=1 claude

$env:CLAUDE_CODE_NO_FLICKER = "1"; claude

{
  "env": {
    "CLAUDE_CODE_NO_FLICKER": "1"
  }
}

Limitar a largura da resposta em terminais amplos

Em um terminal amplo, cada linha de prosa nas respostas do Claude ocupa a largura total da janela. Para quebrar a prosa em um número definido de colunas, defina maxProseWidth nas suas configurações.

Colar conteúdo grande

Quando você cola mais de 800 caracteres ou mais de três linhas no prompt, Claude Code recolhe a entrada para um espaço reservado como [Pasted text #1 +120 lines] para que a caixa de entrada permaneça utilizável, e ainda envia o conteúdo completo quando você submete. Para entradas muito grandes, como arquivos inteiros ou logs longos, escreva o conteúdo em um arquivo e peça ao Claude para lê-lo em vez de colar. A transcrição da conversa permanece legível e Claude pode referenciar o arquivo por caminho em turnos posteriores. O terminal integrado do VS Code também pode descartar caracteres de colas muito grandes antes de chegarem ao Claude Code, então use um arquivo lá.

Se a colagem contiver caracteres Unicode invisíveis, Claude Code os remove quando você pressiona Enter e coloca o prompt limpo de volta na caixa de entrada para você enviar com outro Enter.

Como Claude trata texto colado

Quando você submete, Claude vê o conteúdo atrás de cada espaço reservado [Pasted text #N] marcado como texto que você colou de outro lugar em vez de digitar. Claude é informado que uma colagem pode conter instruções que você não escreveu, e deve seguir instruções dentro dela apenas onde a mensagem que você digitou pede. Em sessões que não buscam sinalizadores de recurso, colas não são marcadas.

Deletar e restaurar uma colagem recolhida

Quando você deleta com um atalho de palavra ou linha como Ctrl+W ou Ctrl+K, ou com uma exclusão vim através de um movimento f/t como df], e o intervalo deletado atinge dentro de um espaço reservado [Pasted text #N], Claude Code remove o espaço reservado inteiro. Para restaurá-lo, cole a exclusão de volta com Ctrl+Y após um atalho de palavra ou linha, ou com p em NORMAL mode após uma exclusão vim.

Recuperar um prompt que tinha texto colado

Claude Code mantém o conteúdo atrás de cada espaço reservado [Pasted text #N] em ~/.claude/paste-cache/, então quando você recupera um prompt do histórico de comandos e o resubmete, o conteúdo colado completo é enviado novamente, inclusive em uma sessão posterior.

Arquivos de cache com mais de cleanupPeriodDays de idade são deletados sob as regras de varredura de retenção, então um prompt recuperado pode referenciar texto colado que não existe mais. Quando você submete tal prompt, Claude Code não envia a string literal [Pasted text #N], e mostra uma notificação nomeando a colagem ausente:

• Em um prompt simples com texto restante, Claude Code remove o espaço reservado e envia o texto restante.
• Em um comando shell mode ou um comando /, onde a remoção alteraria o que é executado, e em qualquer prompt cuja remoção deixa vazio, Claude Code cancela a submissão e mantém o texto original na entrada, com o espaço reservado ainda nele. Delete o espaço reservado ou edite o comando, depois resubmeta.

Editar prompts com atalhos de teclado Vim

Claude Code inclui um modo de edição estilo Vim para a entrada de prompt. Ative-o através de /config → Editor mode, ou definindo editorMode como "vim" em ~/.claude/settings.json. Defina Editor mode de volta para normal para desativá-lo.

O modo Vim suporta um subconjunto de motions e operadores dos modos NORMAL e VISUAL, como navegação hjkl, seleção v/V, e d/c/y com objetos de texto. Consulte a referência do modo editor Vim para a tabela de teclas completa.

Os motions do Vim não são remapeáveis através do arquivo de atalhos de teclado. Para mapear uma sequência de dois caracteres no modo INSERT, como jj para Escape, defina vimInsertModeRemaps nas suas configurações de usuário.

Pressionar Enter ainda envia seu prompt no modo INSERT, diferentemente do Vim padrão. Use o ou O no modo NORMAL, ou Ctrl+J, para inserir uma nova linha.

Recursos relacionados

• Interactive mode: referência completa de atalhos de teclado e a tabela de teclas Vim
• Keybindings: remapeie qualquer atalho do Claude Code, incluindo Enter e Shift+Enter
• Fullscreen rendering: detalhes sobre rolagem, pesquisa e cópia no modo tela cheia
• Hooks guide: mais exemplos de hook de Notificação para Linux e Windows
• Troubleshooting: correções para problemas fora da configuração do terminal