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 chips
Each session is one chip in the band. A chip 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 band tells you without switching. A long title ellipsises in the chip; hover it and a tooltip reads the whole name.
A chip'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, 3 panes for a split. A plain live session shows its name alone; no running time ticks beside it. Hover the chip and the ✕ that closes it stands where the tail would.
The strip the chips stand on is title bar. Press its own ground — the SESSIONS label, the divider, the gap between two chips — and a drag moves the window, a double-click zooms it. A chip keeps its own handling: dragging a chip lifts it, double-clicking one renames it.
Drag a chip along the band to reorder it. The other chips slide aside to show where it will land; let go and it stays there, and ⌘1–9 follow the new order. Drag it down onto the stage instead and it swaps or splits, as before.
Rest the pointer on the + 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 still a new session, and a right click still asks where to start.
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 chip 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 (
finishedfor 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.
- The session scope toggle at the band's right corner (⌥⌘S) picks which chips the band shows: every open workspace's sessions (the default), or only the focused workspace's. It moves, starts and stops nothing.
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 /usageand reads what it prints — nothing else. It never reads Claude's sign-in, never touches~/.claudeor 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
| Key | Does |
|---|---|
| ⌘T | new session, in the workspace root |
| ⌘1–9 | switch to session n |
| ⌥⇥ | previous session — hold ⌥ and keep pressing ⇥ to walk further back; ⌥⇧⇥ walks forward |
| ⌘W | close the session — asks Shelve, Kill or Cancel while its shell is alive |
A middle click on a chip closes it too. The switcher that ⌥⇥ opens shows every session as a card, in most-recent-first order.
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 — an instrument at the foot of the window shown only while it has rows — 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.
| Key | Does |
|---|---|
| ⌘D | split the pane right |
| ⌘⇧D | split the pane down |
| ⌥⌘← ↑ ↓ → | focus the neighbouring pane |
| ⌥⌘W | separate the pane — its session steps out to its own chip, 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.