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.

Carregar também rotaciona a thread compartilhada do Conversation Hub, para que o backlog cross-channel antigo não seja emendado por cima da sessão carregada.

/session attach <nome>

Vincula a conversa a uma sessão nomeada — carrega quando ela existe, cria quando não existe. Enquanto vinculada, cada turno é gravado (write-through) no arquivo da sessão e escritas feitas por outras superfícies são adotadas antes de cada turno — veja Continuidade cross-surface.

/session attach projeto-x

/session save e /session load também vinculam: depois de qualquer um deles, a conversa fica atrelada àquele nome. attach é o alias que funciona com a sessão existindo ou não.

/session detach

Mantém a conversa atual em memória mas remove o vínculo: os turnos deixam de ser gravados no arquivo da sessão nomeada.

/session detach

/session status

Mostra se a conversa está vinculada a uma sessão nomeada, e a qual.

/session status

/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. Mesma semântica do /newsession: também remove qualquer vínculo de sessão e rotaciona a thread compartilhada do hub, para que nenhum backlog da conversa antiga vaze para a nova.

/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.

Salvamento automático no exit

Você não precisa lembrar do /session save: quando o REPL interativo encerra, a conversa é salva automaticamente sob o nome reservado autosave-YYYYMMDD-HHMMSS. Sessões triviais (menos de 2 mensagens não-system) são puladas, e execuções one-shot -p nunca salvam. Gate CHATCLI_SESSION_AUTOSAVE (on por padrão, visível em /config session). Conversas auto-salvas ficam totalmente pesquisáveis e legíveis via @session. Sessões MCP também têm autosave: o servidor MCP/ACP espelha cada conversa viva num arquivo rolling mcp-<session> após cada turno (nos caminhos full-pipeline e plain), e o manage_session clear salva uma última vez antes de descartar. Um CHATCLI_MCP_SESSION_AUTOSAVE explícito sempre vence; sem ele, segue o gate global CHATCLI_SESSION_AUTOSAVE — on por padrão. A retenção das duas superfícies está em Limpeza Automática abaixo.

Continuidade cross-surface

Uma sessão nomeada é a camada durável de continuidade entre superfícies do ChatCLI: o REPL interativo, o servidor MCP (chatcli mcp-server), o servidor ACP (chatcli acp) e o Chat Gateway leem e escrevem o mesmo arquivo de sessão. Comece no terminal, continue na IDE, termine no WhatsApp — a mesma conversa. Enquanto uma sessão nomeada está ativa (após /session save, /session load ou /session attach), o vínculo (binding) funciona nas duas direções a cada turno:

Write-through — cada turno concluído é gravado imediatamente no arquivo da sessão (escrita atômica: arquivo temporário + rename, nunca há arquivos corrompidos pela metade).
Adoção — antes de cada turno, escritas feitas por outras superfícies (servidor MCP/ACP, daemon do gateway, outro terminal) desde a última sincronização são adotadas: quando o arquivo está mais novo, ele substitui o histórico em memória por inteiro (last-writer-wins).

# Terminal
/session attach projeto-x        # vincula (cria a sessão se ainda não existir)

# IDE (prompt box do ACP)
/session attach projeto-x        # mesmo arquivo, mesma conversa

# WhatsApp / Telegram / Slack (gateway)
/session attach projeto-x        # o canal entra na mesma sessão

Cada superfície tem sua porta de entrada:

Superfície	Como vincular
REPL interativo	`/session attach <nome>` (`save` / `load` também vinculam)
ACP (prompt box da IDE)	`/session attach <nome>` — por sessão da IDE; veja ACP
Servidor MCP	actions `attach` / `detach` / `status` do `manage_session` (`save` / `load` também vinculam); veja MCP Server
Chat Gateway	envie `/session attach <nome>` no canal — binding por remetente (principal), persistido; veja Chat Gateway

Variável	Descrição	Padrão
`CHATCLI_SESSION_WRITETHROUGH`	Write-through ao vivo + adoção de escritas externas para a sessão nomeada ativa (desligado desativa as duas direções)	`true`

Sessões criadas por máquina (prefixos autosave-, mcp-) são espelhos rolling dos caminhos de autosave — elas nunca viram bindings vivos.

