Creating and navigating between sessions

Open a shell

1. Open the project’s Terminal screen.
2. In the tab bar, use the new-tab button.
3. On Windows, the same menu offers the shell: PowerShell, CMD Prompt, Git Bash or WSL. On macOS and Linux, the new tab uses the machine’s default shell.

The session is born in the project’s working directory and becomes a tab on the Terminal screen.

Open an agent

An agent CLI is a session like any other: it runs in the panel, with history, search and restoration identical to a shell’s.

If you already know which agent you want, creating the session with the agent already in it is better than opening a shell and typing the command: the session is born with the right process, without a window in which a shell is in control.

What to expect: the agent is still starting up when creation finishes. Writing to it at that instant arrives scrambled — the text lands in the shell before the agent’s interface takes over. Wait for the agent to go idle before sending the first message; the step-by-step is in Working with an agent in the Terminal.

Switch between tabs

• Click the tab to activate it.
• When there are tabs outside the visible area, the tab bar scrolls: use the arrows at the ends to reach them.
• Switching tabs does not interrupt what is running in the others.

Find out what is open

Beyond the tab bar itself, there is the session list, useful when there are many tabs, when you want a session’s identifier, or when the session is in another workspace.

What the list returns:

• one entry per live session, with title, identifier and the workspace it belongs to;
• totalCount — how many sessions actually exist;
• truncated — whether the list you received was cut, by pagination or by the server’s internal ceiling.

Read truncated before concluding the list is complete. The list has an internal safety ceiling; paging only changes what is displayed, not the ceiling.

Sessions created from a Canvas card may take a few seconds to show up in the list.

Details and switching focus

• Inspecting a session returns metadata and a preview of what is on screen, without ending or writing anything to the process.
• Switching to a session changes the visible tab — the same effect as clicking the tab. It does not change what is running.

On the command line

To create, list, inspect and switch tabs without leaving the terminal, see Terminal command reference — the creation, listing, detail and switch commands, with the workspace selector and pagination options.

If something does not work

• The session does not appear in the list: check the workspace of the query and the truncated field; Canvas card sessions take a few seconds.
• The agent received scrambled text: you wrote before its interface took over. Use Reading, sending and waiting to wait for the right condition before writing.
• The panel does not open: follow When the terminal does not open.