Sessions

Vis saves each conversation as a session, so you can close it and continue later. This page shows how to control a session while Vis works, and how to find, fork, organize and export saved sessions. It covers the terminal, the desktop and phone apps and the command line.

When to use

You think of a follow-up while Vis is still working. Send it now. It waits in the queue and runs when the current turn finishes. You can edit it until then.
Vis must read your correction before the turn ends. Send the queued message now. The running turn reads it at its next step.
Vis is going in the wrong direction and you want to stop it. Cancel the turn. Your queued messages return to the composer so you can send them again.
You want to leave the session. See Quit for what Ctrl+C does in each state.
You need a conversation from last week. Find the session by its title or by something said in it.
Your program must create sessions, send messages or find saved sessions. Read Sessions API.
You want to try another approach without losing this conversation. Fork the session.
The last few turns went wrong and you want to go back. Fork from an earlier turn.
Your project has more sessions than you can scan. Put them into groups, star the ones you use often and archive the ones you have finished.
You want to share a conversation or keep a readable transcript. Export the session as an HTML page, or as Markdown with every tool call.
A bug report needs the conversation that shows the problem. Export it, then remove private details as described in Reporting a bug.
You want another session to help or to review the work. Read Council instead.

Start a new session

In the terminal, press Ctrl+X n. In the desktop or phone app, choose New session. To start it inside a group, use the + on the group's band in the app. You can also choose ＋ New session here in the group's g menu in Projects. The session then opens at the top of that group.

Control a running session

You can keep typing while Vis works. A message that you send during a running turn waits in a queue. You can also cancel the running turn or quit the session.

Follow progress

Vis adds short notes while it works. Under each note, one digest row gives a summary of the steps after the note. The row shows what their calls did, for example 1 mutation · 3 observations. It also shows any running, failed or cancelled calls and the time that the steps took. When you stop a turn, the stopped step counts as a failure, so the row turns red.

A mutation changes something, for example a file. An observation only reads. A verification checks the work, for example with tests. An external action reaches outside the computer that runs Vis. The mutation count always shows, also when it is 0, so you can see at once if the steps changed anything.

Open the digest to see the thinking, code and Activity of these steps. Failures, files and images stay visible when the digest is closed. The Interrupted message of a stopped step shows only in the open digest.

When the steps open live views, a closed row ends its counts with live, for example 1 mutation · 1 running · live. Select live to open the newest running live view, or else the newest recording.

To see each step as a separate Activity, turn off Compact mode in Settings. The terminal and each app keep their own choice.

In the desktop or phone app, a large turn first shows only its newest steps, so that the session opens quickly. The app loads the older steps when you scroll near them, and then shows every step, as the terminal does. If the app cannot load them, it shows the error and a Try again button.

Queue a message

Press Enter to send. If no turn is running, the message starts one. Otherwise it is added to the queue below the progress display.

Queued messages run in submission order. The queue pauses after a failed turn. Resume it manually to send the next message.

To edit a queued message:

Terminal: press ↑ to move the newest queued message back into the composer.
Desktop or phone app: choose the message to edit it, or choose × to remove it.

The queue stays when the gateway restarts.

Send a queued message now

Use this when the running turn must read your message before it finishes, for example a correction or a fact that changes the next step. By default a queued message waits for the turn end.

Terminal: press Ctrl+X k to send the whole queue now. To send one message, click Send it now at the end of its row, or press Ctrl+X z and type the label of that button.
Desktop or phone app: choose Send all now in the queue header to send the whole queue. To send one message, choose Send it now on its row.

A sent message shows next iter on its row, and its button changes to Unsend. Choose Unsend to let the message wait for the turn end. The running turn reads the sent messages, in queue order, when it starts its next step. The conversation then shows each one as a normal You message under a Queued · sent now · iter N header. N is the iteration that the message reached.

Images attached to a sent message go with it to the running turn. Vis keeps them with that turn, so the desktop and phone app show them, also after a reload.

Two cases keep a different order:

If the turn ends before its next step, the sent messages start their own turns first, before the rest of the queue.
A queued command (/ or !) cannot go into a running turn. It stays in the queue and runs as its own turn.

Cancel a turn

Press Esc or Ctrl+G to cancel the running turn.

Your queued messages return to the composer as one draft. Submit the draft again to run them.

The cancelled message stays in the conversation. To send it again in the terminal, press ↑.

Quit

Ctrl+C depends on the current state:

State	Ctrl+C
Nothing typed, nothing running	Quits
A draft in the composer	Clears the draft. A second press quits
A turn is running	Cancels the turn
A cancel is in progress	Quits immediately

Find a saved session

Each result shows its project, its group and its status, such as IDLE, NEW or LIVE.

Project and group filters apply to recent sessions and text searches. Selecting several groups searches any of them. A project and group selection narrows both together.

In the terminal

Press Ctrl+X s to open the session switcher. Before you type, it lists your recent sessions. Type to search session titles and conversation text, choose a session with ↑ and ↓, and press Enter to open it.

A border always divides the switcher, also before you type. The left side lists the recent sessions or the sessions that match. The right side shows messages of the selected session, so you always see a part of its conversation.

Before you type, the right side shows the newest messages, newest turn first. When you search, it shows the matching messages, with your search words highlighted. If no message matches, a short note says so above the newest messages. Each message shows who wrote it, You or Vis, and when. The messages stay beside the list in a narrow terminal.

The switcher also has these keys:

Keys	What they do
Ctrl+P	Choose all projects or one project. All projects also clears the groups
Ctrl+G	Choose groups in the chosen project, or select none for all groups. It works only if the project has groups
Ctrl+N	Start a new session
Ctrl+F	Fork the selected session
Ctrl+S	Star or unstar the selected session
Ctrl+D	Delete the selected session after you confirm
Esc	Close the switcher

To browse by project, press Ctrl+X w to open Projects. It lists saved sessions from the connected gateway, including ones you have not opened in this terminal. Use ↑ and ↓ to choose a project, group or session, and press Enter to expand it or to resume a session. Press g on a row for its menu. If your terminal reports mouse clicks, you can click rows and menu items instead.

Each project shows only its name. A new project takes the name of its folder. To rename a project or change its folder, press g on the project row. Then choose Rename project… or Change folder…. For a new folder, type its path and press Enter. The project keeps its sessions, and Vis does not move your files.

To search saved session titles and conversation text, press / while Projects has focus. The search also finds sessions outside the pages on screen. Result-page rows show more matches. Press Esc to go back to your previous folds and page.

Projects shows only part of your sessions and groups at a time. Use the page controls to see more sessions or groups. New sessions and groups appear automatically. If your selected row remains in the list, it keeps focus.

In the desktop or phone app

The app lists sessions under their projects, with groups inside each project. Choose a session to open it.

Each project shows only its name. A new project takes the name of its folder. To add a project, choose the folder icon next to the + button. Then choose the project folder.

To change a project, right-click it or choose the three-dot button at its right. The menu has Rename project, Change folder, Settings and Delete project. When you change the folder, the project keeps its sessions. Vis does not move your files.

To search your sessions, choose the search icon in the app bar. On a phone, you can also pull the session list down. The search opens in its own dialog. The session list behind the dialog does not change.

The dialog opens on your recent sessions, with the most recent at the top. Type to search session titles and conversation text. When you type, the search also finds sessions that you archived.

Menus below the search field control where the search looks. If you added more than one machine, use Machine to choose the machine to search. You cannot choose a machine that does not answer.

Use Project to choose All projects or one named project. If the project you choose has groups, the Groups menu appears. Use Groups to select several groups. The list stays open while you select them. Choose All groups to clear the group selection. To search all projects and groups again, choose All projects.

When you type, the line below the menus shows the number of matches. When you scroll to the end of the results, more results load automatically. If they cannot load, choose Try again below the last result.

With a keyboard, press Ctrl+/ to open the search. This shortcut also works while you type in a text box. When you are not typing, you can also press /.

A border always divides the dialog in the same way as the terminal switcher. The sessions are on the left. The messages of one session are on the right. Before you type, and when no message matches, you see its newest messages. When messages match, you see them with your search words highlighted. On a phone or in a narrow window, the messages are below the sessions.

The messages of the first session in the results show first. To see the messages of a different session, choose that session. To open the session, choose it again. You can also choose Open or one of its messages. Before you type, choose a recent session once to open it. To close the search, press Esc or choose the close button.

Fork a session

A fork is a new session that starts with a copy of another session's conversation. The two sessions then continue separately, and the original does not change. You can fork a session once it has a turn.

Fork the whole conversation

Terminal: press Ctrl+X y. Vis opens the fork and switches to it. To fork another session, select it in the session switcher and press Ctrl+F.
Desktop or phone app: open the session's actions in the session list and choose Fork. The app opens the fork.

Fork from an earlier turn

A turn is one message you sent and the work Vis did to answer it. The fork keeps the turn you choose and every turn before it.

Terminal: press Ctrl+X t to open Fork session at…, which lists the message that started each turn. Type to filter the list, choose the last turn to keep and press Enter.
Desktop or phone app, or a terminal that reports mouse clicks: choose Fork from this turn in the header of a finished answer. In a narrow terminal window, the button reads Fork.

What a fork keeps

Conversation: the copied turns, with the work Vis did and the files attached to them.
Title: the original title followed by (fork). Rename the fork to tell the two sessions apart.
Project and group: the same as the original session.
Settings: your global, project and group settings, but not the settings you changed for the original session only.
A turn that still runs: the turn as it is at the moment of the fork. The copy shows Forked from this point. The turn continues in the original session.

A fork does not copy or restore your project files. Changes Vis made in later turns stay in place, so forking from an earlier turn does not undo them.

Organize sessions into groups

A group collects related sessions under a project, such as "Release apps" or "Bug triage". It shows its own name, colour and session count, and opens and closes like any other fold. A group also narrows which sessions talk to each other in Council.

Desktop or phone app: open the ⋮ menu in a project's header and choose New group. The same menu renames a group, changes its colour, deletes it and files the sessions listed on that page into a group. To move one session, choose Move to... in its actions or drag its row onto a group's band.
Terminal: in Projects, choose ＋ New group… in the g menu of a project, Groups or Sessions row. A group's own g menu renames it, changes its colour, archives it or deletes it. To file sessions, use g on a session row, or mark several with Space and use the group's g menu. Ctrl+X d moves the session you are in.

Deleting a group asks whether to keep its sessions, which return to the project ungrouped, or to delete them with the group.

Rename, star, archive or delete a session

Desktop or phone app: a session's actions include Rename, Star, Archive and Delete.
Terminal: in Projects, the g menu on a session row has its details and the same actions. The g menus on Sessions and Groups show archived sessions and groups.

Stars are shared, so a session you star in the terminal is also starred in the apps. Archived sessions leave the usual lists until you show them. Removing a project or deleting a group or session asks for confirmation, and deleting saved sessions cannot be undone.

Manage sessions from the command line

The vis-agent sessions commands read the sessions saved on this computer, even when you connect the terminal to a remote gateway. A session id can be the full id or any unambiguous prefix from vis-agent sessions list.

vis-agent sessions list                   # saved sessions and their ids
vis-agent sessions search "release notes" # search conversation text
vis-agent sessions show 3a7b2c1d          # one session's details and turns
vis-agent sessions delete 3a7b2c1d        # permanent

vis-agent sessions fork does not create a second session: it records a branch point in the same session, which vis-agent sessions show lists. To get a separate copy, fork in the terminal or an app.

Export a session

Export a saved session to share a conversation, review its tool calls or keep a readable transcript. Use a session id from vis-agent sessions list:

vis-agent sessions export <SESSION-ID> [--md | --html PATH]

Vis does not remove private data from an export. Read an export before you share it. To remove private details, follow Reporting a bug.

Markdown

Markdown is the default format. The export prints the transcript, including tool calls, to stdout:

vis-agent sessions export 3a7b2c1d > session.md

HTML

Use --html for a self-contained page you can open in a browser. Vis creates missing directories and adds .html if the output path has no extension:

vis-agent sessions export 3a7b2c1d --html report.html