Workspaces

A workspace is a named collection of panes hosted by toowld, the toowl daemon. Each workspace gets its own native window. Closing the window detaches — your shells, REPLs, and long-running jobs keep running. Reopen the workspace later and you reattach to the same live state.

toowl up pm2

Three ways to open one

• From any shell. toowl up <name> hands off through a singleton socket so the running GUI picks it up.
• From the palette. Press Cmd+Shift+P / Ctrl+Shift+P and choose Open Workspace….
• From the Workspaces Feather. Open the Perch (Cmd+B / Ctrl+B) and click any workspace under Workspaces.

Detach & reattach

Workspaces are owned by the daemon, not the window. Three consequences worth internalising:

• Closing the window detaches. The daemon keeps the panes, scrollback, and child processes alive. Nothing is killed.
• Reopening reattaches. Run toowl up <name> again (or click in the Feather). You land back in the same scrollback, same cwd, same running commands.
• One workspace, one window. If a workspace is already open, repeat invocations focus the existing window instead of duplicating it.

Declarative workspace files

Drop a TOML file at ~/.config/toowl/workspaces/<name>.toml and it shows up in the Workspaces Feather. toowl up <name> spawns the panes the file declares.

# ~/.config/toowl/workspaces/pm2.toml
name = "pm2"
layout = "2x2"

[[panes]]
title = "api"
cmd = "pnpm dev"
cwd = "~/code/api"

[[panes]]
title = "worker"
cmd = "pnpm worker"
cwd = "~/code/api"

[[panes]]
title = "logs"
cmd = "tail -F /var/log/app.log"

[[panes]]
title = "shell"

layout accepts uniform, 1x2, 2x1, 1x3, 3x1, 2x2, or main-left. Each [[panes]] entry may set title, cmd, and cwd. Omit cmd to get a plain shell.

The Workspaces Feather

The Feather lives on the Perch and shows a two-tier tree:

• Local — workspaces hosted by the daemon on your machine, plus any TOML defs you haven't spun up yet.
• Remote sections — one per remote you've defined in remotes.toml. Collapsed by default; expanding fetches the remote's workspace list lazily.

Status markers in the list use a single ASCII character so they read in every theme:

Edit remotes.toml or anything under ~/.config/toowl/workspaces/ and the Feather refreshes in place — no restart, no manual reload.

Remote workspaces

A workspace hosted by a remote daemon looks the same as a local one, except the window title gets a @ host badge:

toowl - pm2 @ idrl

If the connection drops, the title appends (connection lost) so you can tell at a glance that the daemon isn't reachable. Define remotes in ~/.config/toowl/remotes.toml before opening a remote workspace.

Save the current window as a workspace

From the palette, pick Save Window as Workspace…. toowl walks the current window's pane tree, derives a name from the active pane's cwd, and writes ~/.config/toowl/workspaces/<name>.toml capturing pane titles and working directories.

The current window keeps its live panes (their child PIDs can't migrate to the daemon mid-flight). To pick up the new daemon-backed copy, run toowl up <name>.

Pane chrome dot

Each tab pill paints a small colored square before the title that tells you where the pane lives:

Keep going

• Remote machines — remotes.toml and the Remotes Feather.
• TUI client — attach to the same workspaces from a server shell.
• Feathers — the Perch and the rest of the plugin surface.