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 anterior numa lista. Dentro de uma sessão que já está 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 agosto de 2026. O Claude Code lança versões com frequência, e os nomes das opções e os atalhos de teclado podem mudar entre versões. Por isso, quando o conteúdo abaixo não corresponder ao que o terminal mostra, considere claude --help e essa página como a referência.

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 esse conteúdo continuamente no disco enquanto trabalha, e não apenas no final. 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 é recuperado, juntamente com o modelo que a sessão estava a utilizar e o subagente com que foi iniciada, se tiver usado --agent. O modo de permissões também é recuperado, com exceções por motivos de segurança: o modo de plano e o modo de bypass de permissões nunca são restaurados. Por isso, uma sessão que estava num desses modos é retomada no modo em que uma nova sessão seria iniciada.

Alguns itens não são restaurados porque eram opções passadas no arranque, e não estado guardado. Os diretórios adicionados com --add-dir e as opções como --mcp-config, --settings e --plugin-dir têm de ser passados novamente quando retomar a sessão. Ficheiros de configuração como settings.json são lidos novamente no arranque, portanto não é necessário repetir os valores definidos 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 entrou na shell vai apresentar o erro de chave de API inválida, mesmo que tenha funcionado corretamente da última vez.

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 armazenada na sua conta nem é sincronizada com a cloud. É um ficheiro no disco desse sistema.

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 os dois. Se trabalha como a maioria das pessoas, executando Claude Code no tmux numa VPS, o servidor é onde se acumula o seu verdadeiro histórico de conversas, 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 os seus próprios históricos de sessões, e nenhum dos dois corresponde ao histórico da CLI. Claude Code na Web também tem o seu próprio histórico. Cowork está ainda mais separado, sendo executado numa sandbox da Anthropic em vez de hardware que controla. Por isso, se estiver a comparar Cowork com Claude Code, o local onde a transcrição fica armazenada faz parte da decisão.

Dentro de uma máquina, a pesquisa é mais abrangente do que pode esperar. claude --resume <session-id> procura primeiro no diretório do projeto atual e nos respetivos 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 Claude Code informa-o desse facto com No conversation found with session ID: <session-id>.

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

Por predefiniçã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ífenes. Assim, uma sessão iniciada em /home/deploy/apps/api é armazenada num diretório chamado -home-deploy-apps-api. Se esse nome convertido ultrapassar 200 caracteres, o Claude Code trunca-o e acrescenta um hash do caminho completo, para manter o nome do diretório 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 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 do 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 Anthropic recomenda usar /export ou as interfaces de script documentadas, precisamente por esse motivo.

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

O que existe efetivamente nesses ficheiros de transcrição

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

Pense no que isso significa num servidor. Se o Claude leu um ficheiro .env para determinar por que motivo 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 a sua finalidade, e é 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 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 estão restritas.
• Uploads deliberados: o comando /feedback envia intencionalmente o histórico da conversa para a Anthropic, e /bug e /share comunicam através do mesmo caminho. São ações que escolhe executar, por isso 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 gravação de transcrições, e --no-session-persistence impede-as numa única execução não interativa de claude -p. Compreenda claramente o compromisso antes de definir qualquer uma das opções. As transcrições são necessárias para retomar sessões, por isso, sem transcrição, não há 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, se não tiver definido nenhum, 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 limita a lista ao 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 realçada.

Dar nomes às sessões torna tudo isto muito mais simples. Inicie uma com claude -n auth-refactor ou execute /rename auth-refactor a meio da sessão, quando perceber que a conversa se transformou numa tarefa de trabalho concreta. 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 identificar a linha no seletor, mas não pode ser usado para retomar a sessão. claude --resume <name> corresponde apenas aos nomes definidos por si.

Procurar nos transcripts para encontrar a sessão correta

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

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

Isto mostra os caminhos dos transcripts correspondentes. O nome do ficheiro sem a extensão .jsonl é o ID da sessão, que claude --resume <session-id> aceita. Use grep para determinar qual sessão pretende e, em seguida, retome-a ou exporte-a para a ler efetivamente.

Duas ressalvas importantes. O conteúdo usa escapes 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 introduziu.

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 traz todo o histórico de volta, e é esse histórico completo que cada pedido posterior transporta. Continuar hoje uma conversa que durou quatro horas ontem é dispendioso, e como o consumo de tokens se acumula numa sessão longa explica de onde vem esse custo.

Por vezes, o Claude Code 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. Nessa altura, a cache do prompt expirou, pelo que o pedido seguinte processa novamente todo o histórico uma vez, independentemente da opção escolhida.

• Resume from summary executa imediatamente uma compactação, pelo que os pedidos posteriores transportam um resumo em vez do histórico completo. O custo por pedido é menor, mas o que o resumo omitir deixa de estar disponível.
• Resume full session as-is carrega a conversa sem alterações, mantendo todos os detalhes a um custo por pedido que aumenta com o tamanho da conversa.

Existe uma terceira opção: retomar a sessão completa e impedir que a caixa de diálogo volte a aparecer em retomadas posteriores.

A decisão é mais simples do que parece. Retome quando aquilo que está prestes a escrever depender do que já foi dito. Comece do zero quando não depender. É fácil identificar a deriva quando se sabe o que procurar: o Claude refere-se 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 aumenta simultaneamente o consumo de tokens e reduz a precisão.

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 para a cópia, deixando o original intacto e disponível no seletor. Use esta opçã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 usa o formato JSONL: uma sequência de objetos JSON, um 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.

Por que motivo 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 o portátil se quiser manter um registo local.

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

Sim, se tiver o ID da 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 amplia a lista para todos os projetos da máquina e Ctrl+W amplia-a para 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. Comece uma nova quando isso não acontecer, porque retomar carrega todo o histórico e cada pedido posterior passa a incluí-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 em conta esta consequência: o comando de retoma lê as transcrições, por isso desativá-las significa que --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 encriptado e reduza cleanupPeriodDays.