SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Como retomar sessões e achar o histórico do Claude Code

Use os comandos de retomada do Claude Code por nome ou seletor e encontre os históricos em texto simples gravados no diretório da máquina.

Como retomar uma sessão do Claude Code

Para retomar uma sessão do Claude Code, execute claude --continue para abrir a conversa mais recente no diretório atual ou claude --resume para escolher uma sessão anterior numa lista. A partir de uma sessão já em execução, o comando /resume muda para outra conversa sem sair. As formas abreviadas são -c e -r.

claude --continue
claude --resume
claude --resume auth-refactor

Se já souber o nome ou o ID da sessão, passe-o como argumento. O Claude Code abre diretamente essa sessão sem mostrar o seletor.

Tudo o que se segue corresponde à documentação oficial de sessões em novembro de 2026. O Claude Code recebe lançamentos frequentes, e os nomes das flags e os atalhos de teclado podem mudar entre versões. Por isso, considere claude --help e essa página como a referência principal quando o que está aqui não corresponder ao que o terminal apresenta.

O que uma sessão realmente é

Uma sessão é uma conversa guardada associada a um diretório de projeto. Ela contém todo o histórico de mensagens, incluindo as chamadas de ferramentas feitas pelo Claude e os resultados devolvidos por essas chamadas. O Claude Code grava esses dados continuamente no disco enquanto trabalha, e não apenas no fim. Assim, a conversa sobrevive ao fecho do terminal ou à perda da ligação SSH.

Retomar restaura mais do que o texto. Todo o histórico da conversa volta, juntamente com o modelo usado pela sessão e o subagente com que ela foi iniciada, se utilizou --agent. O modo de permissões também volta quando retoma a partir da shell com --continue ou com um ID de sessão, com uma exceção por motivos de segurança: o modo bypass-permissions nunca é restaurado. Assim, uma sessão que terminou nesse modo é retomada no modo em que uma sessão nova seria iniciada. O plan mode é restaurado, inclusive quando escolhe a sessão no seletor ou muda para ela com /resume. Essas duas formas, de outro modo, não transportariam um modo guardado. As retomas a partir do terminal restauram-no desde a v2.1.290, e o seletor e /resume fazem-no desde a v2.1.292. Nas versões anteriores, o plan mode também era perdido ao retomar. A partir da shell, --permission-mode substitui o modo restaurado.

Alguns elementos não são restaurados porque eram flags de arranque, e não estado guardado. Os diretórios adicionados com --add-dir e opções como --mcp-config, --settings e --plugin-dir têm de ser indicados novamente ao retomar. Ficheiros de definições como settings.json são lidos novamente no arranque, pelo que não é necessário repetir nada do que esteja neles. As credenciais seguem a mesma lógica: o Claude Code determina como autenticar no arranque, com base no seu início de sessão e no ambiente, em vez de as restaurar com a conversa. Por isso, uma sessão retomada num VPS onde um ANTHROPIC_API_KEY inesperado tenha entrado na shell encontra o erro de chave de API inválida, mesmo que tenha funcionado na última vez.

Porque o histórico de sessões é mais importante numa VPS

Este é o facto que surpreende muitas pessoas. A transcrição é gravada na máquina onde o agente foi executado. Não fica guardada na sua conta nem é sincronizada com a cloud. É um ficheiro no disco desse sistema.

Por isso, uma sessão que deixou numa janela do tmux na sua VPS não aparece no seletor do seu portátil, e uma sessão do seu portátil não aparece na VPS. Nada é transferido entre os dois sistemas. Se trabalha como a maioria das pessoas ao executar o Claude Code no tmux numa VPS, o servidor é onde se acumula o seu histórico real de conversas, e o seletor que vê localmente apresenta um conjunto diferente e muito menor.

