Skip to main content
Uma sessão é uma conversa salva vinculada a um diretório de projeto. Claude Code a armazena localmente conforme você trabalha, para que você possa retomar de onde parou, criar um branch para tentar uma abordagem diferente ou alternar entre tarefas. O aplicativo desktop, claude.ai/code e a extensão VS Code cada um mantém sua própria lista de sessões, e o aplicativo desktop também pode retomar uma sessão CLI. Esta página abrange a CLI.

​
Retomar uma sessão

As sessões são salvas continuamente em arquivos de transcrição locais conforme você trabalha, para que você possa retornar a uma após sair ou executar /clear. Use estes pontos de entrada:

​
Retomar uma sessão em background em execução

Quando a conversa que você retoma com claude --resume ou /resume pertence a uma sessão em background que ainda está em execução, Claude Code abre a sessão em execução em si. Com --bg na linha de comando, a retomada é um dispatch em background em vez disso. Antes da v2.1.285, Claude Code recusava e dizia para você abrir a sessão com claude attach <id>, ou para pará-la com claude stop <id> primeiro.
  • Do seu shell: claude --resume <session> executa claude attach nessa sessão no mesmo terminal em vez de carregar a transcrição em si. Um prompt que você passa na linha de comando, como em claude --resume <session> "check the tests too", vai para a sessão como seu próximo turno primeiro, e Claude Code imprime Sent your prompt to the background session (<id>); opening it… antes de anexar. claude -p --resume <session> "prompt" digitado em um terminal faz o mesmo, portanto -p não mantém essa execução não interativa. Claude Code não abre a sessão quando a linha de comando tem qualquer um destes:
    • Entrada ou saída canalizada ou redirecionada
    • Flags que configuram a sessão, como --permission-mode, --model ou --settings
    • Flags que leem a saída, como --output-format json ou --json-schema
    • Flags que limitam ou rebobinam a execução, como --max-turns ou --max-budget-usd
    Com qualquer um destes, ou quando agent view está desativado, Claude Code não envia nada e sai com status 1, imprimindo que a sessão está em execução no background junto com o comando claude attach <id> que a abre, ou dizendo para você encontrá-la em claude agents quando não conseguir determinar o ID. Adicione --fork-session para retomar uma cópia da conversa em vez disso. Para continuar a conversa em si em uma sessão sua, com suas flags aplicadas, execute claude stop <id> e depois repita o comando. Um prompt que começa com / ou ! não é enviado, e nem é qualquer prompt enquanto a sessão aguarda sua resposta a uma pergunta. Em ambos os casos Claude Code não abre a sessão, e a mensagem inclui Your prompt was not sent to it com o motivo.
  • De dentro de uma sessão: /resume move sua conversa atual para o background e anexa este terminal à sessão em execução, imprimindo Opening "<title>", running in the background (<id>). Pressione ← em um prompt vazio para retornar à agent view, que também lista a conversa que você deixou. Quando a conversa atual não consegue se mover para o background, por exemplo porque você já está anexado a uma sessão em background ou a persistência de sessão está desativada, /resume imprime o comando claude attach para executar em vez disso.

​
O que uma sessão retomada restaura

Quando Claude Code carrega uma conversa de sua transcrição, a sessão retomada restaura a conversa junto com o estado salvo nela:
  • Histórico de conversa: o histórico completo, incluindo chamadas de ferramenta e resultados. Uma ferramenta que ainda estava em execução quando o processo anterior terminou, por exemplo em uma falha, não termina ou executa novamente quando você retoma. Claude vê a chamada marcada como interrompida antes de seu resultado ser registrado e é instruído a verificar se ela teve efeito antes de executá-la novamente, a menos que CLAUDE_CODE_RESUME_INTERRUPTED_TURN esteja definido.
  • Modelo: a sessão continua no modelo que estava usando, exceto nos casos descritos em Configurar seu modelo.
  • Agente: uma sessão iniciada com --agent ou a configuração agent continua como esse agente, mantendo suas restrições de ferramentas e modelo. Passe --agent ao retomar para escolher um diferente; para o system prompt em ambos os casos, veja Flags de system prompt em conversas retomadas. Claude Code procura o agente em dois lugares: o diretório original da sessão, desde que você tenha confiado nesse workspace, e depois o diretório de onde você retoma, para que um agente com escopo de projeto ainda carregue quando você retoma de outro diretório. Se Claude Code não encontrar o agente em nenhum dos dois lugares, a sessão retoma com as ferramentas padrão e mostra um aviso nomeando o agente.
  • Modo de permissão: se você retomar de um terminal com claude --continue, claude --resume <session-id> ou claude --resume <name> quando o nome corresponde a uma sessão, sem -p, Claude Code restaura o modo de permissão em que a sessão estava, exceto nos casos em modo de permissão ao retomar, que também cobre o seletor de sessão, /resume e retomar com claude -p. Passe --permission-mode ou --dangerously-skip-permissions para sobrescrever o modo restaurado.
  • Objetivo ativo: um objetivo que ainda estava ativo quando a sessão terminou é transferido; sua contagem de turnos, temporizador e linha de base de gasto de tokens são redefinidos.
  • Tarefas agendadas: tarefas que não expiraram são restauradas. Tarefas Bash em background e tarefas de monitoramento não são.
  • Trabalho em background: um subagente em background, comando Bash em background ou workflow que terminou com o processo anterior aparece na transcrição retomada como uma nota de que não foi concluído. Claude Code não inicia um turno a partir dessas notas; Claude as lê com seu próximo prompt.
Nem toda flag de configuração do lançamento original é restaurada. Se a sessão dependia de --mcp-config, --settings, --plugin-dir, --fallback-model ou diretórios adicionados com --add-dir, passe-os novamente quando você retomar; diretórios adicionados no meio da sessão com /add-dir também não são restaurados, embora o seletor de sessão ainda os use para localizar a sessão. Os arquivos de configurações padrão, como settings.json e settings.local.json, são relidos no lançamento, portanto a configuração que reside neles não precisa ser passada novamente. Para --system-prompt e --append-system-prompt, veja Flags de system prompt em conversas retomadas.

​
Modo de permissão ao retomar

Qual modo de permissão Claude Code inicia uma sessão retomada depende de como você retoma. Os casos abaixo se aplicam quando Claude Code carrega a conversa de sua transcrição; quando você abre uma sessão em background que ainda está em execução em vez disso, essa sessão mantém o modo de permissão em que está.
  • Terminal: claude --continue, claude --resume <session-id> ou claude --resume <name> quando o nome corresponde a uma sessão, sem -p. Claude Code restaura o modo de permissão em que a sessão estava, exceto nos casos da tabela. Passe --permission-mode ou --dangerously-skip-permissions para sobrescrever o modo restaurado.
  • Não interativo: claude -p --resume ou claude -p --continue. Claude Code inicia a execução no modo de permissão em que uma nova execução claude -p iniciaria, exceto que uma sessão que terminou em modo de planejamento retoma em modo de planejamento sob as condições abaixo.
  • VS Code: o painel de conversa da extensão. A tabela cobre apenas uma conversa que terminou em modo de planejamento; para o resto, veja retomar conversas passadas.
  • Seletor de sessão no lançamento: uma sessão que você seleciona do seletor de sessão, se você o abriu com claude --resume sozinho, claude --from-pr ou um nome que corresponde a mais de uma sessão. Claude Code inicia a sessão no modo de permissão em que iniciaria uma nova sessão a partir da mesma linha de comando, exceto que uma sessão que terminou em modo de planejamento retoma em modo de planejamento. Se você passar --permission-mode, --dangerously-skip-permissions ou --fork-session, Claude Code não restaura o modo de planejamento. Nenhum outro modo de permissão armazenado é restaurado.
  • /resume dentro de uma sessão, com ou sem um argumento: a conversa para a qual você alterna continua no modo de permissão em que sua sessão atual está, exceto que uma conversa que terminou em modo de planejamento retoma em modo de planejamento, mesmo que você tenha iniciado Claude Code com --permission-mode ou --dangerously-skip-permissions. Se essa conversa já estava aberta anteriormente nesta execução de Claude Code, como a conversa em que você começou ou uma que você deixou com /clear ou /resume, ela continua no seu modo de permissão atual em vez disso.
Se uma regra de negação remover a ferramenta ExitPlanMode, Claude não pode apresentar um plano para aprovação, portanto Claude Code não restaura o modo de planejamento. A sessão inicia no modo de permissão em que uma nova sessão iniciaria a partir da mesma linha de comando. Com /resume, a conversa continua no seu modo de permissão atual. Restaurar o modo de planejamento nos caminhos não interativo e VS Code requer Claude Code v2.1.246 ou posterior. Cada linha nomeia o modo de permissão em que a sessão terminou, qual dos caminhos terminal, não interativo e VS Code você a retoma, e o modo de permissão em que Claude Code inicia a sessão retomada. Uma execução claude -p --resume ou claude -p --continue retoma em modo de planejamento apenas quando todas estas condições se mantêm:

​
Retomar de um resumo

Em um plano Pro ou Max, quando você retoma uma sessão que ficou inativa por mais de cerca de uma hora e tem mais de 100.000 tokens, Claude Code restaura a conversa e depois abre um diálogo antes de você enviar sua primeira mensagem. O cache de prompt da sessão terá expirado até então, portanto a próxima requisição processa o histórico completo uma vez, não importa qual das opções do diálogo você escolha. O diálogo oferece três maneiras de continuar a sessão:
  • Retomar do resumo: executa /compact imediatamente. Requisições posteriores carregam o resumo em vez do histórico completo.
  • Retomar sessão completa como está: carrega a conversa inalterada.
  • Não me pergunte novamente: retoma a sessão completa e para de mostrar o diálogo em todas as futuras retomadas.
Retomar como está mantém cada detalhe da conversa disponível, a um custo por requisição que escala com o tamanho da conversa. Retomar do resumo custa menos em cada requisição posterior porque carrega o resumo em vez do histórico completo, mas o que quer que o resumo deixe de fora não está mais no contexto de Claude. Veja por que o uso sobe em uma sessão longa para saber de onde vem esse custo por requisição.

​
Onde o seletor de sessão procura

Claude Code armazena sessões por diretório de projeto. Por padrão, o seletor de sessão mostra:
  • Sessões do worktree atual, incluindo sessões em background, que são marcadas bg na lista
  • Sessões iniciadas em outro lugar que adicionaram o diretório atual com /add-dir
Use Ctrl+W para expandir para todos os worktrees do repositório ou Ctrl+A para expandir para cada projeto nesta máquina.

​
/loop, -p, Agent SDK e sessões em background

Sessões cujo primeiro prompt foi um comando /loop não aparecem no seletor, e claude --continue também as pula. Executar /loop mais tarde em uma conversa não oculta a sessão. Claude Code deixa as sessões criadas com claude -p ou o Agent SDK fora do seletor de sessão e fora de claude --continue. Você ainda pode retomar uma passando seu ID de sessão para claude --resume <session-id>. Quando você executa claude -p --continue, Claude Code inclui sessões -p, SDK e /loop. claude --continue abre uma sessão em background que foi concluída, mas não uma que ainda está em execução; abrir sessões em background concluídas requer Claude Code v2.1.257 ou posterior. Se sua conversa mais recente for uma que você moveu para o background e ainda estiver em execução lá, Claude Code sai com Your most recent conversation is running in the background e o ID dessa sessão. Anexe à sessão a partir de claude agents, ou execute claude --resume para escolher outra.

​
Sessões em outros worktrees e projetos

Quando você seleciona uma sessão de outro worktree do mesmo repositório, Claude Code a retoma no local; quando o próprio worktree da sessão não existe mais, Claude Code a retoma no seu diretório atual. Quando você seleciona uma sessão de um projeto não relacionado, Claude Code copia um comando cd e de retomada para sua área de transferência em vez disso. Se o diretório desse projeto não existir mais, Claude Code retoma a sessão no seu diretório atual em vez de copiar um comando cd que falharia. Mover uma sessão com /cd a realoca para o armazenamento de projeto do novo diretório, para que apareça no seletor desse diretório depois.

​
Retomar por ID de sessão ou nome

Você pode executar claude --resume <session-id> de qualquer diretório, para que possa retomar uma sessão que começou em outro lugar ou se moveu com /cd. Claude Code procura o ID nesta ordem:
  1. O diretório do projeto atual e seus git worktrees
  2. Todos os outros projetos nesta máquina
A busca entre projetos resolve o ID apenas quando exatamente um outro projeto contém uma transcrição com mensagens para ele, portanto uma duplicata copiada manualmente faz Claude Code relatar não encontrado em vez de retomar uma cópia arbitrária. Se nenhuma sessão armazenada corresponder ao ID, Claude Code relata No conversation found with session ID: <session-id>. Retomar por nome resolve no repositório atual e seus worktrees. Ambas as formas procuram por uma correspondência exata e a retomam diretamente mesmo que resida em um worktree diferente:

​
Nomeie suas sessões

