sesh

Sesh, the smart tmux session manager

Sesh is a CLI that helps you create and manage tmux sessions quickly and easily using zoxide. - **Smart session creation** - automatically names sessions based on git repo, git remote, or directory - **Zoxide integration** - jump to your most-used projects instantly - **Session configuration** - define startup commands, windows, and preview commands per project in `sesh.toml` - **Wildcard configs** - apply settings to all projects matching a glob pattern - **Built-in picker** - interactive session selector, or integrate with fzf, television, or gum - **Clone and connect** - clone a git repo and start a session in one step - **Mkdir and connect** - create a new directory (relative or absolute path) and start a session in one step - **Last session switching** - seamlessly bounce between your two most recent sessions - **Root session navigation** - jump to the root of a git worktree or repository - **Nerd Font icons** - display session type icons in your picker - **Shell completions** - tab completion for Bash, Zsh, Fish, and PowerShell > [!NOTE] > ⭐ If you find sesh useful, please star the repo — it helps the project grow and reach more developers! > [!TIP] > Want to see more features and help sesh mature? Consider [sponsoring the project](https://github.com/sponsors/joshmedeski) to support ongoing development. ## Table of Contents

- [Videos](#videos) - [How to install](#how-to-install) - [Shell Completion](#shell-completion) - [Extensions](#extensions) - [Agent skill](#agent-skill) - [How to use](#how-to-use) - [Recommended tmux Settings](#recommended-tmux-settings)

- [Bonus](#bonus) - [Configuration](#configuration) - [Contributing](#contributing) - [Background (the "t" script)](#background-the-t-script) - [Contributors](#contributors) - [Star History](#star-history)

## Videos

Intro from Josh Medeski (sesh's creator)

Review from DevOps Toolbox

## How to install Homebrew To install sesh, run the following [homebrew](https://brew.sh/) command: ```sh brew install sesh ``` Arch Linux AUR To install sesh, run the following [yay](https://aur.archlinux.org/packages/yay) command: ```sh yay -S sesh-bin ``` Fedora (Copr) Sesh is available from the [buckaroogeek/Tmux_sesh](https://copr.fedorainfracloud.org/coprs/buckaroogeek/Tmux_sesh/) Copr repository (Fedora and EPEL 10): ```sh sudo dnf copr enable buckaroogeek/Tmux_sesh sudo dnf install tmux-sesh ``` Go Alternatively, you can install Sesh using Go's go install command: ```sh go install github.com/joshmedeski/sesh/v2@latest ``` This will download and install the latest version of Sesh. Make sure that your Go environment is properly set up. Conda To install sesh, run **one** of the following commands, depending on your setup: - Conda/(micro)mamba users ```sh # Replace with mamba/micromamba if required conda -c conda-forge install sesh ``` - Pixi users ```sh pixi global install sesh ``` Nix See the [nix package directory](https://search.nixos.org/packages?channel=unstable&show=sesh&from=0&size=50&sort=relevance&type=packages&query=sesh) for instructions on how to install sesh through the nix platform. **Note:** Do you want this on another package manager? [Create an issue](https://github.com/joshmedeski/sesh/issues/new) and let me know! ## Shell Completion Sesh supports shell completion (tab completion) for Bash, Zsh, Fish, and PowerShell. This helps you discover commands, flags, and arguments by pressing the Tab key. Bash ```sh # Generate completion script sesh completion bash > sesh-completion.bash # Install system-wide (recommended) sudo cp sesh-completion.bash /etc/bash_completion.d/ # Or install user-only mkdir -p ~/.local/share/bash-completion/completions cp sesh-completion.bash ~/.local/share/bash-completion/completions/sesh # Reload your shell source ~/.bashrc ``` Zsh ```sh # Generate completion script sesh completion zsh > _sesh # Install system-wide (recommended) sudo mkdir -p /usr/local/share/zsh/site-functions sudo cp _sesh /usr/local/share/zsh/site-functions/ # Or install user-only mkdir -p ~/.zsh/completions cp _sesh ~/.zsh/completions/ echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc echo 'autoload -U compinit && compinit' >> ~/.zshrc # Reload your shell source ~/.zshrc ``` Fish ```sh # Generate and install completion sesh completion fish > ~/.config/fish/completions/sesh.fish # Reload fish configuration source ~/.config/fish/config.fish ``` PowerShell ```powershell # Generate completion script sesh completion powershell > sesh.ps1 # Create PowerShell profile directory if it doesn't exist mkdir -p (Split-Path $PROFILE) # Add to PowerShell profile Add-Content $PROFILE ". /path/to/sesh.ps1" # Reload PowerShell & $PROFILE ``` After setting up completion, you can press Tab while typing `sesh` to see available commands, flags, and arguments. ## Extensions ## Raycast Extension The [sesh companion extension](https://www.raycast.com/joshmedeski/sesh) for [Raycast](https://www.raycast.com/) makes it easy to use sesh outside of the terminal. Here are limitations to keep in mind: - tmux has to be running before you can use the extension - The extension caches results for a few seconds, so it may not always be up to date ## Ulauncher Extension For Linux users using [Ulauncher](https://ulauncher.io/) there are two extensions to use sesh outside the terminal: - [Sesh Session Manager](https://ext.ulauncher.io/-/github-jacostag-sesh-ulauncher) - [SESHion Manager](https://ext.ulauncher.io/-/github-mrinfinidy-seshion-manager) Here are limitations to keep in mind for Sesh Session Manager: - tmux has to be running before you can use the extension ## Walker launcher usage (Linux) Create an action directly on $XDG_CONFIG_HOME/config.toml ``` [[plugins]] name = "sesh" prefix = ";s " src_once = "sesh list -d -c -t -T" cmd = "sesh connect --switch %RESULT%" keep_sort = false recalculate_score = true show_icon_when_single = true switcher_only = true ``` ### For the dmenu mode you can use: #### Fish shell: set ssession $(sesh l -t -T -d -H | walker -d -f -k -p "Sesh sessions"); sesh cn --switch $ssession #### Bash/Zsh: ssession=$(sesh l -t -T -d -H | walker -d -f -k -p "Sesh sessions"); sesh cn --switch $ssession ##### For dmenu launchers replace walker -dfk with dmenu or rofi) ## Agent skill Sesh ships an [agent skill](https://agentskills.io) that teaches coding agents to start work through sesh instead of shelling out to `tmux new-session`, `tmux new-window`, and `tmux send-keys`. An agent that has it will pick a session or a window depending on whether the work belongs to something already open, resolve names and directories across tmux, zoxide, config, and tmuxinator, reuse what's already running instead of duplicating it, and leave you where you are when the work is a background step. Install it with the [`skills`](https://github.com/vercel-labs/skills) CLI: ```sh # globally, for every project npx skills add joshmedeski/sesh -g # or into the current project only npx skills add joshmedeski/sesh ``` It works with Claude Code, Codex, Cursor, OpenCode, and [dozens of other agents](https://github.com/vercel-labs/skills#supported-agents) — `skills add` will ask which ones to install to, or take `-a claude-code` to pick. The skill lives at [`skills/sesh/SKILL.md`](skills/sesh/SKILL.md) and is versioned with the CLI, so `npx skills update sesh` picks up changes. To install it by hand instead, copy or symlink that file to `~/.claude/skills/sesh/SKILL.md` (or your agent's equivalent skills directory). ### How to use ### tmux for sessions [tmux](https://github.com/tmux/tmux) is a powerful terminal multiplexer that allows you to create and manage multiple terminal sessions. Sesh is designed to make managing tmux sessions easier. ### zoxide for directories [zoxide](https://github.com/ajeetdsouza/zoxide) is a blazing fast alternative to `cd` that tracks your most used directories. Sesh uses zoxide to manage your projects. You'll have to set up zoxide first, but once you do, you can use it to quickly jump to your most used directories. ### Basic usage Once tmux and zoxide are setup, `sesh list` will list all your tmux sessions and zoxide results, and `sesh connect {session}` will connect to a session (automatically creating it if it doesn't exist yet). It is best used by integrating it into your shell and tmux. #### fzf The easiest way to integrate sesh into your workflow is to use [fzf](https://github.com/junegunn/fzf). You can use it to select a session to connect to: ```sh sesh connect $(sesh list | fzf) ``` #### tmux + fzf In order to integrate with tmux, you can add a binding to your tmux config (`tmux.conf`). For example, the following will bind `ctrl-a T` to open a fzf prompt as a tmux popup (using `fzf-tmux`) and using different commands to list active sessions (`sesh list -t`), configured sessions (`sesh list -c`), zoxide directories (`sesh list -z`), and find directories (`fd...`). ``` … ``` You can customize this however you want, see `man fzf` for more info on the different options. To continuously refresh previews of active tmux sessions, add `--watch` to the preview command: ```sh --preview 'sesh preview --watch {}' ``` Watch mode polls only active tmux sessions; directory and configured-session previews still render once. The default interval is 500 milliseconds and can be changed with `--interval 100ms`. #### tmux + [television](https://github.com/alexpasmantier/television) If you prefer to use television instead of fzf, you can add a binding to your tmux config that opens the [sesh channel](https://alexpasmantier.github.io/television/community/channels-unix/#sesh) in a tmux popup. ```sh bind-key "T" display-popup -E -w 80% -h 70% -d '#{pane_current_path}' -T 'Sesh' tv sesh ``` Use `Ctrl-s` to cycle through the sources, and `Ctrl-d` to kill the highlighted session. ### Window management `sesh window` (alias `w`) lets you list, switch to, and create tmux windows within a session — similar to how `sesh list` and `sesh connect` work for sessions. It's a group of subcommands: ```sh sesh window list # list the windows of a session sesh window connect # select a window, creating it if it doesn't exist ``` #### List windows ```sh sesh window list # the session you're attached to sesh window list -t work # another session sesh window list -j # as json ``` #### Switch to an existing window by name ```sh sesh window connect editor ``` If a window named `editor` exists in the target session, sesh selects it. If it doesn't, sesh creates it. #### Create a new window at a directory ```sh sesh window connect ~/projects/my-app ``` A directory arg