A mesma separação aplica-se entre interfaces. A aplicação de desktop e a extensão do VS Code mantêm cada uma o seu próprio histórico de sessões, e nenhum dos dois corresponde ao histórico da CLI, embora a aplicação de desktop também possa retomar uma sessão da CLI. O Claude Code na Web também mantém o seu próprio histórico. O Cowork está ainda mais separado: por predefinição, as sessões são executadas na cloud da Anthropic e guardadas na sua conta Claude, e não em hardware que lhe pertença. A execução local fica disponível apenas para implementações de desktop existentes. Por isso, se está a comparar o Cowork com o Claude Code, o local onde a transcrição fica guardada faz parte da decisão.

Numa mesma máquina, a pesquisa é mais abrangente do que pode esperar. claude --resume <session-id> procura primeiro no diretório atual do projeto e nas respetivas worktrees do git, e depois em todos os outros projetos dessa máquina. A expressão importante é "nessa máquina". Um ID de sessão de outro host não resolve para nada, e o Claude Code informa-o disso através de No conversation found with session ID: <session-id>.

Onde o Claude Code armazena o histórico das sessões

Por padrão, as transcrições ficam no diretório de configuração do Claude Code, num caminho do formato ~/.claude/projects/<project>/<session-id>.jsonl.

<project> é o caminho do diretório de trabalho, com todos os caracteres não alfanuméricos substituídos por hífens. Assim, uma sessão iniciada em /home/deploy/apps/api é armazenada num diretório chamado -home-deploy-apps-api. Se o nome convertido ultrapassar 200 caracteres, o Claude Code trunca-o e acrescenta um hash do caminho completo. Dessa forma, o nome do diretório permanece dentro dos limites do sistema de ficheiros.

O ficheiro está no formato JSONL: um objeto JSON por linha. Cada linha contém uma mensagem, uma utilização de ferramenta ou o respetivo resultado, um registo de um pedido enviado pelo Claude Code ao modelo ou uma entrada de metadados. É texto legível, e não há problema em lê-lo.

Não é recomendável criar um analisador para esse ficheiro. O formato das entradas é interno do Claude Code e muda entre versões. Por isso, um script que leia estes ficheiros diretamente pode deixar de funcionar após qualquer atualização. A documentação da Anthropic recomenda usar /export ou as interfaces de script documentadas. É uma recomendação adequada precisamente por esse motivo.

Duas definições alteram este comportamento. CLAUDE_CONFIG_DIR transfere todo o diretório de configuração. É assim que pode colocar as transcrições num volume separado ou num volume encriptado. cleanupPeriodDays em settings.json controla durante quanto tempo elas são mantidas. O valor predefinido é 30 dias, com um mínimo de 1.

O que existe realmente nesses ficheiros de transcrição

Todos os resultados das ferramentas são registados. Isto significa que uma transcrição contém o conteúdo dos ficheiros que Claude leu e a saída dos comandos que Claude executou. A página de utilização de dados da Anthropic afirma-o claramente: Claude Code armazena localmente as transcrições das sessões, em texto simples, em ~/.claude/projects/. Como a transcrição também regista o que Claude Code envia ao modelo, pode conter o prompt do sistema, as definições das ferramentas, os parâmetros dos pedidos e os ficheiros CLAUDE.md carregados.

Considere o que isto significa num servidor. Se Claude leu um ficheiro .env para determinar por que razão um serviço não iniciava, o conteúdo desse ficheiro está agora num ficheiro JSONL no seu diretório pessoal. Se um comando apresentou uma string de ligação, essa string também está lá. Nada foi divulgado. A transcrição registou o que aconteceu, que é precisamente o seu objetivo. É também por isso que deve fazer parte do seu modelo de ameaças.

  • Cópias de segurança: uma cópia simples de /home ou /root copia as suas transcrições para o destino das cópias de segurança. Adicione uma exclusão ou aceite que cópias dos seus prompts e do conteúdo dos seus ficheiros passam a existir no armazenamento de cópias de segurança.
  • Snapshots e imagens: um snapshot de um VPS criado por qualquer motivo contém o diretório completo. O mesmo acontece com uma imagem que clone para criar outro servidor.
  • Outras contas no sistema: verifique as permissões com ls -ld ~/.claude ~/.claude/projects em vez de assumir que são restritas.
  • Carregamentos deliberados: o comando /feedback envia deliberadamente o histórico da conversa para a Anthropic, e /bug e /share comunicam através do mesmo caminho. A caixa de diálogo de feedback também pode incluir outras sessões do mesmo projeto das últimas 24 horas ou 7 dias, e não apenas a sessão atual. Essas ações dependem de si. Saiba o que está a aceitar antes de confirmar.

