How to exit, close, and detach from Herdr

The safe way to leave Herdr is to detach.

Press ctrl+b, release the keys, then press q.

Your terminal returns to the shell while the Herdr server, panes, coding agents, tests, and development servers keep running.

Reattach later with:

herdr

This is different from closing a pane, closing a workspace, or stopping the Herdr server.

The commands sound similar, but they have very different effects.

The quick answer

If you are unsure, detach.

Detach without stopping the work

Herdr uses a server and client model.

The server owns the pseudo-terminals and processes.

The client is the interface you see inside the current terminal window.

Detaching closes the client connection. It does not stop the server.

Press:

ctrl+b, then q

The two keys are sequential.

Hold Control and press b. Release them. Then press q.

Later, run:

herdr

You return to the exact live panes. A coding agent can still be working. A server can still be listening. A test can still be running.

This is the command I use at the end of the day or before closing an SSH connection.

What if I close the terminal window?

Herdr’s server owns the work, not the outer terminal window.

If you close Windows Terminal, Ghostty, iTerm2, Kitty, or another terminal while attached, the client disappears and the server continues running.

The same applies when an SSH connection drops.

Open a new terminal and run:

herdr

An explicit detach is still better when possible. It makes the action intentional and returns you to the shell cleanly.

Exit one shell

Inside a normal shell pane, run:

exit

Or press ctrl+d at an empty shell prompt.

This exits that shell process. Herdr then closes the pane that owned it.

If another foreground program is running, exit is text sent to that program, not a command executed by the shell.

Stop or quit the program first. For a development server, that often means ctrl+c. For an editor or interactive agent, use its own exit command.

Be careful with ctrl+d. It sends an end-of-file signal to the foreground program. Different programs handle it differently.

Close a pane from the CLI

First list the panes:

herdr pane list

Then close the one you intend:

herdr pane close w1:p2

Herdr stops the process in that pane and removes the pane from the layout.

The pane ID is only an example. Read the live ID from herdr pane list.

If the pane contains unsaved editor work, a coding agent, or a development server, closing it ends that process. Read the pane before closing it:

herdr pane read w1:p2 \
  --source recent-unwrapped \
  --lines 80

For scripts and agents, explicit IDs are safer than relying on the currently focused pane.

Close a tab

List the tabs:

herdr tab list

Close one:

herdr tab close w1:t2

Closing a tab closes every pane inside it.

That can stop several unrelated processes at once: an agent, test watcher, server, and log tail.

Inspect the tab and its panes first:

herdr pane list --workspace w1

If you only want to remove one pane, use herdr pane close instead.

Close a workspace

List the workspaces:

herdr workspace list

Close one:

herdr workspace close w2

A workspace contains tabs, and the tabs contain panes.

Closing the workspace stops all processes under that workspace.

Use this when a project context is genuinely finished, not when you only want to switch to another project.

To switch without closing:

herdr workspace focus w1

Or press ctrl+b, then w and choose a workspace from the interface.

Stop the default Herdr session

This is the destructive option:

herdr server stop

It stops the default Herdr server and exits the pane processes it owns.

Use it when you deliberately want to end the session, restart the server after an update, or troubleshoot a server problem.

Do not use it as a substitute for detach.

Before stopping the server:

• save editor changes
• finish or stop tests
• shut down development servers cleanly
• let coding agents finish or record their session state
• check every workspace for important processes

After a full stop, running herdr restores the saved workspace shape: workspaces, tabs, panes, directories, layout, and focus.

It does not revive arbitrary old processes.

Normal panes return as new shells. Supported coding agents can resume their own conversations when an official Herdr integration previously recorded their native session IDs.

Stop and delete a named session

Named sessions are independent Herdr servers.

List them:

herdr session list

Stop one:

herdr session stop work

This exits the pane processes in that named session.

Attach again:

herdr session attach work

Herdr restores the saved session shape.

Delete a stopped session when you no longer want its saved state:

herdr session delete work

Stop and delete are separate on purpose.

Stopping ends the live runtime. Deleting removes the stopped named session from the list and discards its saved session state.

Detach from a remote session

The same binding works when you first SSH to a server and run Herdr:

ssh you@server
herdr

Press ctrl+b, then q.

You return to the remote shell. You can then exit SSH:

exit

The remote Herdr server and its panes continue running.

Reconnect later:

ssh you@server
herdr

This is also the workflow I use when connecting to Herdr from a phone.

Detach from direct terminal attach

Herdr can attach the current terminal directly to one agent or pane on supported Unix systems:

herdr agent attach reviewer

Detach from that direct stream with the same sequence:

ctrl+b, then q

If you need to send a literal ctrl+b to the program inside the direct attachment, press:

ctrl+b, then ctrl+b

Direct terminal attach is not currently supported on native Windows.

Detach does not survive every kind of failure

Detach is the strongest persistence path because the original server and processes keep running.

It does not make a process immortal.

The work stops if:

• the Herdr server is stopped
• the machine reboots
• the operating system kills the process
• the user logs out in an environment that terminates user services
• the process exits on its own

After a server restart, Herdr can restore layout and optionally recent screen history. Screen history restores what you can see, not the old process that produced it.

This distinction matters when someone says a terminal session is “persistent.”

I pressed the wrong keys

ctrl+b q does nothing

Press ctrl+b, release it, then press q.

Do not press all three keys together.

Open the active keybinding list with:

ctrl+b, then ?

Your configuration may use a different prefix or detach key.

I stopped the server

Run:

herdr

Herdr restores the saved layout.

Check which coding agents resumed and which panes returned as new shells. Restart development servers and tests manually.

A pane disappeared

If the shell or foreground program exited, the pane can close with it.

A closed pane ID is not reused. Create a new pane and restart the command.

I only wanted to hide a pane

Use another tab or workspace, or zoom a different pane.

Closing is not hiding. It ends the pane process.

The rule to remember

Detach removes the client.

Close removes a pane, tab, or workspace and ends the processes inside it.

Stop ends the Herdr server and all of its pane processes.

Delete removes the saved state of a stopped named session.

When you want to leave Herdr and come back later, press ctrl+b, then q.

The official state table is in Herdr’s session state and restore guide.