Workspaces & Terminal

Workspaces & groups

Organize related tabs into workspaces, then bundle workspaces into drag-and-drop groups in the sidebar.

A workspace is a folder of related tabs — one project's terminal, diff panel, and Claude session sit together. Once you have several, groups in the sidebar keep them tidy.

What a workspace contains

Each workspace has its own:

  • Default directory — where new tabs' shells start.
  • Tabs and panes — terminals, Claude sessions, diff panels, web-browser panels.
  • Layout — split ratios, focus, the active tab in each pane.

All of it is persisted to ~/.purplemux/workspaces.json, so a workspace is the unit purplemux saves and restores. Closing the browser doesn't dissolve a workspace; tmux holds the shells open and the layout stays put.

Create a workspace

The first run gives you one default workspace. To add another:

  1. Click + New workspace at the top of the sidebar, or press ⌘N.
  2. Name it and pick a default directory — typically the repo root for that project.
  3. Hit Enter. The empty workspace opens.
Pick the right starting directory
The default directory is the cwd of every new shell in this workspace. If you point it at the project root, every fresh tab is one keystroke away from `pnpm dev`, `git status`, or starting a Claude session in the right place.

Rename and delete

In the sidebar, right-click a workspace (or use the kebab menu) for Rename and Delete. Rename is also bound to ⌘⇧R for the currently active workspace.

Deleting a workspace closes its tmux sessions and removes it from workspaces.json. There is no undo. Tabs that already crashed or were closed stay gone; live tabs get killed cleanly.

Switch workspaces

Click any workspace in the sidebar, or use the number row:

Action macOS Linux / Windows
Switch to workspace 1–9 ⌘1 – ⌘9 Ctrl+1 – Ctrl+9
Toggle the sidebar ⌘B Ctrl+B
Switch sidebar mode (Workspace ↔ Sessions) ⌘⇧B Ctrl+Shift+B

The order in the sidebar is the order the number keys map to. Drag a workspace up or down to change which slot it lives in.

Group workspaces

Once you have a handful of workspaces, drop them into groups by drag-and-drop in the sidebar. A group is a collapsible header — useful for separating "client work", "side projects", and "ops" without forcing them into one flat list.

  • Create a group — drag one workspace onto another and the sidebar offers to group them.
  • Rename — right-click the group header.
  • Reorder — drag groups up and down, drag workspaces in and out.
  • Collapse — click the chevron on the group header.

Groups are visual organization. They don't change how tabs persist or how shortcuts behave; ⌘1 – ⌘9 still walks the flat order top-to-bottom.

Where it lives on disk

Every change writes through to ~/.purplemux/workspaces.json. You can inspect or back it up — see Data directory for the full file layout. If you wipe it while the server is running, purplemux falls back to an empty workspace and starts over.

What's next