Se preferir que não exista qualquer transcrição, CLAUDE_CODE_SKIP_PROMPT_HISTORY impede a escrita de transcrições, e --no-session-persistence impede-a numa única execução não interativa de claude -p. Compreenda claramente a consequência antes de configurar qualquer uma das opções. O resume lê as transcrições. Por isso, sem transcrição não existe resume.

Como encontrar uma conversa antiga

Abra o seletor com claude --resume ou com /resume a partir de uma sessão em execução. Cada linha mostra o nome da sessão, se tiver definido um, ou um título gerado, se não tiver definido nenhum, além do tempo desde a última atividade, do branch git e do tamanho do ficheiro.

O seletor permite fazer pesquisas. Prima / ou comece simplesmente a escrever para filtrar a lista. Os atalhos mais úteis são os que ampliam a pesquisa: Ctrl+A mostra as sessões de todos os projetos nesta máquina, Ctrl+W mostra todas as worktrees do repositório atual e Ctrl+B filtra pela branch git atual. Prima Space para pré-visualizar o conteúdo de uma sessão antes de a selecionar e Ctrl+R para mudar o nome da sessão destacada.

Dar nomes às sessões facilita bastante este processo. Inicie uma sessão com claude -n auth-refactor ou execute /rename auth-refactor a meio da sessão, quando perceber que a conversa se transformou num trabalho concreto. Depois, pode retomar uma sessão com nome diretamente a partir da shell.

Uma sessão sem nome também recebe um título gerado. Esse título é escrito por um pedido em segundo plano para um modelo pequeno e rápido, que resume o seu primeiro prompt. O título ajuda a reconhecer a linha no seletor e também funciona como identificador para retomar a sessão: claude --resume resolve-o da mesma forma que um nome definido pelo utilizador. O que não funciona é o nome de apresentação predefinido, como my-app-3f, que uma sessão interativa sem nome apresenta nas listagens de sessões em execução. Se passar esse nome a claude --resume, o Claude Code não encontra a sessão.

Pesquisar transcrições para encontrar a sessão correta

Às vezes, lembra-se de uma frase e de mais nada. As transcrições são ficheiros de texto, por isso pode pesquisá-las.

grep -rl "nftables" ~/.claude/projects/

Isto apresenta os caminhos das transcrições correspondentes. O nome do ficheiro sem a extensão .jsonl é o ID da sessão, que claude --resume <session-id> aceita. claude --resume também aceita diretamente o caminho absoluto da transcrição. Use grep para determinar qual sessão pretende e, em seguida, retome-a ou exporte-a para ler o conteúdo.

Há duas ressalvas importantes. O conteúdo está escapado em JSON, por isso uma frase que contenha aspas ou que tenha sido dividida por uma quebra de linha pode não corresponder a uma string literal. Além disso, uma correspondência dentro do resultado de uma ferramenta significa que Claude viu esse texto, não que alguém o escreveu.

Leitura e exportação de uma conversa

/export apresenta a conversa atual como texto simples, com as mensagens e a saída das ferramentas formatadas de forma legível, em vez de JSON. Sem argumentos, abre um menu com opções para usar a área de transferência ou um ficheiro. Com um nome de ficheiro, /export handover.txt grava diretamente nesse caminho. Esta é a forma correta de transferir uma conversa de um servidor para o seu portátil ou de a anexar a um ticket.

