Session Management

Working on multiple projects or tasks can be challenging, especially when each one has a different conversation context. ChatCLI solves this with a simple and powerful session management system. A session is essentially a complete “save” of your conversation history, allowing you to resume exactly where you left off.

ChatCLI uses a unified history — a single message array shared across all modes (chat, agent, coder). When saving a session, the entire context is preserved regardless of the mode in which it was generated. Use /compact to reduce size and /rewind to go back to earlier points.

Session Commands

All session management commands start with /session.

/session save <name>

Saves the current conversation (the entire history of prompts and responses) with a name of your choice.

/session save debug-api-pagamentos

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

After saving, the session name will appear in your prompt (e.g., debug-api-pagamentos), indicating that you are working within that session.

/session load <name>

Loads a previously saved session. The current conversation is replaced by the loaded session’s history.

/session load documentação-site

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

/session list

Lists all sessions you have saved to disk.

/session list

Sessões salvas:

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

/session delete <name>

Permanently removes a saved session from disk. This action cannot be undone.

/session delete refatoração-legado

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

If you delete the currently active session, your current history will be cleared and you will start a new conversation.

/session new (or /newsession)

Clears the current history and starts a completely new conversation. Perfect for starting a task from scratch without being tied to any named session.

/session new

New conversation session started; history has been cleared.

/session fork <new-name>

Creates an independent copy of the current session with a new name. The original remains untouched and you automatically switch to working on the fork.Ideal for experimenting with different approaches without losing current progress, or branching a conversation in different directions.

/session fork experiment-v2

╭── ✅ Session forked!
│    From:  my-session
│    To:    experiment-v2
│    Messages: 42
│    Now working on the fork. Original remains intact.
╰──────────────────────────────────────────────

Works with both saved and unsaved (in-memory) sessions. For unsaved sessions, the fork is created from the current history state.

Where Sessions Are Stored

Sessions are saved as JSON files in the current working directory (CWD) — that is, the directory from which you launched ChatCLI. The file naming pattern is:

.chatcli_session_<name>.json

For example, running /session save debug-api creates the file:

.chatcli_session_debug-api.json

The SessionManager is the internal component responsible for all session file I/O. It handles read/write errors (permissions, full disk, malformed JSON) and displays clear messages if something fails.

Session files contain the complete conversation history at the time of saving — including user messages, AI responses, tool call results, and summaries generated by /compact.

Since files are stored in the CWD, starting ChatCLI from different directories will show different sessions. Use /session list to check which sessions are available in the current directory.

Data Format (v2)

Session files use the v2 format, defined by the SessionData struct in the models package. The JSON structure is:

{
  "version": 2,
  "chat_history": [
    {
      "role": "user",
      "content": "Explain the Repository pattern",
      "meta": {
        "is_summary": false,
        "summary_of": 0,
        "mode": "chat"
      },
      "tool_calls": null,
      "tool_call_id": ""
    },
    {
      "role": "assistant",
      "content": "The Repository pattern is...",
      "meta": {
        "is_summary": false,
        "summary_of": 0,
        "mode": "chat"
      },
      "tool_calls": null,
      "tool_call_id": ""
    }
  ],
  "agent_history": [],
  "coder_history": [],
  "shared_memory": []
}

Message Fields

Field	Type	Description
`role`	string	`"user"`, `"assistant"`, `"system"`, or `"tool"`
`content`	string	Text content of the message
`meta.is_summary`	bool	`true` if the message is a summary generated by `/compact`
`meta.summary_of`	int	Number of original messages this summary represents
`meta.mode`	string	Mode in which the message was generated (`"chat"`, `"agent"`, `"coder"`)
`tool_calls`	array/null	List of tool calls (agent/coder mode)
`tool_call_id`	string	ID of the tool call this message responds to (for `role: "tool"` messages)

Format Evolution

v1 (older versions): Maintained separate histories per mode — chat_history, agent_history, and coder_history each with their own messages.
v2 (current version): Uses a unified history. The chat_history field contains all messages from all modes. The agent_history and coder_history fields exist for compatibility but are empty in new sessions.

When loading a v1 session (with separate per-mode histories), ChatCLI automatically merges the messages in chronological order into the unified history. No manual intervention is required.

Unified History and Sessions

ChatCLI uses a single message array for all interaction modes. This means:

When saving a session, the entire unified history is serialized — including messages from chat, agent, and coder mode.
System messages, tool call results, and compacted summaries are all preserved in the file.
When loading a session, the current history is completely replaced by the loaded session’s history.

The active session name appears as a prefix in the interactive prompt:

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

This makes it easy to know which context you are working in at any time.

Loading a session replaces the entire current history. If you have an unsaved conversation, it will be lost. Save first with /session save if you want to preserve it.

Interaction with Other Systems

Sessions interact with several other ChatCLI subsystems. Here is how each one behaves:

Compaction (`/compact`)

The /compact command reduces history size by creating summaries of older messages. If you save a session after compacting, the resulting file will be significantly smaller, as it contains summaries instead of the original messages.

Rewind (`/rewind`)

The checkpoints used by /rewind exist only in memory during the current run. They are not saved in the session file. When loading a session, you will not have rewind points available until you create new ones during the conversation.

Bootstrap (SOUL.md, etc.)

Bootstrap files are not part of the session. They are loaded automatically on every ChatCLI startup, regardless of which session is active. This ensures that the AI’s base behavior is always consistent.

Memory (`/memory`)

Memory is global — it is not tied to any specific session. Data saved with /memory save is available across all sessions and survives ChatCLI restarts.

Context (`/context attach`)

Contexts attached via /context attach are not saved in the session file. When loading a session, you need to re-attach the necessary contexts manually.

Quick summary: Sessions only save the message history. Bootstrap, memory, contexts, and rewind checkpoints are managed separately.

Auto-Save and Persistence

Sessions are not auto-saved. You must explicitly call /session save to persist the conversation to disk.

If you close ChatCLI without saving, the conversation history will be permanently lost. There is no automatic recovery mechanism.

The `.chatcli_history` File (Don’t Confuse)

ChatCLI maintains a separate file called .chatcli_history that stores the command input history (similar to ~/.bash_history). This file:

Contains only the text you typed at the prompt, not the AI’s responses
Is controlled by the HISTORY_FILE and HISTORY_MAX_SIZE environment variables
Has no relation to session files (.chatcli_session_*.json)

Aspect	Sessions (`.chatcli_session_*.json`)	Command History (`.chatcli_history`)
Content	Complete conversation (user + assistant + tool)	Only what you typed
Saving	Manual (`/session save`)	Automatic
Format	Structured JSON (v2)	Plain text, one line per command
Control	`/session` commands	`HISTORY_FILE`, `HISTORY_MAX_SIZE` variables

Recommended Workflow

To get the most out of the session system, follow these practices:

Name sessions after the task

Use descriptive names that clearly identify the objective. Examples: fix-auth-bug, refactor-api, docs-v2, debug-memory-leak.

/session save fix-auth-bug

Compact before saving

Use /compact before /session save to reduce file size and keep only the essential information.

/compact
/session save fix-auth-bug

Start clean before switching sessions

Use /session new before loading another session. This ensures the previous context doesn’t interfere.

/session new
/session load refactor-api

Switch between tasks freely

You can have multiple sessions saved for different tasks and switch between them as needed.

/session save fix-auth-bug      # save current work
/session load refactor-api      # load another task
# ... work on the refactoring ...
/session save refactor-api      # save progress
/session load fix-auth-bug      # go back to the bug

Session Encryption

Session files can be encrypted at rest using AES-256-GCM to protect sensitive conversation data:

Variable	Description	Default
`CHATCLI_ENCRYPTION_KEY`	Encryption key (32 bytes, base64-encoded)	`""` (disabled)

When configured, all session operations (save/load) use transparent encryption:

# Generate a secure key
export CHATCLI_ENCRYPTION_KEY=$(openssl rand -base64 32)

# Save and load sessions normally - encryption is transparent
/session save my-secure-session
/session load my-secure-session

Key derivation uses HKDF (HMAC-based Key Derivation Function) to generate unique per-session keys from the master key. This ensures that compromising one session does not compromise others.

Transparent migration: Existing plaintext sessions are automatically encrypted when loaded and saved again. No manual action is needed to migrate old sessions.

Store the encryption key in a secure location. If the key is lost, encrypted sessions cannot be recovered.

Automatic Cleanup

ChatCLI can automatically remove old sessions on startup:

Variable	Description	Default
`CHATCLI_SESSION_TTL`	Maximum session lifetime	`90d` (90 days)

Sessions that have not been modified within the period defined by CHATCLI_SESSION_TTL are automatically removed when ChatCLI starts. This prevents indefinite accumulation of old sessions on disk.

export CHATCLI_SESSION_TTL=30d   # Clean sessions older than 30 days
chatcli

Use CHATCLI_SESSION_TTL=0 to disable automatic cleanup and keep all sessions indefinitely.

Name Validation

Session names are validated with a strict regex to prevent path traversal and problematic characters:

Allowed characters: letters (a-z, A-Z), numbers (0-9), hyphens (-), underscores (_), and dots (.)
Length: 1 to 128 characters
Forbidden: spaces, slashes, special characters, .. sequences

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

Invalid names are rejected with a clear error message indicating the allowed characters.

Frequently Asked Questions

Are sessions shared between machines?

No. Session files are stored locally in the current working directory. To transfer a session between machines, you would need to manually copy the .chatcli_session_<name>.json file to the same directory on the other machine.

Is there a size limit for sessions?

Technically, the limit is defined by the HISTORY_MAX_SIZE variable (default: 100MB), but in practice sessions rarely exceed a few megabytes. If the history is too large, use /compact before saving to significantly reduce the size.

Can I manually edit the session JSON file?

Yes, but with care. The file follows the v2 format described above. You can remove messages, edit content, or adjust metadata. Make sure to keep the JSON valid and the structure intact (especially the version field).

What happens if I load a session from an older version?

ChatCLI automatically detects sessions in the v1 format (with separate per-mode histories) and performs an automatic migration to v2, merging all messages in chronological order into the unified history. The process is transparent and requires no action from the user.

Can I have sessions with the same name in different directories?

Yes. Since files are saved in the CWD, each directory has its own session namespace. A session called debug in /project-a is completely independent from a session called debug in /project-b.

Next Steps

Conversation Control

Use /compact and /rewind to manage history size and state.

Persistent Context

Save, attach, and reuse project snapshots with the /context command.

Bootstrap and Memory

Customize the AI and maintain long-term context.

One-Shot Mode

Use ChatCLI in scripts, automations, and CI/CD pipelines.

​Session Commands

​Where Sessions Are Stored

​Data Format (v2)

​Message Fields

​Format Evolution

​Unified History and Sessions

​Interaction with Other Systems

​Compaction (/compact)

​Rewind (/rewind)

​Bootstrap (SOUL.md, etc.)

​Memory (/memory)

​Context (/context attach)

​Auto-Save and Persistence

​The .chatcli_history File (Don’t Confuse)

​Recommended Workflow

​Session Encryption

​Automatic Cleanup

​Name Validation

​Frequently Asked Questions

​Next Steps

Conversation Control

Persistent Context

Bootstrap and Memory

One-Shot Mode

Session Commands

Where Sessions Are Stored

Data Format (v2)

Message Fields

Format Evolution

Unified History and Sessions

Interaction with Other Systems

Compaction (`/compact`)

Rewind (`/rewind`)

Bootstrap (SOUL.md, etc.)

Memory (`/memory`)

Context (`/context attach`)

Auto-Save and Persistence

The `.chatcli_history` File (Don’t Confuse)

Recommended Workflow

Session Encryption

Automatic Cleanup

Name Validation

Frequently Asked Questions

Next Steps