Gerenciar sessões

Nomeie, retome, ramifique e alterne entre conversas do Claude Code. Abrange --continue, --resume, --from-pr, o seletor /resume, nomeação de sessão, exportação de transcritos e onde os transcritos são armazenados.

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, ramificar para tentar uma abordagem diferente ou alternar entre tarefas.

O aplicativo desktop, Claude Code na web e a extensão VS Code mantêm seu próprio histórico de sessões. 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:

As sessões criadas com claude -p ou o Agent SDK não aparecem no seletor de sessão, mas você ainda pode retomar uma passando seu ID de sessão para claude --resume <session-id>. Execute isto a partir do diretório em que a sessão foi iniciada: a busca de ID de sessão é limitada ao diretório do projeto atual e seus git worktrees, portanto uma sessão criada em outro lugar relata No conversation found with session ID: <session-id>.

Onde o seletor de sessão procura

As sessões são armazenadas por diretório de projeto. Por padrão, o seletor de sessão mostra sessões interativas da worktree atual, além de sessões iniciadas em outro lugar que adicionaram o diretório atual com /add-dir. Use Ctrl+W para expandir para todas as worktrees do repositório ou Ctrl+A para expandir para cada projeto nesta máquina.

{/* min-version: 2.1.169 /}A partir da v2.1.169, mover uma sessão com /cd a relocata para o armazenamento de projeto do novo diretório, para que apareça no seletor desse diretório depois. {/ min-version: 2.1.196 */}A partir da v2.1.196, uma sessão movida fica fora do seletor do diretório antigo mesmo após uma falha ou saída forçada. Em versões anteriores, ela também poderia reaparecer na lista do diretório antigo após uma saída que não foi limpa quando o caminho antigo continha caracteres especiais como sublinhados.

Selecionar uma sessão de outra worktree do mesmo repositório a retoma no local. Selecionar uma sessão de um projeto não relacionado copia um comando cd e retoma para sua área de transferência.

Retomar por nome resolve no repositório atual e suas worktrees. Ambas as formas procuram por uma correspondência exata e a retomam diretamente mesmo que resida em uma 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 uma sessão é nomeada, retorne a ela com claude --resume <name> ou /resume <name>. Veja Retomar uma sessão para saber como a resolução de nomes se comporta entre worktrees.

{/* min-version: 2.1.196 */}As 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: claude --resume <name>, /resume <name> e o seletor de sessão correspondem apenas aos nomes que você definiu. Nomear a sessão substitui o padrão.

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 definido, caso contrário, o resumo da conversa ou o primeiro prompt, junto com o tempo desde a última atividade, contagem de mensagens e branch git. O caminho do projeto aparece depois que você expande para todos os projetos com Ctrl+A.

As sessões bifurcadas criadas com /branch, /rewind ou --fork-session são agrupadas sob sua sessão raiz. Pressione → para expandir um grupo.

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:

/branch try-streaming-approach

Na linha de comando, combine --continue ou --resume com --fork-session:

claude --continue --fork-session

A sessão original permanece inalterada e disponível no seletor de sessão. A confirmação /branch imprime dois IDs de sessão: o novo branch em que você está agora e o original. Para retornar ao original, passe seu ID para /resume, use o seletor de sessão ou execute /resume <original-name>. As permissões que você aprovou com "permitir para esta sessão" não são transferidas para o novo branch. 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. A conversa anterior é salva e retomável
• /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:

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

Onde os transcritos são armazenados

Por padrão, os transcritos são armazenados 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 -. 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:

Veja também

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

• Worktrees: execute sessões paralelas isoladas em branches separados
• Checkpointing: retroceda código e conversa para um ponto anterior
• Janela de contexto: o que preenche o contexto e o que sobrevive à compactação
• Modo não interativo: comportamento de sessão sob claude -p