Choose the Right Byobu Session Without Losing Your Shell

You will use byobu-select-session to reconnect to an existing Byobu session, create a new one when you mean to, or run an ordinary shell without Byobu. Allow about ten minutes for a first check. You need the byobu package and a terminal on the Linux host where the sessions exist.

This guide describes the installed Byobu 6.11 package, version 6.11-0ubuntu1.1, and the local byobu-select-session(1) manual page. The installed wrapper uses tmux by default, although Byobu can also use screen. Session names, output and available backends are host-specific.

1. Check the installed command

Start with read-only checks. They do not need elevated privileges and do not attach to, create or stop a session:

$ command -v byobu-select-session
/usr/bin/byobu-select-session
$ dpkg-query -W -f='${Package} ${Version}\n' byobu
byobu 6.11-0ubuntu1.1
$ sh -n /usr/bin/byobu-select-session

The last command is silent on success. This command has no documented selection flag. Its purpose is to inspect available sessions and then attach, create or fall back according to its normal rules.

2. Understand what happens with zero or one session

With the normal configuration, one existing session is selected automatically. With no existing session, the command creates a new Byobu session. That is convenient for an interactive login, but it is also the first common trap: running it in a script or test can attach to a terminal multiplexer rather than return to the calling shell.

Run it as an ordinary user from the terminal where you want to work:

$ byobu-select-session

When one session exists, expect to land inside that session without a menu. When none exists, expect a new Byobu session. There is no need for sudo; using root would inspect or create root's separate session environment and could make ownership and configuration harder to understand.

Checkpoint: once attached, confirm the backend and sessions from inside the terminal multiplexer. The installed package normally uses tmux:

$ tmux list-sessions
NAME: 1 windows (created ... ago) [ ... ]

The exact session name, window count and timestamps will differ. If the command reports that tmux is unavailable, check the Byobu backend selection and package installation before changing configuration.

3. Use the menu when there are several sessions

If more than one visible session exists, the selector prints a numbered menu. It includes the available sessions and, in this multiple-session case, choices to create a new Byobu session or run the configured shell without Byobu.

$ byobu-select-session

Byobu sessions...

  1. tmux: work: 1 windows (created ... ago) [ ... ]
  2. tmux: maintenance: 2 windows (created ... ago) [ ... ]
  3. Create a new Byobu session (tmux)
  4. Run a shell without Byobu (/bin/bash)

Choose 1-4 [1]:

Enter the number for the session you need. Pressing Enter accepts the first choice. The displayed names and shell path are examples of the shape of the output, not values to copy. Check the session name before selecting it, especially on a shared host.

Choosing the shell option starts the shell configured by the SHELL environment variable, or /bin/bash when that variable is absent. It does not delete or detach the listed sessions. To return later, run byobu-select-session again.

4. Force a prompt when there is only one session

The manual documents $BYOBU_CONFIG_DIR/.always-select. By default, BYOBU_CONFIG_DIR is $HOME/.byobu. Create the marker when you want the selector to offer the menu even if only one session exists:

$ mkdir -p "$HOME/.byobu"
$ touch "$HOME/.byobu/.always-select"
$ byobu-select-session

This changes your user-level Byobu behaviour. It needs no elevated privileges. Remove the marker to restore automatic selection:

$ rm "$HOME/.byobu/.always-select"
$ test ! -e "$HOME/.byobu/.always-select" && echo 'automatic selection restored'
automatic selection restored

Do not use a broad recursive removal command for this change. The marker is one file, and removing an entire .byobu directory could discard unrelated user configuration.

5. Keep maintenance sessions out of automatic selection

The manual describes a hidden named session beginning with a dot, for example:

$ byobu -S .hidden

That is useful for a session you do not want the selector to choose automatically. The exact hidden-name handling depends on the backend in this installed release: the local selector source hides names beginning with a dot for screen, while tmux sessions beginning with an underscore are excluded from its list. For tmux, use a name such as _maintenance and verify it with the backend directly:

$ byobu new-session -s _maintenance
$ tmux list-sessions
_maintenance: 1 windows (created ... ago) [ ... ]

Creating a session is a state change, and the session will remain until it exits or you stop it. When you have finished, and only after checking the target name, stop that tmux session with:

$ tmux kill-session -t _maintenance

This permanently ends the processes running in that session. Detach instead if you need to preserve the work. Do not run the kill command against a name copied from an unverified list.

6. Recover from a wrong choice or invalid input

If you select the wrong visible session, detach using the normal key sequence for your Byobu backend, then run the selector again. Detaching leaves the session running. If you enter invalid choices three times in a row, the selector falls back to the youngest session according to the manual. That is a reason to stop and check the menu rather than repeatedly guessing.

If the selector opens a new session unexpectedly, first inspect the backend's list:

$ tmux list-sessions
$ printf 'backend=%s\n' "${BYOBU_BACKEND:-tmux}"
backend=tmux

An empty tmux list explains why the normal command creates a session. If you expected screen sessions, do not assume they are visible to a tmux-backed selector. Select the intended Byobu backend through Byobu's own configuration tools, then recheck the list with the corresponding screen or tmux command.