Comando travado no Claude Code: como interromper sem perder a sessão?

O cursor parado, nenhuma linha nova na tela, e aquela dúvida chata batendo: eu mato o terminal e perco tudo, ou espero mais cinco minutos?

Fala aí, beleza? Essa cena é clássica, e a reação instintiva (fechar tudo no grito) costuma ser a pior possível

Porque comando travado no Claude Code não é a mesma coisa que modelo pensando

Quando o modelo está trabalhando, ele está gerando resposta e a coisa anda, mesmo que devagar

Quando o comando trava, quem está pendurado é o processo que a ferramenta Bash abriu, e o Claude fica ali esperando um retorno que não vem

São problemas diferentes, com saídas diferentes, e nenhuma delas exige encerrar a conversa 🙂

Como saber se quem travou foi o comando e não o modelo

Sintoma: nada aparece na tela por um tempo longo demais e você não consegue dizer se o Claude está raciocinando ou se o processo ficou pendurado

Causa: a chamada da ferramenta Bash segue aberta, esperando um processo que não termina ou uma entrada que nunca chega

Solução: olhe o que foi executado antes do silêncio

Se foi um servidor, um watcher ou qualquer coisa feita pra ficar viva, o comando não vai retornar sozinho, nunca

Se foi um comando que abre sessão interativa, pior ainda: a ferramenta Bash do Claude Code não tem suporte a pseudo-terminal (PTY), então esse tipo de execução simplesmente empaca

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

E tem um marcador de tempo que ajuda: o BASH_DEFAULT_TIMEOUT_MS tem valor padrão de 120000 milissegundos, ou seja, 2 minutos

Então silêncio muito acima disso, sem retorno e sem erro, é sinal forte de comando preso e não de modelo raciocinando

Como prevenir: repare no TIPO de comando antes de aprovar a execução

Servidor, watcher e prompt interativo pedem tratamento diferente, e dá pra decidir isso antes de apertar o botão

E se o travamento começou logo depois de você instalar alguma coisa nova no ambiente, a investigação é outra: vale seguir o diagnóstico de ferramenta não reconhecida antes de culpar a Bash

O comando não termina sozinho (servidor, watcher, build em loop)

Sintoma: você pede um npm run dev, um watcher ou qualquer processo de longa duração, e a sessão fica refém

O terminal segue vivo, cuspindo log, e o Claude não volta pra você

Causa: esses processos são feitos pra não terminar

Não tem bug aqui, tem incompatibilidade de expectativa: a ferramenta espera um comando que acaba, e você entregou um que foi projetado pra ficar de pé

Solução: manda pro segundo plano

O Ctrl+B move uma execução da ferramenta Bash para segundo plano

Se tu usa tmux, aperta duas vezes, porque a primeira é consumida pela tecla prefixo do próprio tmux (fica a dica pra não achar que o atalho está quebrado)

O mesmo Ctrl+B vale no modo bash com prefixo !, quando é você quem está rodando o comando longo na mão

A partir daí:

1. cada tarefa em segundo plano ganha um ID único pra rastreio
2. a saída vai pra um arquivo em vez de inundar a conversa
3. o Claude recupera esse conteúdo com a ferramenta Read, quando precisar olhar
4. o /bashes, que é alias de /tasks, lista e gerencia o que está rodando

O erro comum aqui é esquecer que o /bashes existe e ficar tentando adivinhar o estado da tarefa pelo silêncio da tela

Se você ainda embaralha o que é slash command, o que é subagente e o que é skill, dá uma olhada na diferença entre skills, comandos e subagentes antes de seguir

Como prevenir: processo de longa duração já nasce em segundo plano

Não espere travar pra depois reagir

O comando está esperando você digitar algo (vim, git rebase -i, npm init, REPL)

Sintoma: a execução fica parada e nada é pedido na tela

Ou pior: o comando termina em silêncio, sem erro nenhum, e o valor que deveria ser aplicado simplesmente não foi aplicado

Causa: a ferramenta Bash não oferece suporte a shell interativo via PTY

Tem um pedido de funcionalidade aberto no repositório oficial do Claude Code descrevendo exatamente isso: comandos que abrem sessão interativa (como vim, git rebase -i, npm init ou um REPL) fazem a sessão travar, esperar o timeout ou falhar

E tem uma issue separada sobre prompts interativos de stdin, onde o relato é o do desaparecimento silencioso: o prompt nunca aparece e o comando encerra sem aplicar nada

Ou seja, não é você que está fazendo errado, e não adianta esperar mais um pouquinho

Solução: aperta Esc

Esse é o primeiro degrau em qualquer travamento, seja qual for a causa: o Esc cancela a chamada de ferramenta em execução e te mantém na MESMA sessão, esperando a próxima instrução

Depois disso, você reformula o pedido em forma não interativa (a próxima seção é só sobre isso)

Em execução não interativa, ainda dá pra blindar o stdin:

claude -p "prompt" < /dev/null

Redirecionando de /dev/null, o Claude não fica esperando uma entrada que ninguém vai digitar

Como prevenir: evita pedir comando que abre sessão interativa

Se o comando normalmente abriria um editor ou um menu no teu terminal, ele vai travar ali dentro

Como pedir a mesma tarefa de um jeito que não trava

A maior parte dos travamentos não é problema de ferramenta, é problema de formulação do pedido

A tarefa é legítima, o caminho é que era interativo

Se liga nos padrões de reformulação:

Repara que nenhuma dessas saídas exige flag mágica nem prompt secreto

É só trocar "abre isso pra mim" por "faz isso e me devolve o resultado"

E quando o processo PRECISA ficar vivo, ele fica vivo, só que fora do caminho da conversa

Ajustar o timeout quando o comando é legitimamente longo

Sintoma: o comando não travou coisa nenhuma, ele só demora mais que o padrão

Build pesado, suite de testes grande, aquela tarefa que na tua máquina leva um tempão

Causa: o BASH_DEFAULT_TIMEOUT_MS é o timeout padrão para comandos Bash longos, e o valor padrão dele é 120000 ms (2 minutos)

Já o BASH_MAX_TIMEOUT_MS define o teto de timeout que o modelo pode solicitar

Solução: essas variáveis podem ser configuradas sob a chave env no settings.json

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "120000",
    "BASH_MAX_TIMEOUT_MS": "<valor em ms>"
  }
}

O 120000 aí em cima é o valor padrão do BASH_DEFAULT_TIMEOUT_MS, servindo só de referência: troca pelo número de milissegundos que faz sentido pro teu comando

No BASH_MAX_TIMEOUT_MS tu coloca, também em milissegundos, o teto que o modelo pode solicitar

Tome cuidado com um detalhe que pega muita gente: as variáveis de ambiente são lidas na inicialização

Mudou o arquivo? A mudança vale na PRÓXIMA vez que você abrir o Claude Code, não na sessão que já está rodando

O erro comum deste passo é editar o settings.json, testar na mesma sessão, ver que nada mudou e achar que a configuração não funciona

E tem uma variável que merece um aviso grande: CLAUDE_CODE_DISABLE_BACKGROUND_TASKS definida como 1 desativa toda a funcionalidade de tarefas em segundo plano

Se você colocou isso aí em algum momento e agora o Ctrl+B não te ajuda mais, já sabe onde olhar 😀

Ctrl+C como último recurso: como voltar sem perder a conversa

Sintoma: o Esc e o segundo plano não resolveram (ou o pânico falou mais alto), você apertou Ctrl+C duas vezes e o Claude Code fechou no meio da tarefa

Causa: o comportamento é esse mesmo

O primeiro Ctrl+C limpa a entrada e a fila de prompts

O segundo encerra o Claude Code

Por isso ele fica no fim da fila: é o único dos três que tira você da sessão

Solução: respira, porque a conversa não evaporou

Uma sessão é uma conversa salva atrelada a um diretório de projeto, armazenada localmente enquanto você trabalha

Pra voltar:

1. dentro do Claude Code, roda /resume (que tem /continue como alias) pra retomar por ID, por nome, ou pra abrir o seletor de sessões
2. pelo terminal, a flag claude --continue (ou -c) é outra coisa: ela carrega direto a conversa mais recente do diretório atual, sem seletor
3. se você tem o ID em mãos, claude --resume <session-id> vai direto na sessão certa

claude --continue

Retomando por qualquer um desses caminhos, a sessão reabre com o MESMO session ID e as novas mensagens são anexadas à conversa existente

O erro comum deste passo é rodar o claude de outra pasta e achar que perdeu tudo: a flag --continue pega a conversa mais recente do diretório atual, então a pasta importa

