#Sessions

A session is one terminal — a real PTY running your login shell. Sessions are the reason Fold exists, so they get the main stage and the cheapest keystrokes.

#The model

session "claude · auth"
  └── split tree
        ├── pane  (PTY)
        └── split
              ├── pane  (PTY)
              └── pane  (PTY)

A session owns a tree of panes. Each pane is its own PTY with its own process. One session with three panes is three shells, grouped under one name in the sidebar.

#Creating and naming

New sessions start in the project root. Renaming is worth doing early — the sidebar is how you'll navigate once several agents are running.

#Splitting panes

Splits nest arbitrarily. Drag the divider between two panes to resize them.

⌘W is context-aware: it closes the focused editor tab when the editor has focus, and the focused pane when the terminal does. Closing the last pane in a session closes the session, and every close asks for confirmation first.

#Session state

The dot beside each name in the sidebar:

A session that has exited stays in the list with its scrollback intact, so you can read what happened. Its panes show an overlay with a restart button.

Sessions with more than one pane show a pane count in the row.

#Keys and your agents

Agents need their control keys — Ctrl+C, Ctrl+R, arrow keys, and everything else. So xterm gets a custom key handler in Fold: ⌘-chords are intercepted by the app, and everything else passes through to the PTY untouched.

That means ⌘T makes a session and ⌘D splits, but Ctrl+C always reaches the process.

#Terminal links

⌘+Click in a terminal:

• A URL opens in your default browser
• A file path inside the workspace opens in the editor — including :line and :line:col suffixes

Paths are verified on disk before being treated as links, so ordinary text isn't underlined by accident. Hovering a link underlines it.

This is how you jump from an agent's src/foo.ts:42:8 straight to that line.

#Searching the scrollback

⌘F with the terminal focused searches the terminal scope of the unified search panel. See Search.

#The switcher HUD

⌥⇥ opens a switcher with two rows — Terminals and Files — and macOS app-switcher semantics: hold ⌥, press ⇥ or ←/→ to step, ↑/↓ to swap rows, release ⌥ to commit.

#Environment

Fold exports into every session:

Gate Fold-specific shell configuration behind FOLD=1 so it doesn't affect your other terminals. See Terminal setup.

#Output handling

PTY output is forwarded as raw bytes on a per-session channel, coalesced on an 8 ms window or a 32 KB cap, whichever comes first. That keeps a chatty agent from flooding the renderer without adding latency you can feel.

On close, a session gets SIGHUP and then SIGKILL after a grace period.