Dê às sessões nomes descritivos para que sejam encontráveis no seletor de sessão e retomáveis por nome. Isso é mais importante quando você está trabalhando em várias tarefas em paralelo. Depois que você nomeia uma sessão através de uma rota CLI ou do claude.ai, retorne a ela com claude --resume <name> ou /resume <name>; uma sessão do aplicativo desktop retoma no aplicativo desktop. Veja Retomar uma sessão para saber como a resolução de nomes se comporta entre worktrees. Sessões que você não nomeia ainda recebem dois rótulos que Claude Code atribui. Apenas o título gerado funciona como um identificador de retomada:
  • Nome de exibição padrão: sessões interativas que você nunca nomeia ainda recebem um nome de exibição padrão quando iniciam. Requer Claude Code v2.1.196 ou posterior. O padrão combina o nome do diretório de trabalho com um sufixo de dois caracteres, por exemplo my-app-3f, e identifica a sessão em listagens de sessões em execução, como agent view e saída de claude agents --json. O padrão não é um identificador de retomada. Se você o passar para claude --resume ou /resume, Claude Code não encontra a sessão.
  • Título gerado: se você não nomear uma sessão, Claude Code gera um título de sessão para ela. O título é um resumo breve do seu primeiro prompt, escrito por uma solicitação em background para o modelo pequeno/rápido, normalmente um modelo da classe Haiku. Um claude -p executado que você inicia diretamente de um shell ou script não recebe um. Aceitar um plano substitui o título gerado por um título baseado no plano. Você pode passar qualquer um dos títulos para claude --resume ou /resume, e Claude Code o resolve da mesma forma que um nome que você definiu.

​
Use o seletor de sessão

Execute /resume dentro de uma sessão ou claude --resume sem argumentos para abrir o seletor de sessão interativo. Use estes atalhos de teclado para navegar, pesquisar e expandir a lista: Cada linha mostra o nome da sessão se você definir um, caso contrário, o título de sessão gerado por IA, resumo da conversa ou primeiro prompt, junto com o tempo desde a última atividade, branch git e tamanho do arquivo. As sessões criadas com /branch ou --fork-session recebem seus próprios IDs de sessão e aparecem como linhas separadas. Quando o seletor encontra mais de uma entrada para a mesma sessão, ele as agrupa sob uma única linha. Pressione → para expandir um grupo. Se Claude Code não conseguir carregar a sessão que você selecionar no seletor claude --resume, ele imprime Failed to resume the conversation com um comando para tentar novamente e sai com código 1. No seletor /resume dentro de uma sessão, Claude Code relata a falha e sua conversa atual continua em execução.

​
Ramificar uma sessão

Ramificar cria uma cópia da conversa até agora e o coloca nela, deixando o original intacto. Use-o para tentar uma abordagem diferente sem perder o caminho em que você estava. De dentro de uma sessão, execute /branch com um nome opcional:
Se você omitir o nome, Claude Code nomeia o novo branch com base no primeiro prompt da conversa. Na linha de comando, combine --continue ou --resume com --fork-session:
A confirmação /branch imprime dois IDs de sessão: o novo branch em que você está agora e o original. O original permanece inalterado no disco e continua no seletor de sessão; retorne a ele com /resume <original-name> ou passando seu ID para /resume. /branch copia o transcrição e muda o processo Claude Code em execução para escrever nela. Essa distinção determina o que o branch herda: Se você retomar a mesma sessão em dois terminais sem bifurcar, as mensagens de ambos se intercalam em um transcrição. Para rewind baseado em checkpoint dentro de uma única sessão, veja Checkpointing.

​
Gerenciar contexto dentro de uma sessão

Estes comandos controlam o que está na janela de contexto sem deixar a sessão:
  • /clear: comece do zero com um contexto vazio. Claude Code salva a sessão anterior; retome-a com /resume, ou, no mesmo processo Claude Code, a partir da entrada de sessão anterior do menu de rewind. Sem argumentos, a nova sessão mantém um nome que você definiu com --name ou /rename, mas não um título de sessão gerado por IA. Para nomear a sessão que você está deixando, passe o nome, como em /clear release-prep; a nova sessão então começa sem nome
  • /compact [instructions]: substitua o histórico por um resumo, opcionalmente focado no que você especificar
  • /context: mostrar o que está consumindo contexto atualmente
Para saber como a compactação interage com CLAUDE.md, skills e regras, veja o guia de janela de contexto. Para estratégias sobre quando limpar versus compactar, veja Melhores práticas.

​
Exportar e localizar dados de sessão

Execute /export para abrir um menu que permite copiar a conversa atual para sua área de transferência ou salvá-la como um arquivo de texto simples, com mensagens e saídas de ferramentas renderizadas como texto legível. Passe um nome de arquivo para pular o menu e escrever diretamente nesse arquivo.

​
Acessar conversas a partir de scripts

