OmniPTY / docs
Docs / Using OmniPTY / Workspaces

Workspaces

A workspace is a named set of tabs and splits — a tmux session, kept inside one window. Pin one and its whole shape comes back the next time you launch; give its panes startup commands and the session comes back too.

The panel

Workspaces live in the drawer, under the file tree; drag the line between the two to give either more room, and the list scrolls when it outgrows its half. ctrl-w p focuses it from anywhere; tab hops between the two panels once the drawer has focus. cmd-alt-1 … cmd-alt-9 (ctrl-alt-1 … ctrl-alt-9 on Linux) switch straight to a workspace by its position in the list, without touching the panel. The command palette reaches the panel's actions too — search “rename workspace” or “pin workspace” and it acts on the current one, opening the drawer if it was hidden. The active workspace also shows as a chip at the left of the status bar.

j k / ↓ ↑ move the selection
enter / o switch to the selected workspace
a add one — type a name in the prompt, enter creates it
r rename the selected workspace, in the same prompt
d delete it — y confirms, anything else cancels. The × on a workspace's row deletes it straight away.
p pin / unpin — pinned workspaces survive a restart
e edit the startup commands of every pane in the workspace
esc dismiss a delete confirmation, then hand focus back to the terminal
drag a workspace reorder — drop it on the workspace whose place it should take. cmd-alt-1 … 9 follow the new order, and pinned workspaces keep it across restarts.

The same operations are on the panel's right-click menu and the + in its header, and File → New Workspace creates one without naming it.

How they behave

Each workspace carries its own tabs, its own splits, and its own active tab. Switching between them swaps the whole terminal area at once; the shells keep running in the background, so a build you left in another workspace is still going when you come back.

A new workspace always starts at ~/ rather than inheriting the focused pane's directory — it's a fresh context, not a continuation. Unnamed ones are called workspace 1, workspace 2, and so on.

Closing the last pane of the last tab of a workspace closes the workspace; closing the last workspace closes the window. With tabs.close_last = "new_tab" the workspace stays, with a fresh tab in your home directory.

Finding your way around

cmd-shift-g (ctrl-shift-g on Linux) opens Go To: type a few characters and every workspace, tab, and pane that matches is shown as a tree — by workspace name, tab title, working directory, the program running in a pane, or the last command that ran there. The best match starts selected, so ⏎ straight away is the common path; ↑ ↓ walk the rows. Landing on a workspace row switches to it; a tab or pane row switches workspace and tab and focuses the pane. With nothing typed it lists everything, with ● marking where you are.

 ⌕ api
 ──────────────────────────────────────────────────────
   ▣ api-platform                                    ●
     ▭ api                                 2 panes   ●
       ▸ ~/dev/api-platform/api          cargo watch ●
       ▸ ~/dev/api-platform/api/tests    zsh
     ▭ web
       ▸ ~/dev/api-platform/web          npm run dev
   ▣ personal
     ▭ api-notes                         vim
 ──────────────────────────────────────────────────────
 ↑↓ move · ⏎ go · esc close · 3 of 14 panes match

Pinning

Workspaces are temporary by default. Press p to pin one, and OmniPTY writes it to ~/.cache/omnipty/workspaces.json: the name, the tabs and any names you gave them, the split tree, which pane was focused, and each pane's working directory. It also remembers which pinned workspace was in front, and the next launch opens on it. Its shells keep running when you quit: they live in a small background process, the session server, the way tmux's do, and the next launch reattaches to them — the same shells, with their scrollback and whatever was running in them. With more than one window open, each pinned workspace lives in one of them; close a window and the next one you open takes over its pinned workspaces, shells included.

To skip the keypress, set auto_pin = true under [workspaces] in the config: every workspace is pinned the moment it is created. Unpin one with p as usual.

