sesh

sesh [-C file] [command] [options]

sesh creates and switches tmux sessions. Josh Medeski wrote it in Go. A session name comes from the git repository, the git remote, or the directory. Directory history comes from zoxide unless you point the frecency table at another jumper, so projects you visit often show up in sesh list next to sessions that are already running.connect attaches to a name and creates the session when it is not running. last switches to the previous attached session, including the case where tmux's own last-session binding no longer has one. picker is a built-in fuzzy selector. preview prints the active window of a session or a directory. clone clones a repository and then connects. mkdir creates a relative, absolute, or home-relative path and connects to it. window lists or selects windows inside a session. root prints the root of the attached session. rename --enrich adds a GitHub issue title to the session name when the gh command can resolve the branch.sesh list with no source flags includes tmux sessions, zoxide results, configured sessions, and tmuxinator configs. Pass -t, -z, -c, or -T to keep one source.This binary is not the AWS SSO tool that is also started by typing sesh. That project is awsesh.

-C file, --config file

Config file to load instead of the default. The file must already exist. This flag is global.

Print the version and exit.

Print sessions. With no source flags, every source is included.

On list and picker, only tmux sessions.

On list and picker, only zoxide results.

On list and picker, only sessions from the config file. Do not confuse this with the global -C path flag.

On list and picker, include tmuxinator configs. On connect, start a missing session with tmuxinator.

Omit the session you are attached to.

Show a source icon. A Nerd Font is needed for the glyphs.

On list, skip the source icon for the named sources (for example tmux). Repeatable.

On list, draw icons without color. Requires --icons.

Drop entries that point at the same session.

On list, show panes in the current session. This requires an attached tmux client. If it is the only source flag, the list is panes only.

On list and window list, print JSON. On list, this cannot be combined with --format.

On list, show sessions the config blacklist would otherwise hide.

On list, render each row yourself. Placeholders cover the display name, the raw session name, the source, the path, and the active window name (plus a prefix form of that window name). Color spans use {fg:yellow} and {/fg}. Supported color names are black, red, green, yellow, blue, magenta, cyan, white, and the bright- variants. gray and grey mean bright-black.

On list and picker, read live sessions instead of the cache. The cache is still refreshed.

Attach, or create the session. Further words are joined into one name.

On connect, mkdir, window connect, and worktree, switch the client instead of attaching. Use this when sesh is started from outside the terminal.

On connect, run this only when the session is created. On mkdir and window connect, run it in the new session or window. On an existing window the text is sent into whatever is already running there.

On connect, resolve the argument to the git root (worktree or repository) before connecting. sesh root (alias r) prints that root for the attached session instead.

Switch to the previous tmux session. Fails when there is no previous session.

Interactive selector. Source flags match list. --preview shows the highlighted session beside the list, and --no-preview hides that pane. --query prefills the filter. --prompt and --placeholder change the TUI text. -s / --separator-aware treats a space as a hyphen, underscore, slash, or backslash. --no-alias-auto does not connect the moment an alias is typed in full.

Preview one session or directory. -w / --watch refreshes an active tmux session. --interval sets that period (default 500ms) and must be greater than zero. Directories and config-only sessions are rendered once.

Clone, then connect. -c / --cmdDir is the directory git runs in. -d / --dir is the checkout directory name. Arguments after -- are extra git flags.

Create the directory if it is missing, then connect. The path may be relative, absolute, or start with a tilde.

Rename the named session, or the attached one, so the name includes its GitHub issue title. gh must be installed and authenticated. A branch with no issue is renamed back to the plain name. Without --enrich the command does nothing.

window list (aliases l, ls) prints windows of the attached session. window connect (aliases cn, c) selects a window by name, or creates it. A directory argument names the window after its basename and starts there. --new always creates a fresh window. -b / --background creates it without moving you. --path sets the start directory. -t / --target names another session, which is started if needed. --session is a deprecated alias of --target.

Treat git worktrees as sessions. list prints worktrees and issue titles. connect takes an issue or pull-request number and creates the worktree when it is missing. --repo is an owner/repo name. --pr treats the number as a pull request (on browse, -p is that flag). browse opens the issue or pull request in a browser, or prints the URL with --print. picker is the interactive form. --refresh ignores the title cache. connect --browser reads the issue from the active browser tab, and that path is macOS-only.

Rebuild the session-list cache from live data.

Write a completion script for bash, zsh, fish, or powershell.

The default file is ~/.config/sesh/sesh.toml, or sesh/sesh.toml under the XDG config directory. --config replaces the path.A schema line at the top of the file turns on editor completion:

$ #:schema https://github.com/joshmedeski/sesh/raw/main/sesh.schema.json

$ tmux_command = "psmux"
blacklist = ["scratch"]
dir_length = 2

[frecency]
list_command = "fasd -d -l -R"
query_command = "fasd -d {}"
add_command = "fasd -A {}"
remove_command = "fasd -D {}"

tmux has to be available, and zoxide has to be installed unless the frecency table names another directory jumper. awsesh installs a different binary that is also invoked as sesh. Short flags change meaning by subcommand: -s is --switch on connect and --separator-aware on picker; -c is --config on list and --command on connect; -p is --panes on list and --pr on worktree browse. list --format rows are display text. connect does not parse them back into a session name, so keep the raw name in a separate field when you pipe the list into fzf. rename without --enrich is a no-op. worktree connect --browser only reads the active tab on macOS.

Josh Medeski publishes sesh on GitHub. The Go module path is github.com/joshmedeski/sesh/v2. The license is MIT.

tmux(1), zoxide(1), fzf(1), tmuxinator(1), gum(1), television(1), gh(1), awsesh(1)

Source code · Documentation