> ## Documentation Index > Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt > Use this file to discover all available pages before exploring further. # Gerenciamento de Sessões > Aprenda a salvar, carregar e gerenciar múltiplas sessões de conversa para organizar seu trabalho e manter o histórico de diferentes tarefas. 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`. Salva a conversa atual (todo o histórico de prompts e respostas) com um nome de sua escolha. ```bash theme={"system"} /session save debug-api-pagamentos ``` ```text theme={"system"} 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. Carrega uma sessão salva anteriormente. A conversa atual é substituída pelo histórico da sessão carregada. ```bash theme={"system"} /session load documentação-site ``` ```text theme={"system"} Sessão 'documentação-site' carregada. A conversa anterior foi restaurada. ``` Carregar também rotaciona a thread compartilhada do [Conversation Hub](/pt/gateway/conversation-hub), para que o backlog cross-channel antigo não seja emendado por cima da sessão carregada. 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](#continuidade-cross-surface). ```bash theme={"system"} /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. 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. ```bash theme={"system"} /session detach ``` Mostra se a conversa está vinculada a uma sessão nomeada, e a qual. ```bash theme={"system"} /session status ``` Lista todas as sessões que você salvou no disco. ```bash theme={"system"} /session list ``` ```text theme={"system"} Sessões salvas: - debug-api-pagamentos - documentação-site - refatoração-legado ``` Remove permanentemente uma sessão salva do disco. Esta ação não pode ser desfeita. ```bash theme={"system"} /session delete refatoração-legado ``` ```text theme={"system"} 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. 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. ```bash theme={"system"} /session new ``` ```text theme={"system"} Nova sessão de conversa iniciada; histórico foi limpo. ``` 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. O fork é uma linha do tempo própria: ganha um journal de transcript novo semeado com os eventos do pai (os dois nunca escrevem no mesmo journal, então `/rewind` e undo ficam por sessão) e mantém os anexos, a referência de custo e as chaves do arquivo CCR. Um arquivo de sessão gravado por um ChatCLI mais novo (schema de versão maior) é recusado no load em vez de ser reescrito silenciosamente sem os campos que este build não conhece. Ideal para experimentar abordagens diferentes sem perder o progresso atual, ou para ramificar uma conversa em direções distintas. ```bash theme={"system"} /session fork experimento-v2 ``` ```text theme={"system"} ╭── ✅ 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. Exporta o **transcript completo** — o journal, não a janela compactada — como documento Markdown (uma seção por mensagem, tool calls e results em blocos de código, system prompts colapsados) ou como JSON Lines (um turno por linha, o mesmo formato do `@trajectory`). Cai para o histórico vivo quando o journal está desligado. ```bash theme={"system"} /session export md ~/reviews/refatoracao-parser.md /session export jsonl ``` ```text theme={"system"} Exportadas 41 entradas para /Users/dev/chatcli-minha-sessao-20260903-181200.md (fonte: journal). ``` Sem caminho o arquivo vai para o diretório de trabalho como `chatcli--.`, modo 0600. Opera no mesmo registro completo: * `search ` ranqueia toda mensagem do journal com BM25 e imprime os melhores resultados com a posição — `#17 assistant …o freeze de deploy termina sexta…`. * `show [qtd]` reproduz mensagens a partir de uma posição (10 por padrão), para ler um resultado em contexto. * `export [caminho]` é o mesmo que `/session export`. * `stats` imprime contagem de mensagens, tamanho, fonte (journal ou histórico vivo) e id do journal. ```bash theme={"system"} /session transcript search freeze deploy /session transcript show 17 5 ``` *** ## 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. Um REPL vinculado a uma sessão nomeada (carregada ou salva via `/session`, ou a sessão `web-` que o `/web` cria) já é gravado após cada turno: na saída ele é gravado uma última vez e **nenhuma** cópia `autosave-` é feita, então o catálogo não carrega a mesma conversa duas vezes. 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`](/pt/context/session-search). **Sessões MCP também têm autosave**: o servidor MCP/ACP espelha cada conversa viva num arquivo rolling `mcp-` 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](/pt/gateway/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**). ```bash theme={"system"} # 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 ` (`save` / `load` também vinculam) | | ACP (prompt box da IDE) | `/session attach ` — por sessão da IDE; veja [ACP](/pt/server/acp) | | Servidor MCP | actions `attach` / `detach` / `status` do `manage_session` (`save` / `load` também vinculam); veja [MCP Server](/pt/server/mcp-server) | | Chat Gateway | envie `/session attach ` no canal — binding por remetente (principal), persistido; veja [Chat Gateway](/pt/gateway/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](/pt/gateway/conversation-hub) (efêmero, cross-channel); a sessão nomeada é o registro durável. *** ## Journal de transcript Uma sessão salva persiste a conversa **como está em memória** — depois de uma compactação a janela guarda um resumo, e as mensagens originais sobrevivem só como chaves `@recall` no CCR (TTL de 7 dias, limite de tamanho). O journal de transcript é o registro completo e durável por baixo dessa janela: * `~/.chatcli/transcripts/.jsonl`, um arquivo por sessão, append-only, cada linha com fsync. * Cada mensagem é anexada **uma vez**, na primeira vez em que aparece na cauda do histórico vivo — no fim de cada turno do chat, no início de cada turno do agent/coder (assim os tool results do turno anterior estão em disco antes de qualquer reescrita virar stub) e quando uma execução do agente termina, seja como for. Um kill duro no meio da execução perde no máximo o lote de tools em voo. * Uma reescrita do histórico (auto-compact, `/compact`, microcompact, envelhecimento de skills, dedup de leituras) vira um evento `rewrite` carregando os **hashes ordenados do histórico que substituiu**; só mensagens genuinamente novas (o resumo) são anexadas, nada é duplicado. São esses hashes que `/rewind compact` e os checkpoints persistidos de `/rewind` resolvem depois de uma retomada. * O journal é legível, não só de escrita: `/session export` e `/session transcript search|show|stats` operam direto nele. * Cada sync compara o histórico **inteiro** com os últimos hashes registrados, então uma mensagem alterada no lugar (microcompact, dedup de leituras, reparo de pareamento de tool results, trim de Nível 1) também vira reescrita — `/rewind compact` e checkpoints persistidos continuam resolvendo em sessões de agente. Os hashes cobrem tool calls nativas (id, nome, argumentos) e imagens, e mensagens repetidas no fim ("ok") são registradas como as mensagens distintas que são. * O leitor tolera dano: uma última linha parcial de um crash e qualquer linha estranha são puladas e contadas, nunca fatais; o próximo append começa em linha nova. Uma linha selada que este processo não consegue abrir continua sendo erro, porque isso é problema de chave, não corrupção. * Sessões salvas carregam seu `transcript_id`, então `/session load` e `/session attach` continuam escrevendo no mesmo journal entre retomadas. * Sessões salvas também carregam seus **registros de `/context attach`** (`attachments`: id do contexto, prioridade, chunks selecionados, modo de retrieval). O estado de anexo era só do processo — um restart ou um load em outra superfície perdia todos os contextos anexados; carregar uma sessão agora reanexa os mesmos contextos, pulando os que não existem mais. * Com `CHATCLI_ENCRYPTION_KEY` definida, cada linha é selada (mesmo formato AES-256-GCM das sessões) e o journal não é legível sem a chave. * Os journals seguem o TTL das sessões de máquina (`CHATCLI_SESSION_TTL`, 90 dias por padrão). `CHATCLI_SESSION_TRANSCRIPT=false` desliga o journal; `/config session` mostra o id ativo. ## 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: ```text theme={"system"} ~/.chatcli/sessions/.json ``` Por exemplo, ao executar `/session save debug-api`, o arquivo criado será: ```text theme={"system"} ~/.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 é: ```json theme={"system"} { "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: ```text theme={"system"} [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` são salvos com a sessão como listas ordenadas de hash de mensagens (`checkpoints`) e reconstruídos do journal de transcript no `/session load`; um checkpoint cujas mensagens o journal não tem mais é descartado. `/rewind compact` (desfazer a última compactação) também é apoiado pelo journal depois de retomar. Com o journal desligado, os checkpoints ficam locais ao processo como antes. ### 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](#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: Use nomes descritivos que identifiquem claramente o objetivo. Exemplos: `fix-auth-bug`, `refactor-api`, `docs-v2`, `debug-memory-leak`. ```bash theme={"system"} /session save fix-auth-bug ``` Use `/compact` antes de `/session save` para reduzir o tamanho do arquivo e manter apenas as informações essenciais. ```bash theme={"system"} /compact /session save fix-auth-bug ``` Use `/session new` antes de carregar outra sessão. Isso garante que o contexto anterior não interfira. ```bash theme={"system"} /session new /session load refactor-api ``` Você pode ter múltiplas sessões salvas para diferentes tarefas e alternar entre elas conforme necessário. ```bash theme={"system"} /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: ```bash theme={"system"} # 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. ```bash theme={"system"} 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`. ### Curadoria do armazenamento sob demanda A passada de inicialização é silenciosa. O `/storage` torna as mesmas políticas visíveis: uma linha por store local com contagem de arquivos, tamanho, a regra que o governa e o que seria removido agora, mais os stores que nunca são podados (memória destilada, skills, plugins, contextos, agentes, comandos, scheduler, tokenizers, logs). `/storage prune` lista o que as regras removeriam, agrupado por motivo — além da TTL, órfão, rajada de teste, temporário perdido — e só `/storage prune --apply` remove; `/storage prune costs --apply` restringe a um store. Duas regras existem só sob demanda porque uma passada de boot não deve chutar: snapshots de custo criados em rajada (quatro ou mais sessões no mesmo minuto com no máximo duas requisições cada) e as varreduras do CCR e do hub, que abrem os próprios stores. Os checkpoints do coder entraram na passada de inicialização: um repositório sombra cujo workspace é um diretório temporário ou não existe mais é removido no boot, os demais seguem a TTL de sessão. `chatcli storage prune --apply` é a mesma coisa sem REPL, para cron — ou agende de dentro com `/schedule`, que roda comandos slash. *** ## 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 `..` ```text theme={"system"} 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 **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/.json` para o mesmo local na outra máquina. 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. **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 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. **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 Use /compact e /rewind para gerenciar o tamanho e estado do histórico. Salve, anexe e reutilize snapshots de projetos com o comando /context. Personalize a IA e mantenha contexto de longo prazo. Use o ChatCLI em scripts, automações e pipelines de CI/CD. *** This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.