Sessions, tabs & panes

The workspace model#

Use the sidebar (⌘\), sessions popover (⌃⌘S), or Workspace Overview (⌘⇧O) to move between contexts without guessing which window contains the work.

Build and adjust a layout#

Use ⌘D and ⌘⇧D to split, ⌥⌘Arrow to move between panes, and ⇧⌘Return to zoom. Comfortable pane density gives each pane a header; compact density uses narrow borders.

harness-cli ls
harness-cli new-session --cwd ~/Code/my-project
harness-cli new-tab --cwd ~/Code/my-project
harness-cli split-window -h

The commands act on the calling pane’s context when run inside Harness. Outside it, omitted targets generally use the active GUI context. Use explicit targets in unattended scripts.

Save a repeatable arrangement#

Save the active tab’s split tree, pane directories, and running command lines as a named layout. A restore creates a new session; it does not resume the old processes.

harness-cli save-layout --name development
harness-cli restore-layout --name development --dry-run
harness-cli restore-layout --name development

Attach from another terminal#

Use attach for one pane, or attach-window to render the session’s split layout in a terminal client. Several clients can connect to the same session.

harness-cli attach-window
# Or choose a session explicitly:
harness-cli attach-window --session "my-project"

In the compositor, the default Ctrl-A prefix followed by d detaches the client. Detaching is not killing the session. The compositor’s navigation is not identical to the native GUI; consult its command reference for advanced bindings.

When multiple clients have different sizes#

The default smallest sizing mode lets every attached client vote on the terminal size. Owner mode follows the client that owns the surface’s size; other clients adapt their view. Use Take Size in the pane menu when you need control.

harness-cli size-mode smallest
# Alternative policy:
harness-cli size-mode owner

Layout persistence, scrollback persistence, and keeping a live process running are separate concerns. A daemon restart can restore saved history and recreate a layout, but is not a guarantee that a build, editor, or shell process continues uninterrupted.

Reusable setups and closed layouts#

Saved Setups captures the current session’s tabs, split ratios, directories, and shell paths. It deliberately does not capture running command arguments; startup commands are entered explicitly. Open returns to an existing setup session, while Open New Copy creates another.

Recently Closed retains the last 20 closed layouts per host and restores fresh shells. These new workspace tools are separate from the legacy save-layout and restore-layout commands above, which can capture running command lines.