Skip to content
zidane
Terminal

Sessions and forks

The sessions list, session details, and forking, editing or deleting a message in the terminal app.

What sessions, forks and spaces are in both apps: one engine, two apps.

The sessions list#

Esc in a chat opens the list: the current project's sessions, newest first, with turn, message and run counts. Settings › UI › All projects opens it on every project.

zidane
The sessions list: search, a new-session row and two sessions.
KeyDoes
TypeFilter by title and message text
↑ ↓, PgUp PgDnMove
EnterOpen the session, or start one on the + new session row
TabSwitch scope: current project, all projects, then the sessions a window has open now (with the daemon or a remote host)
ShiftTabNext space, also while you type a search. It wraps after the last space. With Settings › UI › Spaces on or a space from an extension. Rebind it as cycleSpaceInList (keyboard map)
← →Previous and next space
CtrlFThe view of the list: grouping, sort and filters (below)
CtrlShiftXDetails of the highlighted session
CtrlRRetry a session whose environment failed to start
EscBack to the open chat, or quit

When there is another space, the title shows the space between arrows, like ‹ Work ›. Click it to show the next space. The footer shows the key, shift+tab space by default.

CtrlN in a chat starts a new session with the same provider and model.

What a row shows#

MarkMeans
▶The highlighted row
●The session open in this window
◆The Main session, always first
★A favorite. Favorites stay at the top.
SpinnerAfter the title: a run is streaming
◉Pulses after the title: the session waits for your answer
○After the title: another window has it open, idle
BadgesArtifacts and extension badges. Right-click one for its actions.

The marks after the title come from presence, which needs the daemon.

An extension can add a glyph before the title, and a line of text and chips under the counts, such as the session's branch. It can also add rows of its own, such as a ticket or a scheduled job, with the sessions it lists under them. Enter or a click opens such a row, and CtrlShiftX shows its actions.

Extensions can pin lines of their own between the search box and the list, and right under the list, such as an inbox count. They stay in place while the list scrolls, and a click runs what the extension set.

The view of the list#

CtrlF on the sessions list opens its view. Each row cycles its value with ← →, and a change applies at once.

RowChoices
GroupNone, Agent, Project, State, the groupings extensions add, and Space default when the space has its own
SortRecent, Created, A–Z, the sorts extensions add, and Space default when the space has its own
AgentAll, then each agent by name
Extension filtersOne row per filter an extension offers in the space: Off or On, or one of its choices. A filter with several choices gets one Off or On row per choice
Reset viewBack to the space's defaults
Save view as space…Asks for a name, then adds a space that lists the sessions the view keeps, and turns Spaces on

Each space keeps its own view.

Spaces from extensions#

An extension can add spaces. They show next to yours, even with Settings › UI › Spaces off. Such a space lists the sessions the extension chose, plus the sessions started in it. A session started there is tagged with the space and can start on the extension's agent and model. Sessions tagged with an extension's space leave Default, and come back to it when the extension goes. To hide one, add an entry with its id and hidden: true to the spaceList setting.

Hosts and environments#

With remote hosts on, the list groups sessions under each host with a status dot (connected, connecting or offline). A new session asks which host, and on a server, which of its folders (this computer keeps the window's folder).

On this computer, Settings › Agent › Environments picks local, OS sandbox, git worktree or a sandbox provider (execution contexts).

Session details#

CtrlShiftX shows the current session's id, dates, folder, counts, token totals, environment and space.

zidane
Session details, with its keys in the bottom row.
Keybindings, Session details
ActionKeysDescription
DeletesessionDeleteKeysDDescriptionDelete the session (press twice).
Copy idsessionCopyIdKeysCDescriptionCopy the session id.
Generate titlesessionGenerateTitleKeysGDescriptionTitle the session with the current model.
Export mdsessionExportMarkdownKeysEDescriptionExport the session as Markdown under .{prefix}/sessions/.
Export jsonsessionExportJsonKeysJDescriptionExport the session as JSON under .{prefix}/sessions/.
CompactsessionCompactKeysKDescriptionSummarize older turns to free context.
SpacesessionMoveSpaceKeysSDescriptionMove the session to the next space (needs Spaces).
FavoritesessionFavoriteKeysFDescriptionAdd the session to favorites, or remove it.
MovesessionMoveEnvironmentKeysMDescriptionMove the session to another environment or machine.
DetailBehavior
DeletePress the key twice
1 to 9Run the environment's own actions, when it lists some
RenameNo free-text rename. G writes a title from the conversation. Settings › Agent › Auto-update session titles names new sessions after their first exchange (automatic titles).
ExportTo <git root>/.zidane/sessions/<id>.md (or .json), or sessions/ in the data folder outside a git repository
KCompact older turns now (compaction)

Fork, edit or delete a message#

When the agent is idle and nothing waits for approval, CtrlS (or ? on an empty prompt) selects a message. ↑ ↓ move, Enter opens it.

zidane
Selecting a message: the last answer is highlighted.
zidane
An open message, with fork, delete, copy and edit.
Keybindings, Turn details
ActionKeysDescription
ForkturnForkKeysFDescriptionFork the session at this turn (press twice).
DeleteturnDeleteKeysDDescriptionDelete this turn (press twice).
CopyturnCopyKeysCDescriptionCopy this turn.
EditturnEditKeysEDescriptionEdit this turn's text.

Fork and delete need two presses.

ActionResult
ForkA new session with every turn up to and including this one. You land in the fork. The original stays as it was.
DeleteRemoves this turn, and tool calls left without their result. You stay in the session.
CopyCopies the text through the terminal (OSC 52). Some terminals do not support it.
EditRewrites the text of the turn. Tool calls and thinking stay. Enter saves, ShiftEnter adds a line, Esc cancels.

To try another direction, fork at an earlier message and send a new one. What a fork keeps (folder, model chain, effort, space, environment): one engine, two apps.

Reference#