smth: switch to something else

A tmux-native session switcher for navigating between sessions and opening new ones backed by jujutsu (jj) repositories and workspaces.

Features

• Tmux-native navigation. Fuzzy-find sessions in a popup, inspect a live preview, and jump back to the previous session using recency-aware ordering.
• First-class jj workflows. Discover repositories and workspaces, open an existing checkout, create a new workspace at trunk() or a chosen commit, or initialize a fresh colocated Git-backed jj repository.
• Keyboard-first session management. Create sessions in the background, flag them, close them, or delete their associated workspace without leaving the picker. See the complete key bindings.
• Agent attention at a glance. Pi is currently the only supported agent integration. Track its lifecycle state per pane, surface sessions that need attention, and optionally send terminal or desktop notifications.
• Flexible configuration. Add repository globs, customize new tmux sessions, and change the live-session sigil.
• Scriptable workflows. Seed queries, filter candidates, or switch immediately using fzf-style startup flags.

Installation

smth expects tmux and jj to be available on $PATH.

Install the latest version from this repository with Cargo:

cargo install --locked --git https://github.com/amnn/smth

Make sure Cargo's binary directory is on your $PATH so tmux can find the installed smth binary.

Setup

Add to ~/.tmux.conf:

set -g detach-on-destroy off
bind s display-popup -E -w 80% -h 80% -T smth -d "#{pane_current_path}" smth --
bind S choose-tree -s

Then reload the tmux configuration:

tmux source-file ~/.tmux.conf

Next Steps

• Manage sessions: switch, create, close, and delete workspaces.
• Configure smth, including repository discovery.
• Connect agents so smth can track their statuses.
• Configure notifications to signal when sessions need attention.

Session management

The session-management guide covers session and checkout types, ordering and previous-session switching, creation, closing without deleting, and staged workspace deletion. See the key bindings below and scripting for the full command reference.

Key bindings

C- means Control, M- means Alt/Meta, and S- means Shift. smth -h prints brief CLI help; smth --help includes the complete picker key list.

Key	Action
C-d	Toggle the workspace's persisted pending-deletion marker.
C-f	Flag or unflag a live session.
C-g	Cancel onto mode, or clear staged deletions.
C-n	Create a non-live session without switching to it.
C-o	Open or cancel the onto revision picker.
C-p	Toggle the preview pane outside onto mode.
C-r, M-r	Set or reset the current repo.
C-u	Clear the filter.
C-x	Close a live session.
C-y	Confirm deletion of all staged workspaces, including hidden ones, and close their sessions.
up, down, C-k, C-j	Move selection by one row.
M-up, M-down, M-k, M-j	Move selection to the first or last row.
S-up, S-down	Scroll the preview pane up or down.
tab, S-tab	Jump between fuzzy matches in onto mode.
enter	Accept the onto revision, or switch to the session, creating it if necessary.
esc, C-c	Close the UI without clearing staged deletions, unless a background operation is running.

Troubleshooting

If repository detection, session metadata, flags, or secondary jj workspaces do not behave as expected, start with the troubleshooting guide.

Alternatives

Choose smth when you want to keep tmux as the foundation, use jj repositories and workspaces as the session model, and add pane-scoped agent attention without adopting a larger terminal or task-orchestration environment.

• Unlike agent-focused terminal environments such as cmux, Herdr, and Orca, smth preserves your existing terminal and tmux setup.
• Compared with general tmux session tools such as sesh, Tmux Sessionizer, and Tmuxinator, smth adds first-class jj workspace creation, revision selection, and repository metadata.
• Compared with workmux, smth uses jj workspaces rather than Git worktrees and leaves integration workflows to jj.

Contributing

New contributors should start with a human-written issue that explains the problem or proposed change. Please discuss and agree on an approach there before opening a pull request.

Acknowledgements

Credit to @giacgiuliari for the name, smth.

License

smth is licensed under the Apache License 2.0.