Para qualquer processo automatizado, use as interfaces concebidas para permanecer estáveis. Os hooks e os comandos da linha de estado recebem um campo transcript_path como entrada. Assim, um hook SessionEnd pode arquivar uma transcrição quando uma sessão termina. Também pode fazer uma pergunta a uma sessão guardada sem a abrir:

claude -p --resume <session-id> --output-format json "summarize what we changed" | jq -r '.result'

Isto envia um prompt de seguimento para a conversa antiga e devolve JSON estruturado. É uma base muito melhor do que analisar um formato JSONL que pode ser alterado na próxima release.

Quando começar do zero é melhor do que retomar

Retomar restaura todo o histórico, e é esse histórico completo que cada pedido posterior envia. Uma conversa que durou quatro horas ontem é dispendiosa para continuar hoje, e como o uso de tokens se acumula numa sessão longa explica de onde vem esse custo.

Por vezes, o Claude Code faz uma compactação intermédia por si. Se deixar uma conversa longa inativa numa sessão de terminal interativa e ela estiver na cache de prompts de uma hora, que uma subscrição Claude fornece por predefinição à conversa principal dentro do uso do seu plano, a compactação por inatividade compacta-a após cerca de 54 minutos, pouco antes de a cache expirar. Isto acontece quando o contexto da conversa atinge um limite de tokens, 200,000 por predefinição, enquanto a compactação automática estiver ativa e a máquina estiver ligada nesse momento. Antes da v2.1.314, o Claude Code também precisava de obter feature flags da Anthropic, pelo que os subscritores com a telemetria desativada nunca recebiam esta funcionalidade; desde a v2.1.314, ela também funciona para esses utilizadores, bem como no painel de chat da extensão VS Code e no separador Code da aplicação de ambiente de trabalho. Não é apresentada nenhuma caixa de diálogo previamente. Quando regressar, a conversa mostrará uma linha que começa por Compacted while idle, before the prompt cache expired, e a mensagem seguinte enviará um resumo em vez de todo o histórico.

  • Deixe-a ativa para que os pedidos posteriores sejam mais baratos, mas tudo o que for omitido pelo resumo deixa de estar disponível. Pode reduzir o limite com CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS, embora os valores inferiores a 100,000 sejam aumentados para 100,000.
  • Desative-a definindo idleCompaction como false em settings.json, ou a partir da linha Idle compaction em /config na v2.1.302 ou posterior. Nesse caso, a conversa permanece completa, com um custo por pedido que aumenta de acordo com o seu tamanho. Se a cache tiver expirado quando enviar a mensagem seguinte, esse pedido processará novamente todo o histórico uma vez.

Nos planos Pro e Max, a v2.1.304 adicionou uma verificação adicional, e a documentação atual também inclui os planos Ultra. Ao retomar uma conversa longa depois de uma pausa prolongada, ou ao utilizar um modelo diferente, se isso consumir uma parte significativa do limite de uso de 5 horas, uma caixa de diálogo Resume this conversation? mostra essa percentagem estimada e permite retomar mesmo assim ou iniciar uma conversa nova. Quando a opção de conversa nova o indicar, o Claude poderá consultar a conversa anterior se fizer referência a ela.

A decisão é mais simples do que parece. Retome quando aquilo que vai escrever depender do que já foi dito. Comece do zero quando não depender. É fácil detetar a deriva quando se sabe o que procurar: o Claude faz referência a um ficheiro que eliminou há uma hora ou volta a discutir uma decisão que tinha sido tomada no início da sessão. Esse é contexto obsoleto, e mantê-lo aumenta simultaneamente o consumo de tokens e os erros.

Se a parte útil de uma conversa antiga for uma decisão ou um facto de que voltará a precisar, não dependa da retoma para o preservar. Registe-o num local visível para todas as sessões, que é a finalidade dos ficheiros de memória do Claude Code.

/branch também é útil neste caso. Copia a conversa até ao ponto atual e muda-o para a cópia, mantendo o original intacto e disponível no seletor. Utilize-o para experimentar uma segunda abordagem sem perder a primeira.

Como o resume difere da compactação e da memória

Estes conceitos são frequentemente confundidos, mas resolvem problemas diferentes.

O resume serve para recuperar uma conversa depois de sair, reiniciar o sistema ou passar para outra tarefa. A compactação diz respeito à janela de contexto dentro de uma conversa ativa: /compact substitui o conteúdo que o Claude mantém por um resumo, para que os pedidos seguintes enviem menos tokens. Se o problema for uma janela de contexto cheia, a compactação é a ferramenta adequada, e gerir a janela de contexto do Claude Code explica o processo corretamente.

A memória é diferente. Os ficheiros CLAUDE.md e a memória automática contêm instruções e factos carregados no início de cada sessão. Não são uma conversa à qual regressa. São aquilo que regista para nunca precisar de regressar a uma conversa específica.

Se pretende ter duas conversas em execução ao mesmo tempo e coordená-las, existe um mecanismo separado. as sessões do Claude Code podem enviar mensagens entre si enquanto ambas estão ativas. Esse é um problema diferente de recuperar do disco a sessão do dia anterior.

FAQ

Onde o Claude Code armazena o histórico das minhas sessões?

Por padrão, no diretório de configuração, em ~/.claude/projects/<project>/<session-id>.jsonl, onde <project> é o caminho do diretório de trabalho, com os caracteres não alfanuméricos substituídos por hífenes. Cada ficheiro está em JSONL: uma linha contém um objeto JSON relativo a uma mensagem, à utilização de uma ferramenta ou ao respetivo resultado, ao registo de um pedido enviado ao modelo ou a uma entrada de metadados. CLAUDE_CONFIG_DIR move o diretório de configuração para outro local, e cleanupPeriodDays em settings.json define durante quanto tempo as transcrições são mantidas. O valor predefinido é 30 dias, com um mínimo de 1.

Porque não consigo ver a sessão do meu VPS no seletor do meu portátil?

Porque as transcrições são gravadas no disco da máquina onde o agente foi executado, e nada as sincroniza entre máquinas. Uma conversa que teve dentro do tmux no seu VPS existe apenas no VPS. Retome-a aí através de SSH ou execute /export dentro dela e copie o ficheiro de texto para obter um registo local.

Posso retomar uma sessão iniciada noutro diretório?

Sim, se tiver o respetivo ID da sessão. claude --resume <session-id> procura primeiro no diretório do projeto atual e nas respetivas worktrees do git e, depois, em todos os outros projetos da mesma máquina. Dentro do seletor, Ctrl+A alarga a lista a todos os projetos da máquina e Ctrl+W alarga-a a todas as worktrees do repositório atual. Se não encontrar correspondências, o Claude Code apresenta No conversation found with session ID: <session-id>.

Devo retomar uma sessão antiga ou iniciar uma nova?

Retome-a quando a próxima mensagem depender do que já foi dito nessa conversa. Inicie uma nova quando isso não acontecer, porque retomar uma sessão recarrega todo o histórico e cada pedido seguinte passa a incluí-lo. Esteja atento à deriva de contexto: uma sessão que continua a referir-se a ficheiros que já apagou está a transportar contexto obsoleto, o que consome tokens e reduz a precisão em cada interação.

Posso impedir o Claude Code de gravar transcrições no disco?

Sim. CLAUDE_CODE_SKIP_PROMPT_HISTORY impede a gravação de transcrições, e --no-session-persistence impede-a numa única execução não interativa de claude -p. Tenha primeiro em conta esta limitação: o comando de retoma lê as transcrições, pelo que desativar a gravação significa que --continue e --resume não têm nada para carregar. Se a sua preocupação for o local onde os ficheiros ficam, e não a sua existência, aponte CLAUDE_CONFIG_DIR para um volume encriptado e reduza cleanupPeriodDays.

Este artigo foi útil?