Core concepts
Workspaces, tabs, panes — and the background server that owns them all.
Four words explain most of Nermal. Three of them you can see; the fourth is the reason the other three survive a reboot.
Pane
A pane is one terminal: one shell (or one program) attached to one PTY. It is the only thing in Nermalthat actually runs something.
Panes have stable ids — %42 — for their whole life. That id is what the
CLI addresses, and what $Nermal_PANE holds inside the pane
itself.
Tab
A tab is a layout of panes. One pane to start with; split it and the tab holds two, arranged in rows and columns you can drag around.
Tabs appear in the sidebar (or the top strip, if you move it there). A tab's label is the best evidence Nermalhas: a name you set, else the coding agent running in it, else the last segment of its working directory.
Workspace
A workspace is a named set of tabs — a project, usually. One window shows one workspace at a time, and ⌘ ⇧ O opens the switcher to move between them or open a second window on another one.
The switcher is one flat list, most recently used first — local and remote workspaces together, each row wearing the machine it lives on. Typing filters by workspace, tab, or machine name, so typing a machine's name is how you see just that machine. ⌘ ⇧ N opens the New Workspace form, where you pick the machine (this computer, or any configured SSH host) and optionally a name.
Workspaces are how Nermalkeeps ten repositories from becoming forty indistinguishable tabs. They also travel: a workspace on a remote machine is still a workspace, opened from the same switcher.
The server
Here is the part that matters. The window does not own your shells — a background server does.
Quitting Nermalcloses the window and leaves that server running. Your build keeps building, your agent keeps working, your SSH session stays up. Open Nermalagain and it reattaches to exactly what was there.
This is also why:
Nermalworks from any terminal. The CLI talks to the same server. The GUI does not have to be running at all.- A crash is not a catastrophe. Panes come back showing what was on them: a capped tail of each pane's output is kept on disk and handed to the pane that reopens on its id.
- Stopping is explicit. Quit and Stop Server… in the tray menu is the only ordinary way to end everything, and it warns you first.
Restarting the server ends every process in every pane on that machine — shells, agents, and SSH sessions alike. Layouts are kept and come back with fresh shells. Never do it on someone else's behalf without asking.
What survives what
| Close a tab | Quit Nermal | Stop the server | Reboot | |
|---|---|---|---|---|
| The shell keeps running | ✗ | ✓ | ✗ | ✗ |
| The layout comes back | ✗ | ✓ | ✓ | ✓ |
| What was on screen comes back | ✗ | ✓ | ✓ | ✓ 1 |
| A supported agent session resumes | ✗ | ✓ | ✓ | ✓ |
Machines
Everything above exists per machine. Your laptop is one; a dev box you connect to over SSH is another, with its own server, its own workspaces, and its own panes.
The switcher lists them together, and the CLI reaches them with -m:
Nermal-m devbox lsRemote panes run on the remote machine — the files, the repository, the git data, and the process tree are all over there. Remote workspaces →
The three environment variables
Every pane exports these, and anything you launch from one inherits them:
| Variable | What it holds |
|---|---|
Nermal_PANE | This pane's id — the default target of Nermalsplit, send, capture, procs. |
Nermal_WS | This pane's workspace id. |
Nermal_CONFIG_DIR | The config directory, which is how the CLI finds the right server. |
echo $Nermal_PANE is the fastest way to tell whether you are inside Nermalat all.
Drive it from a script
Those ids are the whole interface. The CLI page starts there.