Projects and sessions

ProjectsCopy link

A project is one piece of work — in practice, one repository — with its own terminals, tabs, and panel state.

Cmd+N creates one with a single terminal in it. The terminal starts in the current session's directory, or your home directory if there isn't one, so the usual next step is to cd where you're going. Zshell takes it from there: the file tree and git panel anchor themselves to the repository containing that directory.

To skip the cd, right-click a folder in Finder and choose Services → New Zshell Project Here — it opens as a project with its terminal already started inside.

Projects are the unit Zshell switches on:

A project is named after its selected session — so it follows the terminal, the same way a tab title does. Right-click it in the sidebar for Rename… (and Use Automatic Title to undo that), Set Project Directory…, and Close Project. Closing a project ends its sessions; it doesn't touch anything on disk.

For shared remote sessions, closing a pane or project only detaches this client; the host keeps its shell and jobs running.

Saved SSH projectsCopy link

Open the command palette (Cmd+P) and choose New SSH Project…. Add a host, optional user and port, and the remote directory to open. Choose SSH Agent, Password, Private Key File, or Private Key Text for authentication, then save the connection and select Connect.

Saved connections stay available after relaunch. Use the optional Group field to organize the connection list, and its edit and delete buttons to maintain entries. Passwords and pasted private keys are saved in macOS Keychain; a private-key file entry remembers the path to your existing key.

For a command or an SSH launch with extra options, see Quick Launch.

Sidebar groupsCopy link

Use New Group at the bottom of the sidebar to create a Plain Group or a Folder Group…. Plain groups start new terminals in your home directory; folder groups supply the selected folder as the default. An explicit project directory still takes priority. Moving a project between groups does not change its running terminals or replace its pinned directory.

Drag a project onto a group header or another project to organize it. Drag it onto + (New Project) at the bottom of the sidebar to remove its group membership. Group headers can also be dragged to reorder groups. Click a header to collapse or expand it, double-click to rename it, or use its context menu. Choose Set Color Marker… to give the group a color, or Remove Color Marker to clear it. Remove Group keeps all of its projects open. Number shortcuts follow the currently visible project rows; next/previous project navigation can reveal members of a collapsed group.

You can drop folders from Finder anywhere in the sidebar's project list. An already open folder is focused instead of creating a duplicate project.

The project directoryCopy link

Two panels need to know which folder they're showing: the file tree and the git panel. By default Zshell works it out — it takes the terminal's current directory and walks up to the nearest enclosing git repository.

That's why cd-ing around inside a repo doesn't make the file tree jump: the repository root stays the root. Outside a repository, the panels simply follow the terminal.

When the foreground program moves into a different checkout—an agent entering its own Git worktree, for example—Files, Git, and Info follow that checkout instead. They return when the foreground job does. A manually pinned project directory always wins and disables this automatic re-rooting.

To pin it instead, right-click the project and choose Set Project Directory…. The pinned folder is remembered across relaunches, and Use Automatic Directory hands control back.

SessionsCopy link

Each project holds as many sessions as you want, shown as tabs across the top. A session is a real login shell — zsh, fish, bash, whatever your account is set to — with its own working directory and scrollback.

A new local session starts in the pinned project directory when one is set, then uses its sidebar group's default directory. Without either, it inherits the current session's directory and falls back to your home directory.

Tab groupsCopy link

Right-click a tab and choose Move to Group → New Tab Group. That tab joins the new group, shown as a colored arrow without a name. New sessions opened from a grouped tab stay in that group; right-click the group's arrow and choose New Session in Group to create a session directly inside it.

Drag a tab onto a group's arrow or another tab to move it. Its context menu also lists groups and Remove from Group. Click the arrow to collapse or expand the group. Collapsing a group keeps the active terminal running and visible; switching to a hidden member expands the group. Removing a group keeps its tabs and sessions open. Pinning a grouped tab moves it to the fixed section outside the groups. Right-click a group's arrow to choose Set Color Marker… or Remove Color Marker. Group colors and collapse state are restored after relaunching Zshell.

A tab can also be dropped onto a sidebar project, or onto a sidebar group header to create a new project inside that group. Dropping onto + (New Project) at the bottom of the sidebar creates a project outside all sidebar groups. Move Tab to Project in the tab menu also reaches other windows. These moves preserve the running terminals and pane layout. Projects must have the same local or SSH location; creating a new project from a tab preserves its source location. Tabs containing diffs stay in their current project.

Tab titlesCopy link

Tabs are titled by whatever the terminal reports — your shell's prompt escape, or the program currently running. Right-click a tab to Rename… it by hand, and Use Automatic Title to go back to following the terminal.

The rest of the tab menu is the usual set: Close, Close Others, Close Tabs to the Right, Close All, plus Reveal in Finder and Copy Absolute Path for the session's directory. Close Files and Close Diffs clear those content types across the project while leaving terminals and browser panes alone.

WindowsCopy link

Cmd+Shift+N opens another window. Windows are independent — their own projects, their own sidebar state — and each one is restored separately.

What survives a relaunchCopy link

Zshell snapshots your layout as you work, so quitting and reopening gives you back:

• every project, in order
• every tab, including custom names, pinning, and color markers
• sidebar groups, including names, color markers, order, membership, and collapse state
• tab groups, including color markers, order, membership, and collapse state
• pinned project directories and empty projects
• the pane layout inside each tab
• which sidebars were open and which right panel was selected

If a terminal’s original PTY is unavailable, Zshell resumes its verified Claude Code, Codex, Pi, or OpenCode conversation when Resume agent conversations and AI support are enabled. Other panes open fresh shells in their previous directories. The resumed conversation keeps its own identity; Zshell does not recover a running build by replaying commands.

Previous scrollback is restored while terminal.restore-history is enabled. New configurations enable it by default; the restored scrollback is stored on disk.

Terminal environment and initializationCopy link

Select a project, then use Terminal → Project Terminal Environment… to set environment variables and an initialization command. Use Terminal → Tab Terminal Environment… for the current tab's overrides.

Changes affect only terminals created after saving. Existing processes keep their environment. Initialization runs for the normal login shell, not for a custom startup program or explicit argv. ZSHELL_*, TERM, COLORTERM, TERM_PROGRAM, and TERM_PROGRAM_VERSION are managed by Zshell and cannot be overridden.