Get Started In tmux

June 7, 2026 · View on GitHub

This tutorial gets opensessions running as a real tmux sidebar, either through TPM or from a local clone. By the end, you will be able to press prefix o → s to open the sidebar, toggle it with prefix o → t, spread non-sidebar panes with prefix o → e, switch directly with prefix o → 1 through prefix o → 9, and see agent and Git state update live.

Prerequisites

  • tmux installed
  • Either TPM already installed or a local checkout of this repository
  • curl or wget if you install with TPM, so opensessions can download prebuilt release binaries
  • Rust/Cargo only if you are developing locally or your platform is not covered by the release binaries

1. Fast path with TPM

If you already use TPM, run:

grep -q "Ataraxy-Labs/opensessions" ~/.tmux.conf 2>/dev/null || printf '\nset -g @plugin '\''Ataraxy-Labs/opensessions'\''\n' >> ~/.tmux.conf && tmux source-file ~/.tmux.conf && ~/.tmux/plugins/tpm/bin/install_plugins

Result: TPM clones the GitHub repo for you. The first time tmux loads the plugin, opensessions downloads the matching prebuilt binaries into ~/.tmux/plugins/opensessions/bin/.

If you do not use TPM yet, continue with the local-clone flow below.

2. Local development only: build from source

Skip this step for normal TPM installs. If you run from a local clone or need to build for an unsupported platform, build the Rust binaries from the repository root:

cargo build --release

Result: the plugin can run binaries from target/release/ instead of downloaded release binaries in bin/.

3. Add opensessions to your tmux config

Open ~/.tmux.conf and add one of these minimal entries:

If you use TPM:

set -g @plugin 'Ataraxy-Labs/opensessions'

If you run from a local clone instead:

source-file /absolute/path/to/opensessions/opensessions.tmux

If you added the TPM plugin line manually instead of using the one-line installer above, reload tmux and install plugins with:

tmux source-file ~/.tmux.conf
~/.tmux/plugins/tpm/bin/install_plugins

All @opensessions-* tmux options already have defaults. Configure width from the in-sidebar width slider or ~/.config/opensessions/config.json; add tmux overrides only for global keys, for example:

set -g @opensessions-focus-global-key "C-e"

Result: tmux registers direct prefix bindings for sidebar toggle, focus, and session switching.

4. Reload tmux configuration

Run:

tmux source-file ~/.tmux.conf

If you are using TPM and have not installed plugins yet, also run:

~/.tmux/plugins/tpm/bin/install_plugins

Result: the new keybinding is active in your current tmux server.

Recommended shortcut scheme:

  • prefix o → s reveals and focuses the sidebar pane.
  • prefix o → t toggles the sidebar.
  • prefix o → e spreads non-sidebar panes in the current window using even-horizontal.
  • prefix o → 1 through prefix o → 9 switch directly to the visible session indices.

If you use a terminal or window manager setup where no-prefix bindings are safe, you can also set @opensessions-focus-global-key and @opensessions-index-keys, but they are left unset by default to avoid conflicts.

5. Open the sidebar

Inside tmux, press:

prefix o → s

Result: tmux reveals and focuses the sidebar. If the server is not running yet, the helper script starts it first.

6. Verify the sidebar is live

Use the sidebar to:

  1. Move selection with j and k or the arrow keys.
  2. Press Enter to switch sessions.
  3. Press n or c to create a new tmux session.
  4. Press t to open the theme picker.

Result: you should see the session list update and tmux switch the attached client to the selected session.

7. Verify agent detection

In any tmux session whose working directory matches a repo you use with a supported agent, start one of these tools:

  • Amp
  • Claude Code
  • Codex
  • OpenCode

Result: the session row should show a live status marker, and the detail panel should show thread-level information when available.

Expected Outcome

You now have opensessions wired into tmux as a toggleable sidebar. From here you can move on to: