Gerenciamento de Sessões

Trabalhar em múltiplos projetos ou tarefas pode ser desafiador, especialmente quando cada um possui um contexto de conversa diferente. O ChatCLI resolve isso com um sistema simples e poderoso de gerenciamento de sessões. Uma sessão é essencialmente um “salvamento” completo do seu histórico de conversa, permitindo que você a retome exatamente de onde parou.

O ChatCLI usa um histórico unificado — um único array de mensagens compartilhado entre todos os modos (chat, agent, coder). Ao salvar uma sessão, todo o contexto e preservado independente do modo em que foi gerado. Use /compact para reduzir o tamanho e /rewind para voltar a pontos anteriores.

Comandos de Sessão

Todos os comandos de gerenciamento de sessão começam com /session.

/session save <nome>

Salva a conversa atual (todo o histórico de prompts e respostas) com um nome de sua escolha.

/session save debug-api-pagamentos

Sessão 'debug-api-pagamentos' salva com sucesso.

Após salvar, o nome da sessão aparecerá no seu prompt (ex: debug-api-pagamentos), indicando que você está trabalhando nela.

/session load <nome>

Carrega uma sessão salva anteriormente. A conversa atual é substituída pelo histórico da sessão carregada.

/session load documentação-site

Sessão 'documentação-site' carregada. A conversa anterior foi restaurada.

/session list

Lista todas as sessões que você salvou no disco.

/session list

Sessões salvas:

  - debug-api-pagamentos
  - documentação-site
  - refatoração-legado

/session delete <nome>

Remove permanentemente uma sessão salva do disco. Esta ação não pode ser desfeita.

/session delete refatoração-legado

Sessão 'refatoração-legado' deletada com sucesso do disco.

Se você deletar a sessão que está ativa no momento, seu histórico atual será limpo e você começará uma nova conversa.

/session new (ou /newsession)

Limpa o histórico atual e inicia uma conversa completamente nova. É perfeito para começar uma tarefa do zero sem estar atrelado a nenhuma sessão nomeada.

/session new

Nova sessão de conversa iniciada; histórico foi limpo.

/session fork <novo-nome>

Cria uma cópia independente da sessão atual com um novo nome. O original permanece intacto e você automaticamente passa a trabalhar no fork.Ideal para experimentar abordagens diferentes sem perder o progresso atual, ou para ramificar uma conversa em direções distintas.

/session fork experimento-v2

╭── ✅ Session forked!
│    De:   minha-sessão
│    Para: experimento-v2
│    Mensagens: 42
│    Agora trabalhando no fork. O original permanece intacto.
╰──────────────────────────────────────────────

Funciona tanto com sessões salvas quanto com sessões em memória (não salvas). No caso de sessões não salvas, o fork é criado a partir do histórico atual.

Onde as Sessões são Armazenadas

As sessões são salvas como arquivos JSON no diretório de trabalho atual (CWD) — ou seja, o diretório de onde você iniciou o ChatCLI. O padrão de nomenclatura dos arquivos é:

.chatcli_session_<nome>.json

Por exemplo, ao executar /session save debug-api, o arquivo criado será:

.chatcli_session_debug-api.json

O SessionManager é o componente interno responsável por toda a E/S de arquivos de sessão. Ele trata erros de leitura/escrita (permissões, disco cheio, JSON malformado) e exibe mensagens claras caso algo falhe.

Os arquivos de sessão contêm o histórico completo da conversa no momento do salvamento — incluindo mensagens do usuário, respostas da IA, resultados de tool calls e resumos gerados por /compact.

Como os arquivos ficam no CWD, se você iniciar o ChatCLI de diretórios diferentes, verá sessões diferentes. Use /session list para verificar quais sessões estão disponíveis no diretório atual.

Formato de Dados (v2)

Os arquivos de sessão utilizam o formato v2, definido pela struct SessionData no pacote models. A estrutura JSON é:

{
  "version": 2,
  "chat_history": [
    {
      "role": "user",
      "content": "Explique o padrão Repository",
      "meta": {
        "is_summary": false,
        "summary_of": 0,
        "mode": "chat"
      },
      "tool_calls": null,
      "tool_call_id": ""
    },
    {
      "role": "assistant",
      "content": "O padrão Repository é...",
      "meta": {
        "is_summary": false,
        "summary_of": 0,
        "mode": "chat"
      },
      "tool_calls": null,
      "tool_call_id": ""
    }
  ],
  "agent_history": [],
  "coder_history": [],
  "shared_memory": []
}

Campos de cada mensagem

Campo	Tipo	Descrição
`role`	string	`"user"`, `"assistant"`, `"system"` ou `"tool"`
`content`	string	Conteúdo textual da mensagem
`meta.is_summary`	bool	`true` se a mensagem é um resumo gerado por `/compact`
`meta.summary_of`	int	Número de mensagens originais que este resumo representa
`meta.mode`	string	Modo em que a mensagem foi gerada (`"chat"`, `"agent"`, `"coder"`)
`tool_calls`	array/null	Lista de chamadas de ferramenta (agent/coder mode)
`tool_call_id`	string	ID da tool call que está mensagem responde (para mensagens `role: "tool"`)

Evolução do formato

v1 (versões antigas): Mantinha históricos separados por modo — chat_history, agent_history e coder_history cada um com suas próprias mensagens.
v2 (versão atual): Usa um histórico unificado. O campo chat_history contém todas as mensagens de todos os modos. Os campos agent_history e coder_history existem por compatibilidade, mas ficam vazios em sessões novas.

Ao carregar uma sessão v1 (com históricos separados por modo), o ChatCLI mescla automaticamente as mensagens em ordem cronológica no histórico unificado. Nenhuma intervenção manual é necessária.

Histórico Unificado e Sessões

O ChatCLI usa um único array de mensagens para todos os modos de interação. Isso significa que:

Ao salvar uma sessão, o histórico inteiro e unificado é serializado — incluindo mensagens de chat, agent e coder mode.
Mensagens do sistema, resultados de tool calls e resumos compactados são todos preservados no arquivo.
Ao carregar uma sessão, o histórico atual é completamente substituído pelo da sessão carregada.

O nome da sessão ativa aparece como prefixo no prompt interativo:

[debug-api] claude-sonnet-4-6>

Isso facilita saber em qual contexto você está trabalhando a qualquer momento.

Carregar uma sessão substitui todo o histórico atual. Se você tem uma conversa não salva, ela será perdida. Salve antes com /session save se quiser preservá-la.

Interação com Outros Sistemas

As sessões interagem com vários outros subsistemas do ChatCLI. Veja como cada um se comporta:

Compactação (`/compact`)

O comando /compact reduz o tamanho do histórico criando resumos das mensagens mais antigas. Ao salvar uma sessão após compactar, o arquivo resultante será significativamente menor, pois contém os resumos em vez das mensagens originais.

Rewind (`/rewind`)

Os checkpoints usados pelo /rewind existem apenas em memória durante a execução atual. Eles não são salvos no arquivo de sessão. Ao carregar uma sessão, você não terá pontos de rewind disponíveis até criar novos durante a conversa.

Bootstrap (SOUL.md, etc.)

Arquivos de bootstrap não fazem parte da sessão. Eles são carregados automaticamente a cada inicialização do ChatCLI, independente de qual sessão esteja ativa. Isso garante que o comportamento base da IA seja sempre consistente.

Memória (`/memory`)

A memória é global — não está vinculada a nenhuma sessão específica. Dados salvos com /memory save ficam disponíveis em todas as sessões e sobrevivem ao encerramento do ChatCLI.

Contexto (`/context attach`)

Contextos anexados via /context attach não são salvos no arquivo de sessão. Ao carregar uma sessão, você precisa re-anexar os contextos necessários manualmente.

