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

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

***

## Comandos de Sessão

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

<Steps>
  <Step title="/session save <nome>">
    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.
    ```

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

  <Step title="/session load <nome>">
    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.
    ```
  </Step>

  <Step title="/session list">
    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
    ```
  </Step>

  <Step title="/session delete <nome>">
    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.
    ```

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

  <Step title="/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.

    ```bash theme={"system"}
    /session new
    ```

    ```text theme={"system"}
    Nova sessão de conversa iniciada; histórico foi limpo.
    ```
  </Step>

  <Step title="/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.

    ```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.
    ╰──────────────────────────────────────────────
    ```

    <Tip>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.</Tip>
  </Step>
</Steps>

***

## 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 é:

```text theme={"system"}
.chatcli_session_<nome>.json
```

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

```text theme={"system"}
.chatcli_session_debug-api.json
```

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

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

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

***

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

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

***

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

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

***

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

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

***

## Auto-Save e Persistência

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

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:

<Steps>
  <Step title="Nomeie sessões pela tarefa">
    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
    ```
  </Step>

  <Step title="Compacte antes de salvar">
    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
    ```
  </Step>

  <Step title="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.

    ```bash theme={"system"}
    /session new
    /session load refactor-api
    ```
  </Step>

  <Step title="Alterne entre tarefas livremente">
    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
    ```
  </Step>
</Steps>

***

## 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
```

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

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

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

***

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

```bash theme={"system"}
export CHATCLI_SESSION_TTL=30d   # Limpar sessões com mais de 30 dias
chatcli
```

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

***

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>
</AccordionGroup>

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Controle de Conversa" icon="clock-rotate-left" href="/pt/features/conversation-control">
    Use /compact e /rewind para gerenciar o tamanho e estado do histórico.
  </Card>

  <Card title="Contexto Persistente" icon="database" href="/pt/features/persistent-context">
    Salve, anexe e reutilize snapshots de projetos com o comando /context.
  </Card>

  <Card title="Bootstrap e Memória" icon="memory" href="/pt/features/bootstrap-memory">
    Personalize a IA e mantenha contexto de longo prazo.
  </Card>

  <Card title="Modo One-Shot" icon="terminal" href="/pt/features/non-interactive-mode">
    Use o ChatCLI em scripts, automações e pipelines de CI/CD.
  </Card>
</CardGroup>

***