What survives, and what doesn't. Quitting, closing the window, and OmniPTY crashing all leave a pinned workspace's shells running; the shells in unpinned workspaces end with the window, as they always did. Logging out or rebooting ends everything, and a shell you exit is gone. A pane whose shell didn't survive starts a fresh one in the saved directory and runs its startup command, so that setup still earns its keep. To stop everything on the way out, use Quit and End Sessions (in the app menu and the command palette). To turn this off altogether, set persist_sessions = false under [workspaces]: pinned workspaces then restore layout and directories with fresh shells.

A reattached shell has the environment it started with. A change to your login files, or to OmniPTY's own environment, reaches new shells, not ones that were already running. Windows opened with -e run their program in-process and take no part in any of this.

The state file is rewritten atomically, and a file that fails to parse is moved aside to workspaces.json.corrupt rather than being overwritten, so a bad write can't quietly erase your layouts. When the file's format changes between releases, the old file is copied once to workspaces.json.v2.bak (or whichever version it was) before the first write in the new one.

Startup commands

A pinned workspace's shells survive a quit, but not a reboot. For that, a pane can declare what it runs: whenever it gets a fresh shell — after a reboot, a Quit and End Sessions, or with persist_sessions = false — it runs it again, so cargo watch is in the top-right pane when you come back either way. It's the tmuxinator model, kept inside the workspace you already have.

ctrl-w r (or File → Set Startup Command…, or the palette) opens a small input for the focused pane. It's prefilled with the pane's current startup command — or, if it has none, with the last command that ran there, so most of the time you just press enter. An empty input clears it. tab cycles what happens when the command exits:

shell drop back to the prompt. The default, and almost always what you want.
close close the pane on a clean exit, exactly as if you'd typed exit. A non-zero status keeps the pane so the failure stays readable.
restart run it again. Exponential backoff from one second, and a breaker: five exits inside a minute stops the restarts with a toast. A run that lasts over a minute resets the count.

To see or edit the whole workspace at once, press e in the workspaces panel or pick Edit Startup Commands… from a row's right-click menu. Every pane is listed as tab 1 · pane 2 — ~/dev/api with its command; arrows move between rows, typing edits, tab cycles on-exit, enter saves the lot. Rows with a startup command show a ▸ in the panel.

Startup commands are saved with a pinned workspace, and only then — set one on a temporary workspace and OmniPTY reminds you to pin it. Reopening a closed tab (cmd-shift-t, or ctrl-shift-alt-t on Linux) also brings its commands back.

How they run

Each pane waits for its own shell to be ready before firing — the first prompt the shell integration reports, not a fixed delay — so a slow .zshrc doesn't lose the command and four panes restoring at once don't race. If a shell never shows a prompt (a broken [shell] program, say) the pane gives up after workspaces.startup_timeout and says so, rather than firing into a void.

With shell integration on and zsh or bash, the command goes through the same silent-run channel as "open in $EDITOR": it isn't echoed at the prompt and never enters shell history. It does appear in the command log, so the status bar shows it running and its exit status is known — which is what close and restart key off. Without integration, or on another shell, the command is typed in visibly followed by enter; that works, but it lands in history and the pane can't see it finish, so on_exit behaves as shell.

A pane that reattaches to its still-running shell doesn't run its command again: whatever was running still is. If that's the startup command itself, its on_exit carries on too, so a restart dev server that crashes after you come back is restarted as usual. A command that exits while OmniPTY is closed just leaves its shell at the prompt; nothing restarts it until the pane next gets a fresh shell.

Before a command fires, its pane shows a dimmed ▸ cargo watch -x check chip in the corner, replaced by real output once it runs (and ↻ while a restart is waiting on its backoff).

Turning them off

A startup command that wedges the app needs an out that isn't editing JSON by hand. Any of these restores the layout without running anything:

  • hold shift while OmniPTY launches;
  • omnipty --no-startup-commands from the CLI shim;
  • run_startup_commands = false under [workspaces] in config.toml, to turn the feature off for good.

workspaces.json now contains commands. Anything that can write that file gets a shell command run on your next launch. It lives in your own ~/.cache and is written owner-only (0600), and OmniPTY will never run a command from anywhere but that file — a per-repository project file is a possible later feature, and it would have to ask first.