Resumo rápido: Sessões salvam apenas o histórico de mensagens. Bootstrap, memória, contextos e checkpoints de rewind são gerenciados separadamente.

Auto-Save e Persistência

Sessões não são salvas automaticamente. Você deve chamar /session save explicitamente para persistir a conversa no disco.

Se você fechar o ChatCLI sem salvar, o histórico da conversa será perdido permanentemente. Não há mecanismo de recuperação automática.

Arquivo `.chatcli_history` (não confundir)

O ChatCLI mantém um arquivo separado chamado .chatcli_history que armazena o histórico de comandos digitados (similar ao ~/.bash_history). Esse arquivo:

Contém apenas os textos que você digitou no prompt, não as respostas da IA
É controlado pelas variáveis de ambiente HISTORY_FILE e HISTORY_MAX_SIZE
Não tem relação com os arquivos de sessão (.chatcli_session_*.json)

Aspecto	Sessões (`.chatcli_session_*.json`)	Histórico de comandos (`.chatcli_history`)
Conteúdo	Conversa completa (user + assistant + tool)	Apenas o que você digitou
Salvamento	Manual (`/session save`)	Automático
Formato	JSON estruturado (v2)	Texto simples, uma linha por comando
Controle	Comandos `/session`	Variáveis `HISTORY_FILE`, `HISTORY_MAX_SIZE`

Workflow Recomendado

Para tirar o máximo proveito do sistema de sessões, siga estas práticas:

Nomeie sessões pela tarefa

Use nomes descritivos que identifiquem claramente o objetivo. Exemplos: fix-auth-bug, refactor-api, docs-v2, debug-memory-leak.

/session save fix-auth-bug

Compacte antes de salvar

Use /compact antes de /session save para reduzir o tamanho do arquivo e manter apenas as informações essenciais.

/compact
/session save fix-auth-bug

Inicie limpo antes de trocar de sessão

Use /session new antes de carregar outra sessão. Isso garante que o contexto anterior não interfira.

/session new
/session load refactor-api

Alterne entre tarefas livremente

Você pode ter múltiplas sessões salvas para diferentes tarefas e alternar entre elas conforme necessário.

/session save fix-auth-bug      # salva o trabalho atual
/session load refactor-api      # carrega outra tarefa
# ... trabalha na refatoração ...
/session save refactor-api      # salva o progresso
/session load fix-auth-bug      # volta para o bug

Criptografia de Sessões

Os arquivos de sessão podem ser criptografados em repouso usando AES-256-GCM para proteger dados sensíveis de conversas:

Variável	Descrição	Padrão
`CHATCLI_ENCRYPTION_KEY`	Chave de criptografia (32 bytes, base64-encoded)	`""` (desabilitado)

Quando configurada, todas as operações de sessão (save/load) usam criptografia transparente:

# Gerar uma chave segura
export CHATCLI_ENCRYPTION_KEY=$(openssl rand -base64 32)

# Salvar e carregar sessões normalmente - criptografia é transparente
/session save minha-sessão-segura
/session load minha-sessão-segura

A derivação de chaves usa HKDF (HMAC-based Key Derivation Function) para gerar chaves únicas por sessão a partir da chave mestra. Isso garante que comprometer uma sessão não compromete as demais.

Migração transparente: Sessões existentes em texto plano são automaticamente criptografadas ao serem carregadas e salvas novamente. Não é necessária nenhuma ação manual para migrar sessões antigas.

Guarde a chave de criptografia em local seguro. Se a chave for perdida, as sessões criptografadas não podem ser recuperadas.

Limpeza Automática

O ChatCLI pode remover automaticamente sessões antigas na inicialização:

Variável	Descrição	Padrão
`CHATCLI_SESSION_TTL`	Tempo de vida máximo das sessões	`90d` (90 dias)

Sessões que não foram modificadas dentro do período definido por CHATCLI_SESSION_TTL são removidas automaticamente quando o ChatCLI é iniciado. Isso evita acúmulo indefinido de sessões antigas no disco.

