Workspaces and navigation

Use this how-to when you are arranging an active Gardn session. For the complete shortcut list, see the keybinding reference.

Arrange the sidebar

1. Click a workspace in the left sidebar to make it active.
2. Click a group header to collapse or expand its workspaces.
3. Drag a workspace to reorder it. Drag it onto a group to move it into that group.
4. Drag a group header to reorder groups.
5. Right-click a workspace or group to open its context menu. Use the menu to rename, create, or delete items as appropriate.

Deleting a group is destructive: the application asks for confirmation and does not allow deleting the last group. Closing a workspace asks for confirmation by default and closes the workspace's tabs and panes when accepted.

When the sidebar is collapsed, its compact rail keeps groups and agent-status sections visible. Click a group or workspace row to switch directly, click an activity count to open the matching filtered agent picker, and use the help and expand controls at the bottom of the rail.

Create a workspace

Interactive workspace creation derives a name from the starting directory by default. To enter the name before creation, set:

[ui]
prompt_new_workspace_name = true

The prompt applies to interactive creation from the sidebar, menus, navigator, and context bar. gardn workspace create and workspace.create remain non-interactive and use their own --label or label input.

Work with tabs

Click a tab in the tab bar to focus it. Drag a tab to reorder it within the active workspace. Scroll over the tab bar to move through overflowed tabs; manual scrolling suspends automatic follow until tab focus changes, when the active tab is brought back into view. Right-click a tab for its context menu.

To use the keyboard, open the command palette with ctrl+b, then space, and search for a tab action. The default direct prefix actions are documented in the keybinding reference.

Split and focus panes

1. Click a pane to focus it.
2. Open the command palette and choose split pane vertical or split pane horizontal, or use the default prefix bindings.
3. Drag a pane divider to resize the split. Drag the sidebar divider to resize the sidebar.
4. Choose focus pane left, focus pane down, focus pane up, or focus pane right from the command palette to move focus without using the mouse.
5. Choose zoom pane to temporarily show the focused pane. Choose it again to restore the layout.

The default shortcuts are ctrl+b, then v for a vertical split, - for a horizontal split, h/j/k/l for directional focus, z for zoom, and r for resize mode. In resize mode, use h/left, j/down, k/up, or l/right; press enter to accept or esc to leave the mode.

Choose Zen mode from the command palette, or press ctrl+b, then shift+z, to give the terminal the full viewport. Zen mode hides the sidebars, tab bar, mobile header, and context bar for the current client. Repeat the action to restore them.

Use the workspace navigator and context bar

On desktop, the bottom context bar shows the active group, workspace, tab, and focused pane alongside live group, workspace, and tab counts. Click a visible path segment to open the workspace navigator at that group, workspace, tab, or pane.

Press the default ctrl+b, then w to open the workspace navigator directly. It searches groups, workspaces, tabs, panes, and metadata with whitespace-separated terms; filter chips narrow results to blocked, working, idle, or done agents. Group and workspace rows expose disclosure arrows, while singleton tab and pane levels are omitted without making their metadata unsearchable. Use space to toggle the highlighted branch, e to expand the full tree, or c to collapse it to group roots. Mouse hover moves the selection, and clicking a row accepts its group, workspace, tab, or pane target.

Use ctrl+b, then down to hide or restore the context bar for only the attached client. To set its persistent default, set ui.context_bar to always or never.

Use the session navigator

Press the default ctrl+b, then g to open the navigator. Use up and down to move through visible workspaces. Use h, j, k, and l (with left and right arrow aliases) to focus panes. Press enter to switch to the selected workspace, or press a number to choose one of the first ten visible workspaces. tab cycles panes. Press esc or the prefix key to leave the navigator.

The navigator also exposes pane, tab, group, and agent actions through its indexed rows. If a shortcut is not shown there, use the command palette or consult the keybinding reference; do not assume an unset optional binding exists.

Use the command palette

Press the default ctrl+b, then space. Type part of an action name to filter it, select a result, and press enter. The palette includes workspace, tab, pane, group, layout, sidebar, settings, scrollback, and agent actions. It is the safest way to discover an action after changing keybindings.

Close and detach safely

Use the command palette when you need to verify what will close. The default actions are:

• ctrl+b, then x: close the focused pane.
• ctrl+b, then shift+x: close the focused tab.
• ctrl+b, then shift+d: close the selected workspace.
• ctrl+b, then q: detach from the running server or exit a no-session client.

Closing a workspace or its last active content can terminate the processes owned by those panes. Confirm the prompt only when that is intended. Detaching is different from closing: it leaves the server session available for another client.