Opensessions – A beautiful TMUX sidebar, no nonsense

Part of the— agent-native infrastructure for software development. See also:[Ataraxy Labs]stack[sem](semantic version control) ·[weave](entity-level merge driver) ·[inspect](semantic code review).Read the manifesto:

[https://ataraxy-labs.com/#thesis]· Essays:[https://ataraxy-labs.com/blogs]· LLMs:[https://ataraxy-labs.com/llms.txt]

tmux is all you need. make tmux great again :)

opensessions

is a sidebar for tmux

when your sessions, agents, and localhost tabs start multiplying.

It lives inside your existing tmux workflow instead of replacing it: one small pane for session switching, agent state, repo breadcrumbs, and quick jumps back into the right terminal.

Built with Rust and ratatui for native performance and zero runtime dependencies.

tmux is the only supported mux today. There is older zellij integration code in the repo, but it is not stable enough to document as supported; we are looking for maintainers who want to help bring it back to that bar.

Requirements:

tmux

cargo

(install Rust)TPM

Add this to ~/.tmux.conf

:

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

Then reload tmux and install plugins:

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

Build the binaries:

cd ~/.tmux/plugins/opensessions
cargo build --release

Open the sidebar with prefix o → s

.

TPM clones the repo into ~/.tmux/plugins/opensessions

. The sidebar and server run as native Rust binaries from target/release/

.

If you want the same setup as a single shell command:

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 && cd ~/.tmux/plugins/opensessions && cargo build --release

Use TPM's built-in update (prefix + U

) or run:

~/.tmux/plugins/tpm/bin/update_plugins opensessions

Then rebuild:

cd ~/.tmux/plugins/opensessions && cargo build --release

The plugin automatically restarts the server on update so it picks up the new binary. Toggle the sidebar back on with prefix o → s

if it was open.

Run the uninstall script before removing the plugin files — it cleans up tmux hooks, keybindings, sidebar panes, and environment variables that would otherwise persist and cause glitching:

sh ~/.tmux/plugins/opensessions/integrations/tmux-plugin/scripts/uninstall.sh

Then remove the set -g @plugin 'Ataraxy-Labs/opensessions'

line from ~/.tmux.conf

and run prefix + alt + u

(TPM uninstall).

• Live agent state across sessions for Amp, Claude Code, Codex, and OpenCode.
• Per-thread unseen markers for done

,error

, andinterrupted

states. - Session context in the UI: branch in the list, working directory in the detail panel, thread names, and detected localhost ports.

• Programmatic metadata API: agents and scripts push status, progress, and logs to the sidebar via HTTP.
• Fast switching with j

/k

, arrows,Tab

,1

-9

, session reordering, hide/restore, creation, and kill actions. prefix o → s

andprefix o → t

for sidebar focus and toggle,prefix o → e

for sidebar-safeeven-horizontal

layout in the current window,prefix o → 1

through9

for quick switching, optional no-prefix shortcuts, in-app theme switching, and plugin hooks for more mux providers or watchers.- Native Rust sidebar built with ratatui 0.30 and crossterm 0.29, with a local WebSocket server on 127.0.0.1:7391

.

Scripts and agents can push custom metadata to the sidebar over HTTP — no binary needed:

curl -X POST http://127.0.0.1:7391/set-status \
  -H 'content-type: application/json' \
  -d '{"session":"my-app","text":"Deploying","tone":"warn"}'

curl -X POST http://127.0.0.1:7391/set-progress \
  -H 'content-type: application/json' \
  -d '{"session":"my-app","current":3,"total":10,"label":"services"}'

curl -X POST http://127.0.0.1:7391/log \
  -H 'content-type: application/json' \
  -d '{"session":"my-app","message":"Tests passed","source":"ci","tone":"success"}'

Endpoints: /set-status

, /set-progress

, /log

, /clear-log

, /notify

Tones: neutral

, info

, success

, warn

, error

— each with a distinct icon and color.

Full reference: docs/reference/programmatic-api.md

Build and run from a local clone:

git clone https://github.com/Ataraxy-Labs/opensessions.git
cd opensessions
cargo build --release
cargo test

Start the sidebar manually (outside tmux, for testing):

cargo run -p opensessions-sidebar

Start the server:

cargo run -p opensessions-server

For the full tmux workflow with keybindings, troubleshooting, and configuration options, follow the guide below.

Get started in tmuxSet up Ghostty shortcutsConfiguration referenceFeatures and keybindings referenceProgrammatic API referenceArchitecture explanationContracts and extension interfacesPlugin authoring guide

• Session ordering is persisted in ~/.config/opensessions/session-order.json

. - Amp watcher reads ~/.local/share/amp/threads/*.json

and clears unseen state from Amp'ssession.json

when a thread becomes seen there. - Claude Code watcher reads JSONL transcripts in ~/.claude/projects/

. - Codex watcher reads transcript JSONL files in ~/.codex/sessions/

or$CODEX_HOME/sessions/

and resolves sessions fromturn_context.cwd

. - OpenCode watcher polls the SQLite database in ~/.local/share/opencode/opencode.db

. - Hidden sidebars are stashed in a tmux session named _os_stash

, so they can come back without restarting the sidebar process. - Clicking a detected port opens http://localhost:<port>

.

apps/tui-rs/

— Rust ratatui sidebar client (connects to server over WebSocket)apps/server-rs/

— Rust server that assembles state from mux providers and agent watchersapps/sidebar-shim-rs/

— Lightweight shim for sidebar process managementapps/tui/scripts/

— Shell scripts for tmux sidebar launch and session switching

packages/runtime-rs/

— Shared Rust runtime: tmux provider, agent watchers, config, tracker, protocolpackages/sidebar-core-rs/

— Core sidebar rendering logic, extractable for snapshot testspackages/sidebar-protocol-rs/

— Shared protocol types between server and sidebar

opensessions.tmux

— Root TPM entrypoint for usersintegrations/tmux-plugin/

— tmux-facing scripts and host integration glueintegrations/amp/

— Amp agent integrationintegrations/pi-extension/

— Pi extension integration

• The app is effectively pinned to 127.0.0.1:7391

today. theme

,sidebarWidth

,sidebarPosition

,plugins

, andmux

are wired through the runtime; other typed config fields are not all live yet.- Inline theme objects exist in core, but the running server persists and broadcasts theme names.

• tmux is the only supported mux today.

MIT

source & further reading

github.com — original article