HerdRanger 0.20.18 pre-release guide
03 · Sessions, spaces, and agents
Navigate spaces, sessions, and agents.
Use Core’s sidebar and Connections popup for desktop work, or choose a running session in legacy Herdr TUI.
Open the user guide
How Core and TUI organize work
Herdr Core
The saved server is your trusted SSH endpoint. On and Via captions distinguish local and forwarded machines. A separately saved server remains a distinct connection even if machine names match.
Herdr TUI
Legacy work lives in the selected session. A standalone SSH profile opens a shell without a Herdr tree.
Select and manage legacy TUI sessions
HerdRanger can reopen your preferred running session. Use the chooser when you need a different session. Open Manage sessions for supported lifecycle actions and review the target and confirmation before creating, starting, or stopping a session.
After an uncertain result, inspect the host before repeating the action. Discovery and reconnect are read-only.
Create a Core space from a project folder
- Use the + beside the Core server name. New Space targets the selected machine.
- Browse to an existing directory or choose New folder. Review the server, parent, folder name and destination before creating a child folder.
- When creation succeeds, HerdRanger selects the new folder. Canceling New Space leaves that folder in place. If the result is uncertain, verify the destination on the host before retrying.
- Edit the space name prefilled from the folder name. Where offered, New Agent lets you edit its suggested name, select the configured provider, and choose when to start it.
Creating a space leaves existing tabs open. The success notice clears on its own.
Browse existing project folders
HerdRanger can discover existing directories in a configured project root. Browsing is read-only. Review the selected path and the available space or agent action before proceeding.
Git worktrees
A worktree gives a Git repository a separate checkout, so another space can use a different branch in its own folder.
- From a Git-backed space, open Space settings → Manage worktrees → Check repository. Controls depend on the connected Herdr schema.
- Enter the new branch name and review the optional space name and checkout path. Choose Create once to create the checkout and its space.
- Open an existing checkout as a space where supported. Removal is confirmed and non-forced. Inspect the repository on the host if Herdr rejects the removal.
See troubleshooting if the controls are missing or the folder is outside a Git repository.
Core navigation, search, and open connections
Use the sidebar toggle on narrow screens. Wider layouts can show the left tree beside chat. All, Needs input, and Pinned filter the tree. Collapsed branches show attention counts, pinned spaces stay above the scrolling list, and the tree remembers expansion within the connection. Tap an agent to open it, or use its overflow menu for management.
The dock shows Servers, Search, Connections, and Menu. Search opens its own popup for available server, machine, space and agent names.
Connections opens the same popup from the dock or terminal. In Open connections, choose a Current or Open row to return to that exact view. Under Connect to server, select an unopened saved server. The lists scroll while search and the footer stay in place. These rows represent views and saved profiles, and the counts reflect matching rows.
Manage servers opens saved profiles. Done or the header close control returns to your current chat and draft. Close all confirms the views listed when the dialog opened. Terminal-backed views can warn that their shell will stop. Saved profiles stay available. Use the relevant Herdr action if you intend to close remote work.
Choose a provider for an agent
Select from the provider kinds already configured on the host. Available choices depend on the connected runtime. Provider sign-in and tokens belong on the host or with the provider. Verify them separately if the SSH connection succeeds but an agent fails to start.
Treat mutations as remote operations
Creating, renaming, closing, deleting, or moving work changes authoritative Herdr state. Confirm the named target. If the network result is ambiguous, inspect the remote state before repeating the action.
Confirmed agent or space removals may queue behind a running operation. HerdRanger revalidates each target before closing it. A failed or unconfirmed operation stops the remaining queue; rename, move, and create actions are never queued.