Last-writer-wins converge enquanto as superfícies alternam turnos. Duas superfícies respondendo o mesmo turno simultaneamente em tempo real continua sendo papel do Conversation Hub (efêmero, cross-channel); a sessão nomeada é o registro durável.

Onde as Sessões são Armazenadas

As sessões são salvas como arquivos JSON em um store por usuário — o mesmo store que todas as superfícies (REPL, servidor MCP/ACP, daemon do gateway) leem e escrevem:

~/.chatcli/sessions/<nome>.json

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

~/.chatcli/sessions/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 o store é por usuário (diretório home), as mesmas sessões ficam visíveis não importa de qual diretório você inicie o ChatCLI — e todas as superfícies (terminal, IDE, cliente MCP, canal do gateway) veem a mesma lista. Use /session list para vê-las todas.

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

Além do /session save explícito, a persistência tem duas camadas automáticas:

Sessão nomeada vinculada — após /session save, /session load ou /session attach, cada turno é gravado (write-through) no arquivo da sessão (veja Continuidade cross-surface; gate CHATCLI_SESSION_WRITETHROUGH, on por padrão).
Autosave no exit — uma conversa sem vínculo ainda é salva como autosave-YYYYMMDD-HHMMSS quando o REPL interativo encerra (veja Salvamento automático no exit acima; gate CHATCLI_SESSION_AUTOSAVE, on por padrão).

Salve com um nome escolhido por você sempre que a conversa importar: sessões nomeadas pelo usuário nunca expiram, enquanto autosaves ficam sujeitos à Limpeza Automática abaixo.

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/sessions/*.json)

Aspecto	Sessões (`~/.chatcli/sessions/*.json`)	Histórico de comandos (`.chatcli_history`)
Conteúdo	Conversa completa (user + assistant + tool)	Apenas o que você digitou
Salvamento	`/session save`, ou automático a cada turno enquanto vinculada (write-through)	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 aplica um ciclo de vida limitado às sessões criadas por máquina na inicialização (REPL e servidor MCP/ACP). A regra central: sessões que você nomeou nunca são apagadas automaticamente — só os arquivos com prefixo autosave- e mcp- que o ChatCLI cria sozinho ficam sujeitos à retenção.

Variável	Descrição	Padrão
`CHATCLI_SESSION_TTL`	Tempo de vida máximo das sessões de máquina, em dias (`0` desabilita a expiração)	`90d` (90 dias — 3× a retenção padrão de transcripts do Claude Code)
`CHATCLI_SESSION_AUTOSAVE_KEEP`	Backstop de contagem por prefixo de máquina (as mais novas sobrevivem, por mtime)	`600`

O tempo é a retenção primária: sessões de máquina sem modificação dentro do TTL são removidas em background na inicialização. A contagem é um backstop generoso contra acúmulo patológico, não o limite de trabalho. E nada destilado se perde: fatos, episódios e rollups extraídos de uma sessão são permanentes e sobrevivem à limpeza — o prune limita disco e custo de busca, não conhecimento.

export CHATCLI_SESSION_TTL=30d   # Expirar sessões de máquina com mais de 30 dias
chatcli

Use CHATCLI_SESSION_TTL=0 para desabilitar a limpeza automática e manter todas as sessões indefinidamente. Para tornar uma conversa imortal independente de política, basta salvá-la com nome: /session save meu-checkpoint.

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 em ~/.chatcli/sessions. Para transferir uma sessão entre máquinas, copie o arquivo ~/.chatcli/sessions/<nome>.json para o mesmo local 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?

Não — o store é por usuário. As sessões vivem em ~/.chatcli/sessions, então os mesmos nomes ficam visíveis de qualquer diretório e de qualquer superfície (REPL, servidor MCP/ACP, gateway). Esse namespace compartilhado é exatamente o que faz a continuidade cross-surface funcionar; use nomes específicos da tarefa (projeto-a-debug, projeto-b-debug) para separar projetos.

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.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Gerenciamento de Sessões

Comandos de Sessão

Salvamento automático no exit

Continuidade cross-surface

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

​Salvamento automático no exit

​Continuidade cross-surface

​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

Salvamento automático no exit

Continuidade cross-surface

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