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.

Configure Groups and Spaces

Right-click a Group or Space and select Settings.

Group Settings separates controls by purpose:

• General changes the name and icon or deletes the Group.
• Space defaults sets the host and directory for new Spaces. It does not move existing Spaces.
• Appearance selects the Group accent.
• Agents selects favorite and default agent profiles.
• GitHub sets the organization inherited by Spaces.

Space Settings keeps its name, host, and directory in General. Its GitHub tab selects repository scope.

Open curated project tools

Browser, Review, and Editor open executable tools in managed tabs using the selected workspace context.

To open a tool:

1. Press Ctrl+B, then Space.
2. Search for Open Browser, Open Review, or Open Editor.
3. Select the action and press Enter.

Browser and Editor start in the workspace directory. Review starts in an observed Git repository. Gardn asks you to select a repository when the workspace contains more than one.

The default tools use the active Gardn theme. A terminal-derived theme passes the terminal colors through. A custom command runs unchanged.

Open Settings > Commands to replace a command. Clear a command to hide its action. Use its reset row to restore the default.

Open GitHub

Choose Open GitHub from Gardn's command palette. GitHub opens inside the invoking pane for the current client, not a managed tool tab. Sidebars, tabs, and other panes remain usable. Switching away preserves the view in its owner pane. Closing GitHub restores the terminal underneath. It uses the existing gh authentication. If you have not signed in, run gh auth login first.

The native screen uses Gardn's palette, theme, scrollbars, and settings. It has no separate executable command, installation, or configuration file. Gardn adapts behavior from Kit Langton's ghui under the MIT license. See Settings > About for the copyright and license acknowledgment.

To scope GitHub for a group:

1. Right-click the group and select Settings.
2. Open GitHub and enter the login in GitHub Organization.
3. Press Enter to save it.

Space Settings > GitHub controls how each Space uses GitHub:

• Automatic uses discovered local GitHub repositories. If none exist, it uses the Group organization or your personal queues. Discovery errors do not broaden the scope.
• Selected repositories accepts one or more owner/repository identities. Press Enter to save the list. This selection overrides the Group organization.
• Group organization uses the configured Group organization.

Repository narrowing stays within the configured scope. Changing scope closes an invalidated GitHub view. Reopen Open GitHub to apply the settings.

Use the native screen to:

• View authored pull requests, requested reviews, and assigned issues in Overview.
• Read pull request and issue conversations, add comments, edit your own comments, manage labels, change pull request draft status, and close items.
• Review diffs with split or unified views, wrapping, whitespace controls, file navigation, and inline line-range reviews.
• Merge with repository rules enforced, enable auto-merge, or use the merge queue where available.
• Inspect scoped Actions workflow runs, jobs, and steps, and open log links.

Use Queue to choose Authored, Assigned, Mentioned, All, or Review requested. The menu shows only filters supported by the current tab; issues do not offer Review requested. The active filter has a checkmark. Click an option or use arrow keys and Enter. Press Escape to cancel.

Hover highlights controls and clickable rows without changing your selected item or keyboard focus. Text filters apply to loaded results. Use More to load another page. Repository selection never opens an outside-scope view.

The native screen does not offer admin merge, branch deletion, Worktrunk review Spaces, agent handoffs, or an action to open a matching Space.

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.