logo
Install
Docs
Releases
Install
Docs
Releases
logo
What Fold is
Getting started
Sessions
Workspaces
Remote sessions
Editor
Git
Search
Notes
Terminal
Settings
Shortcuts

Updated: 2026/11/2 23:29:23

PreviousGetting started
NextWorkspaces

#Sessions

A session is a terminal: a real TTY running a shell, drawn by libghostty. Sessions are window-wide — every session stays alive and reachable whichever workspace you are looking at. A session is born in a workspace, runs in its directory, and is that workspace's for life — except a remote session, which belongs to its host and merely sits in the workspace.

#The sidebar

Sessions live in the sidebar down the window's left side. Every open workspace has a group — its coloured box, its name and how many sessions it has — and under it one row per session, every name spelled out. A session sits under the workspace it was born in, so you can see at a glance which project each shell serves. Fold the arrow beside a workspace to tuck its rows away.

A row wears its session's live terminal title — whatever the shell or the program in it sets. Run an agent that states what it is doing and the sidebar tells you without switching. The session on screen wears a plate in its workspace's colour; the others rest bare until the pointer is on them.

A row's tail — the word at its right edge — speaks only when there is something to say: exit 1 when the shell ended, lost when its helper went, offline when its host cannot be reached, :5173 when it owns a listener, 2 panes for a split. A plain live session shows its name alone; no running time ticks beside it. Hover the row and the ✕ that closes it stands where the tail would.

  • Click a row to switch to that session — its workspace comes into focus with it. Double-click it to rename it. A middle click closes it.
  • Drag a row up or down to reorder the sessions in its group, and ⌘1–9 follow. Drag it onto the stage instead and it swaps with a pane, or splits it at an edge.
  • Drag a workspace's name to reorder the workspaces.
  • The sidebar's empty space is title bar: drag it to move the window, double-click it to zoom.

Rest the pointer on the + at the top and three buttons fan out under it — New session, Split right and Split down — each with its key beside it. A click on the + is a new session in the focused workspace, and a right click asks where to start. Each workspace's header has its own + when you hover it: a new session in that workspace, without switching to it.

Fold the sidebar away with ⌃⌘S, or a double-click on its edge: it becomes a narrow rail of workspace boxes with a tile per session under each — still clickable, each naming itself when you hover. Drag the edge to make the sidebar wider or narrower; Fold remembers the width and whether it was folded.

Claude Code fronts its title with a spinner while it works and ✳ while it waits. Fold reads that as a fact, takes it off the name, and wears Claude's own mark on the row instead: animated while working, held still while waiting.

  • The done sound plays when a program in any session rings the terminal bell or says it finished — you hear an agent complete from another workspace. Off in Settings.
  • A banner comes with it: a macOS notification with the session's name, its workspace and the agent's own words (finished for a bare bell). Click it and Fold comes forward on that session. Each session keeps one banner — its next ring replaces it. Off in Settings, beside the sound.
  • Ports shows what a session is listening on.

#Claude usage

When claude is installed, the instruments end with Claude's mark and how much of the current session you have used. Click it for a popup that lists every limit Claude reports — the session, the week, and the week per model — each with a bar and when it resets, and a line saying how old the numbers are.

  • Refresh in the popup's head asks again now.
  • Open as pane turns it into a tool pane. It moves, joins, zooms and comes back after a relaunch like Files, Git and Notes. It has no dock circle and no key: the fact is its door, and a click on the fact brings it from wherever it stands.
  • Where the numbers come from. Fold runs your own claude -p /usage and reads what it prints — nothing else. It never reads Claude's sign-in, never touches ~/.claude or your status line.
  • When it asks. Every five minutes while Fold is in front and the numbers are on screen, again when a limit resets, and when you press refresh. The numbers can trail Claude by a few minutes.
  • If Claude doesn't answer, Fold keeps the last numbers and says how old they are. It also says so when Claude isn't signed in or your account has no plan limits.
  • Turn the fact off in Settings, under Facts bar.

#Moving between sessions

KeyDoes
⌘Tnew session, in the workspace root
⌘1–9switch to the nth session in the sidebar, top to bottom
⌥⇥previous session — hold ⌥ and keep pressing ⇥ to walk further back; ⌥⇧⇥ walks forward
⌘Wclose the session — asks Shelve, Kill or Cancel while its shell is alive

A middle click on a row closes it too. The switcher that ⌥⇥ opens shows every session as a card, in most-recent-first order.

Your panes stay put. Documents and tool panes stand where you put them whatever session you look at. A new session, a row click, ⌘1–9 or ⌥⇥ keeps them on screen, and the session you switch to takes the place where the terminal stood — a split arrives whole. Closing or shelving the session on screen hands them to the session you land on.

Closing the last terminal keeps them too. When the window's last session closes, the documents and tool panes stay and fill the window — no session row in the sidebar. You can keep opening files and tools, and ⌘D splits a new shell beside the focused pane. The next session you start comes back where the terminal stood, the panes at their old size; if you rearranged them meanwhile, your layout is kept and the terminal opens on the left. Close the last pane and you get the "No terminal open" page.

#The shelf

Every shell runs in a small helper that outlives Fold. Closing a session asks the close question: Shelve keeps it running out of sight, Kill ends it, Cancel does nothing. A shelved session is listed on the shelf — the row at the foot of the sidebar, wearing its count — and comes back with a click, scrollback and all. Closing a workspace shelves its sessions; quitting Fold kills nothing. On the next launch Fold reattaches to every shell the helper still holds, and a shell whose process is gone comes back as a fresh shell, said so.

#Splits

A session can be split into panes, each with its own fresh session.

KeyDoes
⌘Dsplit the pane right
⌘⇧Dsplit the pane down
⌥⌘← ↑ ↓ →focus the neighbouring pane
⌥⌘Wseparate the pane — its session steps out to its own row, still running

Closing the last pane closes the session.

#What Fold does to your shell

Nothing. Your own zsh configuration loads first, untouched. The flying-plane prompt — the dim path with the folder lit, the quiet branch, the plane — ships inside the app and needs no setup; see Terminal.