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

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 mais antiga numa lista. A partir de uma sessão que já esteja 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 abaixo corresponde à documentação oficial das sessões em agosto de 2026. O Claude Code lança versões com frequência, e os nomes dos parâmetros e os atalhos de teclado mudam entre versões. Por isso, considere claude --help e essa página como a referência principal quando algo não corresponder ao que o seu terminal apresenta.

O que é realmente uma sessão

Uma sessão é uma conversa guardada associada a um diretório de projeto. 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-a continuamente no disco enquanto trabalha, e não apenas no final, por isso a conversa sobrevive ao fecho do terminal ou à perda da ligação SSH.

Retomar restaura mais do que o texto. O histórico da conversa é recuperado na íntegra, juntamente com o modelo usado pela sessão e o subagente com que foi iniciada, se tiver usado --agent. O modo de permissões também é restaurado, com exceções por motivos de segurança: o modo de planeamento e o modo de ignorar permissões nunca são restaurados. Assim, uma sessão que estava num desses modos é retomada no modo em que uma sessão nova seria iniciada.

Alguns elementos não são recuperados porque eram flags passadas no 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 especificados novamente ao retomar. Ficheiros de definições como settings.json são lidos novamente no arranque, por isso não é necessário repetir nada do que esteja definido neles.

Por que 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 uma cloud. É um ficheiro no disco dessa máquina.

Por isso, uma sessão que deixou dentro de uma janela 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 as duas máquinas. Se trabalha como a maioria das pessoas quando executa o Claude Code no tmux numa VPS, o servidor é onde se acumula o seu histórico de conversas real, e o seletor que vê localmente mostra um conjunto diferente e muito menor.

A mesma separação aplica-se entre interfaces. A aplicação de ambiente de trabalho 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. O Claude Code na Web também mantém o seu próprio histórico.

Numa mesma máquina, a pesquisa é mais abrangente do que pode esperar. claude --resume <session-id> procura primeiro no diretório do projeto atual e nas respetivas árvores de trabalho do git e, em seguida, 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 nenhuma sessão, e o Claude Code informa-o com 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ífen. Assim, uma sessão iniciada em /home/deploy/apps/api fica 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: cada linha contém um objeto JSON, que pode ser uma mensagem, uma utilização de ferramenta ou uma entrada de metadados. É texto legível, e a sua leitura não apresenta problemas.

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

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

O que existe efetivamente nesses ficheiros de transcrição

O resultado de todas as ferramentas é registado. Isto significa que uma transcrição contém o conteúdo dos ficheiros que Claude leu e o resultado dos comandos que Claude executou. A página de utilização de dados da Anthropic afirma isso claramente: Claude Code armazena as transcrições das sessões localmente, em texto simples, em ~/.claude/projects/.

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 cadeia de ligação, essa cadeia também está lá. Nada foi divulgado. A transcrição registou o que aconteceu, que é precisamente a sua finalidade, e é por isso que deve fazer parte do seu modelo de ameaças.

• Backups: um backup simples de /home ou /root copia as suas transcrições para o local onde os backups são armazenados. 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 backups.
• Snapshots e imagens: um snapshot de VPS criado por qualquer motivo contém todo o diretório. O mesmo acontece com uma imagem que clone para criar um segundo servidor.
• Outras contas no servidor: verifique as permissões com ls -ld ~/.claude ~/.claude/projects em vez de presumir que estão restritas.
• Uploads deliberados: o comando /feedback envia propositadamente o histórico da conversa para a Anthropic, e /bug e /share comunicam através do mesmo caminho. Essas são ações que escolhe executar. Por isso, saiba o que está a aceitar antes de confirmar.

Se preferir que não existisse nenhuma transcrição, 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. Compreenda o compromisso antes de configurar qualquer uma das opções. As transcrições são utilizadas pela retoma. Sem transcrição, não existe retoma.

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, caso contrário, além do tempo desde a última atividade, do branch do 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 alargam 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 atual do git. 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.

Atribuir nomes às sessões facilita tudo isto. Inicie uma com claude -n auth-refactor ou execute /rename auth-refactor a meio, quando perceber que a conversa se transformou numa tarefa efetiva. 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 é criado por um pedido em segundo plano a um modelo pequeno e rápido, que resume o seu primeiro prompt. O título ajuda a reconhecer a linha no seletor, mas não serve para retomar a sessão. claude --resume <name> encontra apenas os nomes que definiu.

