Skip to main content

​
Sessions

Atomic saves conversations as sessions so you can continue work, branch from earlier turns, and revisit previous paths.

​
Session Storage

Sessions auto-save to ~/.atomic/agent/sessions/, organized by working directory. Each session is a JSONL file with a tree structure.
Use /session in interactive mode to see the current session file, session ID, message count, tokens, and cost.

​
Custom session directories

Use --session-dir <dir>, ATOMIC_CODING_AGENT_SESSION_DIR, or the matching settings override to save the active chat session outside the default ~/.atomic/agent/sessions/ store. When a workflow runs from a session that uses one of these non-default directories, Atomic also writes workflow stage transcripts to that same directory so a headless command such as atomic --mode json --session-dir <dir> -p '/workflow <name> ...' captures the main transcript and all stage transcripts together. Workflow definitions can still set a per-stage sessionDir; that explicit stage directory wins over the inherited host directory. If the host session uses the default session store, workflow stages keep the previous default behavior and write to the global store unless a stage explicitly sets sessionDir. For the JSONL file format and SessionManager API, see Session Format.

​
Session Commands

​
Resuming and Deleting Sessions

/resume opens an interactive session picker for the current project. atomic -r opens the same picker at startup. When Atomic reconstructs a resumed session, the latest active verbatim compaction entry supplies a durable compacted transcript string followed by the exact original kept tail. A zero-retention boundary stores firstKeptEntryId: null and replays no pre-boundary ordinary message. Resume does not rerun a planner or re-derive omissions. Legacy logical-deletion context_compaction entries are inert archival records, so previously hidden content can re-enter context in sessions created by older versions. In the picker you can:
  • search by typing
  • toggle path display with CTRL+P
  • toggle sort mode with CTRL+S
  • filter to named sessions with CTRL+N
  • rename with CTRL+R
  • delete with CTRL+D, then confirm
When available, Atomic uses the trash CLI for deletion instead of permanently removing files. The picker opens instantly: its header, search field, and loading indicator paint on the first frame, then sessions are discovered and parsed off the terminal’s UI loop. Large session directories are scanned in cooperative batches and a single very large transcript is parsed in yielding chunks, so search, navigation, and cancel stay responsive and no individual session can freeze the picker while it loads. Closing the picker cancels any in-flight scan and discards stale results, so a slow load that finishes after you leave never updates the list.

​
Internal (workflow) sessions

Sessions created by workflow stage execution are marked as internal and are excluded from the standard /resume, atomic -r, and --continue history by default. This keeps the resume picker focused on your interactive coding sessions. Workflow stage sessions remain fully discoverable and resumable through the workflow-specific path: use /workflow resume <runId> (or the workflow tool’s resume/status actions) to inspect and continue a workflow run and its stages. A workflow stage session can still be opened directly by passing its file path to --session. Legacy workflow sessions created before this behavior lack the internal marker and will continue to appear in the standard history until they age out or are deleted.

​
Naming Sessions

Use /name <name> to set a human-readable session name:
Set the name at startup with --name or -n:
Named sessions are easier to find in /resume and atomic -r.

​
Branching with /tree

Sessions are stored as trees. Every entry has an id and parentId, and the current position is the active leaf. /tree lets you jump to any previous point and continue from there without creating a new file.

Tree View

Example shape:

​
Tree Controls

Filter modes are: default, no-tools, user-only, labeled-only, and all. Configure the default with treeFilterMode in Settings.

​
Selection Behavior

Selecting a user or custom message:
  1. Moves the leaf to the selected message’s parent.
  2. Places the selected message text in the editor.
  3. Lets you edit and resubmit, creating a new branch.
Selecting an assistant, tool, compaction, or other non-user entry:
  1. Moves the leaf to that entry.
  2. Leaves the editor empty.
  3. Lets you continue from that point.
Selecting the root user message resets the leaf to an empty conversation and places the original prompt in the editor.

​
/tree, /fork, and /clone

Use /tree when you want to keep alternatives together. Use /fork or /clone when you want a separate session file.

​
Branch Summaries

When /tree switches away from one branch to another, Atomic can summarize the abandoned branch and attach that summary at the new position. This preserves important context from the path you left without replaying the whole branch. When prompted, choose one of:
  1. no summary
  2. summarize with the default prompt
  3. summarize with custom focus instructions
Branch summaries are separate from /compact: branch navigation can generate summary prose (optionally with focus instructions), while Verbatim Compaction lets a model select numbered line ranges and reconstructs retained text mechanically. See Compaction for Verbatim Compaction, branch summarization internals, and extension hooks.

​
Session Format

Session files are JSONL and contain message entries, model changes, thinking-level changes, context-window changes, labels, active verbatim compaction boundaries, branch summaries, and extension entries. Retired context_compaction and non-verbatim compaction records remain parseable but inert. For parsers, extensions, SDK usage, and the full SessionManager API, see Session Format.