E se o problema não foi a saída, mas o que o Claude fez antes de travar?

Aí o caminho é o /rewind, que também abre apertando Esc duas vezes com o campo de prompt VAZIO

Detalhe que confunde: se tiver texto no campo, o Esc duplo só limpa o texto em vez de abrir o menu de rewind

Como prevenir: Esc antes de pensar em Ctrl+C

O Esc cancela a chamada de ferramenta e te deixa na sessão, que é exatamente o que você queria quando entrou em pânico

Na prática: rodando tarefas longas em paralelo sem travar a sessão

Quando gravei o vídeo sobre o /goal, o comando do Claude Code que trabalha sozinho até terminar, essa lógica de "não travou, só está rodando" ficou bem clara na tela

Eu deixei duas rotinas autônomas rodando em paralelo na máquina e fiquei só acompanhando o andamento enquanto seguia com o projeto

Com a tarefa em andamento no terminal, apertei ESC e voltei pra sessão de prompt sem encerrar o que estava rolando: o trabalho seguiu, e eu voltei a conversar

A interface ainda mostrava o indicador de status avisando que tinha rotina ativa, e eu conseguia listar o que estava em execução

Uma coisa que descobri testando: nenhuma parada é instantânea

Quando pedi a pausa, o agente terminou o passo que estava executando antes de pausar

Ele inclusive respondeu na tela que tinha recebido a instrução e que ia interromper a análise depois de concluir o trecho em andamento

Eu li isso como proteção, não como lentidão: melhor terminar o passo do que deixar coisa pela metade

Depois retomei a execução e a tarefa continuou do ponto em que tinha parado

No cancelamento o comportamento foi o mesmo: o agente ainda finaliza a interação atual antes de sair, então demora um pouco pra encerrar de fato

E quando o objetivo já tinha sido atingido, marquei a rotina como concluída na mão, pra ele não ficar repetindo execução à toa

Ah, e precisei atualizar o Claude Code antes de conseguir usar o recurso, porque a versão que eu tinha era anterior à necessária

Se der erro de comando não encontrado, olha a versão antes de xingar a ferramenta 😛

O que eu recomendo pra esse tipo de execução longa: prompt com estado final MENSURÁVEL, uma forma do agente comprovar que chegou lá, e restrições opcionais do que ele não pode fazer

Serve bem pra tarefa longa, com objetivo claro, que não exige supervisão constante (teste repetitivo é o exemplo mais óbvio)

E vale ler a documentação oficial pra ver parâmetros, usos recomendados e limitações, que foi de lá que tirei a base

Os limites do segundo plano que você precisa conhecer:

Segundo plano não é terra sem lei, e conhecer os limites evita susto:

• uma tarefa em segundo plano é encerrada automaticamente se a saída ultrapassar 5GB, com uma nota no stderr explicando o motivo
• no macOS e no Linux, o Claude Code encerra tarefas em segundo plano quando o sistema operacional sinaliza pressão de memória, desde que a sessão esteja ociosa há pelo menos 30 minutos e nenhum turno ou subagente esteja rodando
• as tarefas em segundo plano são limpas automaticamente quando o Claude Code é encerrado

Esse último ponto é o que mais gera confusão: sair do Claude Code não deixa as tarefas penduradas em algum limbo, elas vão junto

Conclusão

A escada de reação pra comando travado no Claude Code é curta e vale decorar, sempre nessa ordem:

1. Esc primeiro, em qualquer travamento, porque ele cancela a chamada de ferramenta em execução e te mantém na mesma sessão
2. Ctrl+B na sequência, quando o processo é longo por natureza (servidor, watcher, build), mandando pro segundo plano com ID próprio e saída em arquivo
3. Ctrl+C só por último, sabendo que o primeiro limpa o input e o segundo encerra o Claude Code

E se encerrou mesmo, /resume dentro do Claude Code ou a flag claude --continue no terminal trazem a conversa de volta com o mesmo session ID

Antes de precisar de tudo isso, faz duas coisas: revisa a chave env do teu settings.json (timeout e a variável que desliga o segundo plano) e testa o /bashes na próxima tarefa longa que você rodar

É muito mais tranquilo aprender o atalho com a sessão calma do que descobrindo no susto, né? 😀

até o próximo post!