Projects and sessions

Projects

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.

The project directory

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.

Sessions

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 session starts in the pinned project directory when one is set. Otherwise it inherits the current session's directory, then falls back to your home directory when neither is known.

Tab titles

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.

Windows

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 relaunch

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

• every project, in order
• every tab, including custom names and pinned directories
• the pane layout inside each tab
• which sidebars were open and which right panel was selected

Terminals come back as fresh shells in their old directories. Zshell doesn't keep processes alive in the background — if a build was running when you quit, it stopped when you quit.

Previous scrollback is restored only if you ask for it, with terminal.restore-history. It's off by default because the restored scrollback is stored on disk.