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-commandsfrom the CLI shim;run_startup_commands = falseunder[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.