Projects, sessions and panes

Project

A project is a repository folder, with a name and a color. It shows up in the sidebar and it is where sessions start. Besides the folder, a project holds the pane arrangement, whatever you set up for worktrees, and the quick commands you keep at hand.

Switching projects is ⌘1 to ⌘9, in the order they appear in the sidebar, or through the command palette. A pinned project moves to the top of its group and counts in that order.

Session

A session is a real terminal running on your computer, with a folder, a state and, almost always, an agent. A project has as many sessions as you want, and they appear grouped by project in the sidebar, with the count next to the name.

A session starts out named after the agent plus its number in the project, and you can rename it with a double click. The new name survives closing and reopening the app.

Not every session has an agent:

• Agent session. Opens with the agent already running and, if you wrote a first request, already working.
• Terminal. A plain shell, for whatever you want to run yourself. It is the Terminal option in the agent list, or ⌘T.

Sessions can also wait their turn, sitting queued behind another one, and they can be connected to each other by dragging one card onto another, for when two tasks talk to each other.

Pane

A pane is one cell of the project grid, and the rule is simple: one terminal per pane. The grid goes from a single pane up to four by four, meaning sixteen at the same time.

⌘D splits, moving up to the next grid and focusing the empty pane. At the ceiling, the app says so instead of squeezing in one more. Dragging the title moves the terminal into an empty pane, or swaps places with whatever is already there.

In the Sessions view you see one pane at a time, at full size. Seeing several at once is the job of the Grid, described in Agents in parallel.

Places and views

The sidebar separates two different things, and getting that straight saves confusion: the places in the app and the ways of seeing the same terminals.

Folders in the sidebar

When the project list grows, folders group what belongs together. You create them from the command palette, from the project dialog or from the Projects screen, and they take projects dragged in and dragged back out.

Right-clicking a folder renames it, creates a project already inside it and undoes the last change. The sidebar collapses too: drag the divider below 120 pixels and it turns into a column of icons.

The other word context

You will see the word context in two senses, and they are not the same thing:

• Switching context, in the ⌘1 to ⌘9 keyboard shortcut, means switching projects.
• The ctx indicator, a percentage in the session footer, is how much of the agent context window is already used up. It turns yellow past 70 percent and red past 90, and goes back to normal when the agent compacts the conversation.