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.

Loading also rotates the shared Conversation Hub thread, so the old cross-channel backlog is not spliced on top of the loaded session.

/session attach <name>

Binds the conversation to a named session — loads it when it exists, creates it when it doesn’t. While attached, every turn is written through to the session file and writes made by other surfaces are adopted before each turn — see Cross-surface continuity.

/session attach projeto-x

/session save and /session load also bind: after either one, the conversation is attached to that name. attach is the alias that works whether or not the session exists yet.

/session detach

Keeps the current conversation in memory but drops the binding: turns stop being written through to the named session file.

/session detach

/session status

Shows whether the conversation is bound to a named session, and to which one.

/session status

/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. Same semantics as /newsession: it also drops any session binding and rotates the shared hub thread, so no backlog from the old conversation leaks into the new one.

/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. The fork is its own timeline: it gets a fresh transcript journal seeded with the parent’s events (the two never append to one journal, so /rewind and undo stay per session) and keeps the attachments, the cost reference and the CCR archive keys. A session file written by a newer ChatCLI (higher schema version) is refused on load instead of being silently rewritten minus the fields this build does not know.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.

/session export <md|jsonl> [path]

Exports the full transcript — the journal, not the compacted window — as a Markdown document (one section per message, tool calls and results in fenced blocks, system prompts collapsed) or as JSON Lines (one turn per line, the same format @trajectory uses). Falls back to the live history when the journal is off.

/session export md ~/reviews/parser-refactor.md
/session export jsonl

Exported 41 entries to /Users/dev/chatcli-my-session-20260903-181200.md (source: journal).

Without a path the file lands in the working directory as chatcli-<session>-<timestamp>.<ext>, mode 0600.

/session transcript <search|show|export|stats>

Works on the same full record:

search <query> ranks every journaled message with BM25 and prints the top hits with their position — #17 assistant …the deploy freeze ends on Friday….
show <from> [count] replays messages from a position (default 10), so a hit can be read in context.
export <md|jsonl> [path] is the same as /session export.
stats prints the message count, size, source (journal or live history) and journal id.

/session transcript search deploy freeze
/session transcript show 17 5

Automatic saving on exit

You don’t have to remember /session save: when the interactive REPL exits, the conversation is auto-saved under a reserved autosave-YYYYMMDD-HHMMSS name. Trivial sessions (fewer than 2 non-system messages) are skipped, and one-shot -p runs never autosave. Gated by CHATCLI_SESSION_AUTOSAVE (on by default, shown in /config session). Autosaved conversations are fully searchable and readable via @session. MCP sessions autosave too: the MCP/ACP server mirrors each live conversation to a rolling mcp-<session> file after every turn (both the full-pipeline and plain paths), and manage_session clear saves one last time before discarding. An explicit CHATCLI_MCP_SESSION_AUTOSAVE always wins; unset, it follows the global CHATCLI_SESSION_AUTOSAVE gate — on by default. Retention for both surfaces is covered under Automatic Cleanup below.

Cross-surface continuity

A named session is ChatCLI’s durable continuity layer across surfaces: the interactive REPL, the MCP server (chatcli mcp-server), the ACP server (chatcli acp) and the Chat Gateway all read and write the same session file. Start on the terminal, continue in the IDE, finish on WhatsApp — same conversation. While a named session is active (after /session save, /session load or /session attach), the binding works in both directions on every turn:

Write-through — each completed turn is written to the session file immediately (atomic write: temp file + rename, so there are never torn files).
Adoption — before each turn, writes made by other surfaces (MCP/ACP server, gateway daemon, another terminal) since the last sync are adopted: when the file is newer, it replaces the in-memory history wholesale (last-writer-wins).

# Terminal
/session attach projeto-x        # binds (creates the session if it doesn't exist yet)

# IDE (ACP prompt box)
/session attach projeto-x        # same file, same conversation

# WhatsApp / Telegram / Slack (gateway)
/session attach projeto-x        # the channel joins the same session

Each surface has its own way in:

Surface	How to bind
Interactive REPL	`/session attach <name>` (`save` / `load` also bind)
ACP (IDE prompt box)	`/session attach <name>` — per IDE session; see ACP
MCP server	`manage_session` actions `attach` / `detach` / `status` (`save` / `load` also bind); see MCP Server
Chat Gateway	send `/session attach <name>` in the channel — binding per sender (principal), persisted; see Chat Gateway

Variable	Description	Default
`CHATCLI_SESSION_WRITETHROUGH`	Live write-through + adoption of external writes for the active named session (disables both directions when off)	`true`

Machine-created sessions (autosave-, mcp- prefixes) are rolling mirrors owned by the autosave paths — they never become live bindings.

Last-writer-wins converges as long as surfaces alternate turns. Two surfaces answering the same turn simultaneously in real time remains the Conversation Hub’s job (ephemeral, cross-channel); the named session is the durable record.

Transcript journal

A saved session persists the conversation as it stands in memory — after a compaction the window holds a summary, and the original messages survive only as @recall keys in the CCR store (7-day TTL, size-capped). The transcript journal is the durable full record underneath that window:

~/.chatcli/transcripts/<id>.jsonl, one file per session, append-only, every line fsynced.
Every message is appended once, the first time it appears at the tail of the live history — at each chat turn end, at the start of every agent/coder turn (so the previous turn’s tool results are on disk before any rewrite can stub them) and when an agent run exits, however it exits. A hard kill mid-run loses at most the tool batch in flight.
A history rewrite (auto-compact, /compact, microcompact, skill aging, repeated-read dedup) is recorded as a rewrite event carrying the ordered hashes of the history it replaced; only genuinely new messages (the summary) are appended, nothing is duplicated. Those hashes are what /rewind compact and persisted /rewind checkpoints resolve after a resume.
The journal is readable, not write-only: /session export and /session transcript search|show|stats work on it directly.
Every sync compares the whole history against the last journaled hashes, so a message changed in place (microcompact, read dedup, tool-result pairing repair, Level 1 trim) is recorded as a rewrite too — /rewind compact and persisted checkpoints keep resolving in agent sessions. Hashes cover native tool calls (id, name, arguments) and images, and repeated tail messages (“ok”) are recorded as the separate messages they are.
The reader tolerates damage: a partial last line from a crash and any foreign line are skipped and counted, never fatal; the next append starts on a fresh line. A sealed line this process cannot open is still an error, because that is a key problem rather than corruption.
Saved sessions carry their transcript_id, so /session load and /session attach keep writing to the same journal across resumes.
Saved sessions also carry their /context attach records (attachments: context id, priority, selected chunks, retrieval mode). Attach state used to be process-local — a restart or a load on another surface lost every attached context; loading a session now re-attaches the same contexts, skipping any that no longer exist.
With CHATCLI_ENCRYPTION_KEY set, each line is sealed (same AES-256-GCM format as sessions) and the journal cannot be read without the key.
Journals follow the machine-session TTL (CHATCLI_SESSION_TTL, 90 days by default). CHATCLI_SESSION_TRANSCRIPT=false disables the journal; /config session shows the active id.

Where Sessions Are Stored

Sessions are saved as JSON files in a per-user store — the same store every surface (REPL, MCP/ACP server, gateway daemon) reads and writes:

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

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

~/.chatcli/sessions/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 the store is per-user (home directory), the same sessions are visible no matter which directory you launch ChatCLI from — and every surface (terminal, IDE, MCP client, gateway channel) sees the same list. Use /session list to see them all.

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 are saved with the session as ordered message-hash lists (checkpoints) and rebuilt from the transcript journal on /session load; a checkpoint whose messages the journal no longer holds is dropped. /rewind compact (undo the latest compaction) is also journal-backed after a resume. With the journal disabled, checkpoints are process-local as before.

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

Besides the explicit /session save, persistence has two automatic layers:

Bound named session — after /session save, /session load or /session attach, every turn is written through to the session file (see Cross-surface continuity; gated by CHATCLI_SESSION_WRITETHROUGH, on by default).
Exit autosave — an unbound conversation is still saved as autosave-YYYYMMDD-HHMMSS when the interactive REPL exits (see Automatic saving on exit; gated by CHATCLI_SESSION_AUTOSAVE, on by default).

Save under a name you chose whenever the conversation matters: user-named sessions never expire, while autosaves are subject to Automatic Cleanup.

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

Aspect	Sessions (`~/.chatcli/sessions/*.json`)	Command History (`.chatcli_history`)
Content	Complete conversation (user + assistant + tool)	Only what you typed
Saving	`/session save`, or automatic on every turn while bound (write-through)	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 applies a bounded lifecycle to machine-created sessions on startup (REPL and MCP/ACP server alike). The core rule: sessions you named are never deleted automatically — only the autosave- and mcp- prefixed files ChatCLI creates on its own are subject to retention.

Variable	Description	Default
`CHATCLI_SESSION_TTL`	Maximum machine-session lifetime, in days (`0` disables expiry)	`90d` (90 days — 3× Claude Code’s default transcript retention)
`CHATCLI_SESSION_AUTOSAVE_KEEP`	Keep-count backstop per machine prefix (newest survive, by mtime)	`600`

Time is the primary retention: machine sessions untouched for the TTL are removed in the background at startup. The keep-count is a generous backstop against pathological accumulation, not the working limit. And nothing distilled is ever lost: facts, episodes and rollups extracted from a session are permanent and survive its cleanup — pruning bounds disk and search cost, not knowledge.

export CHATCLI_SESSION_TTL=30d   # Expire machine sessions older than 30 days
chatcli

Use CHATCLI_SESSION_TTL=0 to disable automatic cleanup and keep all sessions indefinitely. To make one conversation immortal regardless of policy, just save it under a name: /session save my-checkpoint.

Curating storage on demand

The startup pass is silent. /storage makes the same policies visible: one line per local store with its file count, size, the rule that governs it and what would be removed right now, plus the stores that are never pruned (distilled memory, skills, plugins, contexts, agents, commands, scheduler, tokenizers, logs). /storage prune lists what the rules would remove, grouped by reason — past TTL, orphaned, test burst, stray temp file — and only /storage prune --apply removes it; /storage prune costs --apply scopes it to one store. Two rules exist only on demand because a boot pass must not guess: cost snapshots started in a burst (four or more sessions in one minute with at most two requests each), and the CCR and hub sweeps, which open their own stores. Coder checkpoints joined the startup pass: a shadow repository whose workspace is a temp directory or no longer exists is removed at boot, the rest follow the session TTL. chatcli storage prune --apply is the same thing without a REPL, for cron — or schedule it from inside with /schedule, which runs slash commands.

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 under ~/.chatcli/sessions. To transfer a session between machines, copy the ~/.chatcli/sessions/<name>.json file to the same location 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?

No — the store is per-user. Sessions live in ~/.chatcli/sessions, so the same names are visible from any directory and any surface (REPL, MCP/ACP server, gateway). That shared namespace is exactly what makes cross-surface continuity work; use task-specific names (projeto-a-debug, projeto-b-debug) to keep projects apart.

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.

Home

Getting Started

Core Concepts

Features

Security

Support

Session Management

Session Commands

Automatic saving on exit

Cross-surface continuity

Transcript journal

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

Curating storage on demand

Name Validation

Frequently Asked Questions

Next Steps

Conversation Control

Persistent Context

Bootstrap and Memory

One-Shot Mode

​Session Commands

​Automatic saving on exit

​Cross-surface continuity

​Transcript journal

​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

​Curating storage on demand

​Name Validation

​Frequently Asked Questions

​Next Steps

Conversation Control

Persistent Context

Bootstrap and Memory

One-Shot Mode

Session Commands

Automatic saving on exit

Cross-surface continuity

Transcript journal

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

Curating storage on demand

Name Validation

Frequently Asked Questions

Next Steps