# Sessions

Start, 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.

For work that should survive client detachment or recover after interruption, use [Continuous execution](/docs/continuous). An attached `zot --continuous` TUI reads committed host history instead of persisting a local session. Continuous import and export bridge session transcripts, but exported transcripts are not full store backups.

## Start a fresh session

Run `/new` to persist the current conversation and start an empty session without exiting zot. It keeps the same working directory, provider, model, tools, extensions, jail state, and other runtime configuration. It does not make a model call. The previous conversation remains available through `/sessions`.

If a turn is active, `/new` cancels it before rotating sessions. It also resets transcript usage, queued prompts, session-scoped tool approvals, and pinned-skill preparation. Background agents stay running, while `/swarm` switches to the new session's scope.

`/new` requires session persistence. With `--no-session`, it is hidden from autocomplete and `/help`. Typing it directly reports that sessions are disabled. You can bind a shortcut such as `alt+n` to `/new` under [TUI settings](/docs/tui-settings), leaving `ctrl+n` available for an optional navigation binding.

## Clear context and pinned skills

`/clear` empties the active in-memory conversation without creating a new session. It also prepares your project and global pins for the next message, without starting a model turn. Use `/new` instead when you want to preserve the current conversation as a distinct entry in `/sessions`. Fresh sessions prepare pins too. Continuing, resuming, importing, or branching an existing session does not reload them. `/compact` summarizes existing context instead of reloading pins. See [Skills](/docs/skills) for availability, scope, and supported modes.

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