export CHATCLI_SESSION_TTL=30d   # Limpar sessões com mais de 30 dias
chatcli

Use CHATCLI_SESSION_TTL=0 para desabilitar a limpeza automática e manter todas as sessões indefinidamente.

Validação de Nomes

Nomes de sessão são validados com uma regex estrita para evitar path traversal e caracteres problemáticos:

Caracteres permitidos: letras (a-z, A-Z), números (0-9), hífens (-), underscores (_) e pontos (.)
Comprimento: 1 a 128 caracteres
Proibido: espaços, barras, caracteres especiais, sequências ..

Padrão: ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$

Nomes inválidos são rejeitados com uma mensagem de erro clara indicando os caracteres permitidos.

Perguntas Frequentes

As sessões são compartilhadas entre máquinas?

Não. Os arquivos de sessão são armazenados localmente no diretório de trabalho atual. Para transferir uma sessão entre máquinas, você precisaria copiar manualmente o arquivo .chatcli_session_<nome>.json para o mesmo diretório na outra máquina.

Existe limite de tamanho para as sessões?

Tecnicamente, o limite é definido pela variável HISTORY_MAX_SIZE (padrão: 100MB), mas na prática as sessões raramente passam de alguns megabytes. Se o histórico estiver muito grande, use /compact antes de salvar para reduzir significativamente o tamanho.

Posso editar o arquivo JSON da sessão manualmente?

Sim, mas com cuidado. O arquivo segue o formato v2 descrito acima. Você pode remover mensagens, editar conteúdos ou ajustar metadados. Certifique-se de manter o JSON válido e a estrutura intacta (especialmente o campo version).

O que acontece se eu carregar uma sessão de uma versão antiga?

O ChatCLI detecta automaticamente sessões no formato v1 (com históricos separados por modo) e faz a migração automática para v2, mesclando todas as mensagens em ordem cronológica no histórico unificado. O processo é transparente e não requer ação do usuário.

Posso ter sessões com o mesmo nome em diretórios diferentes?

Sim. Como os arquivos são salvos no CWD, cada diretório tem seu próprio namespace de sessões. Uma sessão chamada debug em /projeto-a é completamente independente de uma sessão debug em /projeto-b.

Próximos Passos

Controle de Conversa

Use /compact e /rewind para gerenciar o tamanho e estado do histórico.

Contexto Persistente

Salve, anexe e reutilize snapshots de projetos com o comando /context.

Bootstrap e Memória

Personalize a IA e mantenha contexto de longo prazo.

Modo One-Shot

Use o ChatCLI em scripts, automações e pipelines de CI/CD.

​Comandos de Sessão

​Onde as Sessões são Armazenadas

​Formato de Dados (v2)

​Campos de cada mensagem

​Evolução do formato

​Histórico Unificado e Sessões

​Interação com Outros Sistemas

​Compactação (/compact)

​Rewind (/rewind)

​Bootstrap (SOUL.md, etc.)

​Memória (/memory)

​Contexto (/context attach)

​Auto-Save e Persistência

​Arquivo .chatcli_history (não confundir)

​Workflow Recomendado

​Criptografia de Sessões

​Limpeza Automática

​Validação de Nomes

​Perguntas Frequentes

​Próximos Passos

Controle de Conversa

Contexto Persistente

Bootstrap e Memória

Modo One-Shot

Comandos de Sessão

Onde as Sessões são Armazenadas

Formato de Dados (v2)

Campos de cada mensagem

Evolução do formato

Histórico Unificado e Sessões

Interação com Outros Sistemas

Compactação (`/compact`)

Rewind (`/rewind`)

Bootstrap (SOUL.md, etc.)

Memória (`/memory`)

Contexto (`/context attach`)

Auto-Save e Persistência

Arquivo `.chatcli_history` (não confundir)

Workflow Recomendado

Criptografia de Sessões

Limpeza Automática

Validação de Nomes

Perguntas Frequentes

Próximos Passos