/export produz uma transcrição renderizada para uma pessoa ler. As interfaces abaixo produzem dados estruturados para um script analisar: um resultado JSON de uma execução, o caminho para o arquivo de transcrição de uma sessão, ou um fluxo ao vivo de eventos. Escolha pelo que dispara o script:
  • Executar Claude uma vez e capturar o resultado: invoque claude -p com --output-format json ou stream-json para capturar o resultado, ID da sessão, uso e custo de uma execução não interativa como JSON estruturado.
  • Fazer uma pergunta a uma sessão existente: passe um ID de sessão para claude -p --resume para enviar um prompt de acompanhamento, como uma solicitação de resumo, e capturar a resposta estruturada.
  • Reagir a eventos de sessão: leia o campo transcript_path que hooks e comandos de linha de status recebem como entrada. Um hook SessionEnd pode arquivar a transcrição quando uma sessão termina.
  • Incorporar Claude em um aplicativo TypeScript ou Python: use o Agent SDK para receber cada mensagem programaticamente.
O exemplo abaixo usa a segunda interface. Ele envia um prompt de acompanhamento para uma sessão existente e lê a resposta com jq:

​
Onde os transcritos são armazenados

Por padrão, Claude Code armazena transcritos como JSONL em ~/.claude/projects/<project>/<session-id>.jsonl, onde <project> é o caminho do seu diretório de trabalho com caracteres não alfanuméricos substituídos por -. Para um diretório de trabalho cujo nome convertido excede 200 caracteres, Claude Code trunca o nome para 200 caracteres e anexa um hash do caminho completo, para que o nome do diretório permaneça dentro dos limites do sistema de arquivos. Cada linha é um objeto JSON para uma mensagem, uso de ferramenta ou entrada de metadados. O formato de entrada é interno ao Claude Code e muda entre versões, portanto scripts que analisam esses arquivos diretamente podem quebrar em qualquer versão. Para construir sobre dados de sessão, use /export ou as interfaces de script em vez disso. A localização, retenção e comportamento de gravação são configuráveis:

​
Excluir dados de sessão

As transcrições expiram sob as regras de varredura de retenção. Para excluir as transcrições de um projeto e o estado relacionado mais cedo, execute claude purge. Se você excluir uma sessão em segundo plano com claude rm <id>, sua transcrição permanece no disco e continua disponível através de claude --resume.

​
Nomear o diretório do projeto você mesmo

Por padrão, Claude Code deriva o nome <project> do caminho completo do diretório de trabalho. Para escolher o nome você mesmo, defina CLAUDE_CODE_PROJECT_DIR_NAME junto com CLAUDE_CONFIG_DIR. Claude Code então armazena os transcritos dessa sessão e memória automática sob seu nome. Isso é adequado para um host que incorpora Claude Code e fornece a cada sessão seu próprio diretório de configuração. Requer Claude Code v2.1.234 ou posterior. Por exemplo, este lançamento mantém os dados do inquilino A sob /srv/tenant-a e nomeia seu diretório de projeto como work:
Claude Code escreve os transcritos da sessão para /srv/tenant-a/projects/work/ e sua memória automática para /srv/tenant-a/projects/work/memory/, seja qual for o diretório de trabalho. Três regras se aplicam quando você o define:
  • Defina CLAUDE_CONFIG_DIR também: o nome não varia com o diretório de trabalho, portanto sob o padrão ~/.claude ele mesclaria os transcritos e memória automática de cada projeto em um diretório. Claude Code ignora CLAUDE_CODE_PROJECT_DIR_NAME quando CLAUDE_CONFIG_DIR não está definido.
  • Use 1-64 letras, dígitos, hífens ou sublinhados: não use um nome de dispositivo Windows como con. Claude Code ignora qualquer outro valor e usa o nome derivado.
  • Defina-o no ambiente shell que inicia claude: Claude Code o lê uma vez na inicialização desse ambiente, portanto um bloco env em um arquivo de configurações não pode defini-lo.
Depois de nomear o diretório do projeto de um diretório de configuração, continue lançando com esse nome. Se você iniciar Claude Code com o mesmo CLAUDE_CONFIG_DIR mas sem CLAUDE_CODE_PROJECT_DIR_NAME, ele lê e escreve o diretório derivado novamente. As sessões armazenadas sob seu nome permanecem no disco: pressione Ctrl+A no seletor de sessão para listar sessões de cada diretório de projeto sob esse diretório de configuração, o fixado incluído, e de qualquer forma que você lance, claude --resume <session-id> encontra uma sessão armazenada sob qualquer um dos nomes.

​
Veja também

Estas páginas cobrem mecânicas relacionadas de sessão e paralelismo: