Sessions

Inspect, resume, prune, fork, branch, compact, and export transcripts.

Every turn is appended to a JSONL transcript under $ZOT_HOME. Resume the last session with -c, pick one with -r, or browse them all from /sessions. Jump between past turns with /jump without editing history. Run /session to open the session actions picker.

Free up context without losing the thread with /compact, which summarizes the transcript into a single message and keeps the last few exchanges verbatim. In interactive mode, zot also auto-compacts when context usage reaches the threshold selected under /settings: off, 70%, 80%, 85% (default), or 90% of the model's advertised context window. Turning the threshold off disables percentage-based compaction, but manual /compact and automatic recovery from payload-too-large responses remain available.

Prune stored sessions

Run zot sessions prune outside the TUI to find stored sessions whose recorded working directories no longer exist. zot groups them by directory, shows the session count and human-readable stored size in binary units such as KiB and MiB, lets you select entries such as 1,3-5, and asks before permanently deleting anything. This command does not initialize a model or require provider credentials.

Add --older-than AGE to select sessions by time since their last activity, including sessions for directories that still exist. Supported units are m (minutes), h (hours), d (24-hour days), w (7-day weeks), mo (calendar months), and y (calendar years). Use --cwd PATH with --older-than to restrict matches to one working directory. zot rechecks each selected session immediately before deletion and preserves it if it became active recently.

shell

zot sessions prune --dry-run                         # list missing-directory groups
zot sessions prune --older-than 4h --dry-run         # inspect sessions inactive for four hours
zot sessions prune --older-than 1mo --cwd ~/project  # select old sessions for one directory
zot sessions prune --older-than 1y --all              # select every match, then confirm
zot sessions prune --older-than 30d --all --yes       # delete every match without prompting

Fail-closed cleanup

For missing-directory pruning, permission failures, malformed or symlinked session entries, non-absolute working directories, and filesystem errors other than not found are reported and preserved. A deleted directory and a path hidden by some unmounted filesystems are indistinguishable, so review the selection and ensure remote filesystems are mounted before deleting. --all still asks for confirmation; --yes skips it and requires --all. The scan includes normal and named-agent sessions below $ZOT_HOME/sessions/, but not explicit session files stored elsewhere or swarm-agent state.

Timeline

Choose timeline from the /session picker, or run /session timeline directly, to replace the chat area with a read-only view of the current system prompt, user and assistant messages, and tool calls. It does not modify the transcript.

The header shows the latest provider-reported context usage and an estimated composition for the system prompt, tool definitions, and messages. Composition uses a simple byte estimate and is directional rather than tokenizer-exact. Actual usage can remain zero until the provider reports usage for a completed turn.

Key	Action
`[[up]] / [[down]]`	Select the previous or next event.
`[[pgup]] / [[pgdn]]`	Move through the timeline eight events at a time.
`[[tab]] / [[shift+tab]]`	Switch between summary, payload, result, schema, and timing details.
`[[/]]`	Search event labels, summaries, payloads, and results.
`[[ctrl+e]]`	Export the timeline as private-permission JSON to ~/Downloads, falling back to the home directory.
`[[esc]]`	Clear an active search or return to chat.

Timing and export details

Timing is derived from transcript timestamps, so events without recorded timestamps show timing as unavailable. JSON exports include event payloads, tool results, schemas, context usage, and export time. Images are represented by MIME type and byte size; their raw data is not embedded.

Session actions

Type /session, then a space, to autocomplete each action and see its description.

/session timeline inspects context composition, messages, tool calls, and their recorded details.
/session export writes the transcript to a portable .zotsession file.
/session import pulls one back in as a first-class resumable session.
/session fork branches from any past user message into a new session.
/session tree shows every branch in this directory and lets you switch into any of them.

Export covers only the main chat thread. /swarm subagents are not bundled: their per-agent state lives in a unix-socket inbox and a session file on disk, neither of which round-trips through a JSONL file.