Procurar nos transcripts para encontrar a sessão correta

Por vezes, lembra-se de uma frase e de mais nada. Os transcripts são ficheiros de texto, por isso pode procurá-los.

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

Este comando apresenta os caminhos dos transcripts correspondentes. O nome do ficheiro sem a extensão .jsonl é o ID da sessão, e claude --resume <session-id> aceita esse ID. 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 cadeia literal. Além disso, uma correspondência dentro do resultado de uma ferramenta significa que o Claude viu esse texto, não que alguém o tenha introduzido.

Ler e exportar 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 que permite escolher entre a área de transferência e um ficheiro. Com um nome de ficheiro, /export handover.txt escreve 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 serem estáveis. Os hooks e os comandos da linha de estado recebem um campo transcript_path como entrada, pelo que 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 de novo é melhor do que retomar

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

O Claude Code por vezes oferece uma opção intermédia. Num plano Pro ou Max, retomar uma sessão que está inativa há cerca de uma hora e contém mais de 100,000 tokens abre uma caixa de diálogo antes da primeira mensagem. Até lá, a cache de prompts expirou, por isso o pedido seguinte volta a processar todo o histórico uma vez, independentemente da opção escolhida.

• Retomar a partir do resumo executa uma compactação imediatamente, por isso os pedidos seguintes transportam um resumo em vez do histórico completo. O custo por pedido é menor, mas tudo o que o resumo omitir deixa de estar disponível.
• Retomar a sessão completa tal como está carrega a conversa sem alterações, mantendo todos os detalhes, com um custo por pedido que aumenta com o tamanho da conversa.

Uma terceira opção retoma a sessão completa e impede que a caixa de diálogo apareça em retomas posteriores.

A decisão é mais simples do que parece. Retome quando aquilo que está prestes a escrever depende do que já foi dito. Comece de novo quando não depende. É fácil detetar o desvio quando se procura por ele: o Claude faz referência a um ficheiro que eliminou há uma hora ou volta a discutir uma decisão tomada no início da sessão. Esse é contexto obsoleto, e transportá-lo para a frente custa tokens e precisão ao mesmo tempo.

Se a parte útil de uma conversa antiga for uma decisão ou um facto de que vai precisar novamente, não dependa da retoma para o transportar. Registe-o num local visível para todas as sessões, que é precisamente 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 para a cópia, mantendo a original intacta e disponível no seletor. Use-a para experimentar uma segunda abordagem sem perder a primeira.

Como retomar uma sessão é diferente de compactação e de memória

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

Retomar uma sessão 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 que o Claude está a manter por um resumo, para que os pedidos seguintes enviem menos tokens. Se o problema é uma janela de contexto cheia, a compactação é a ferramenta adequada, e gerir a janela de contexto do Claude Code explica isso 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, por isso não representam uma conversa à qual regressa. São informações que regista para nunca precisar de regressar a uma conversa.

Se pretende ter duas conversas a decorrer ao mesmo tempo e a coordenar-se, isso usa um mecanismo separado. as sessões do Claude Code podem trocar mensagens entre si enquanto ambas estão ativas. Esse é um problema diferente de recuperar do disco a sessão de ontem.

FAQ

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

Por predefiniçã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: um objeto JSON por linha para uma mensagem, uma utilização de ferramenta ou 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, com o valor predefinido de 30 dias e 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 não são sincronizadas entre máquinas. Uma conversa que teve dentro de tmux no seu VPS existe apenas no VPS. Retome-a aí através de SSH ou execute /export dentro da sessão e copie o ficheiro de texto para o seu computador se quiser manter um registo local.

Posso retomar uma sessão que iniciei noutro diretório?

Sim, se tiver o respetivo ID de sessão. claude --resume <session-id> procura primeiro no diretório do projeto atual e nas respetivas árvores de trabalho git e, depois, em todos os outros projetos da mesma máquina. No seletor, Ctrl+A alarga a lista a todos os projetos da máquina e Ctrl+W alarga-a a todas as árvores de trabalho do repositório atual. Se não encontrar correspondências, o Claude Code comunica 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 todos os pedidos seguintes passam a transportá-lo. Esteja atento ao desvio de contexto: uma sessão que continua a referir-se a ficheiros que já eliminou 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 a consequência, porque é das transcrições que a retoma depende; se as desativar, --continue e --resume não terão 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 cifrado e reduza cleanupPeriodDays em vez disso.