{"id":13683451,"url":"https://github.com/omerxx/tmux-sessionx","last_synced_at":"2025-04-30T13:30:52.915Z","repository":{"id":210923803,"uuid":"727560685","full_name":"omerxx/tmux-sessionx","owner":"omerxx","description":"A Tmux session manager, with preview, fuzzy finding, and MORE","archived":false,"fork":false,"pushed_at":"2024-05-12T20:56:38.000Z","size":398,"stargazers_count":451,"open_issues_count":14,"forks_count":44,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-05-17T00:32:02.776Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/omerxx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-05T05:28:11.000Z","updated_at":"2024-05-30T19:00:02.806Z","dependencies_parsed_at":"2024-01-22T15:05:47.084Z","dependency_job_id":"3302fa8f-d885-49fa-a617-4760f9b2da97","html_url":"https://github.com/omerxx/tmux-sessionx","commit_stats":null,"previous_names":["omerxx/tmux-sessionx"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omerxx%2Ftmux-sessionx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omerxx%2Ftmux-sessionx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omerxx%2Ftmux-sessionx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omerxx%2Ftmux-sessionx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omerxx","download_url":"https://codeload.github.com/omerxx/tmux-sessionx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224212175,"owners_count":17274376,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T13:02:11.808Z","updated_at":"2025-04-30T13:30:52.894Z","avatar_url":"https://github.com/omerxx.png","language":"Shell","funding_links":[],"categories":["Shell","\u003ca name=\"tools\"\u003e\u003c/a\u003eTools and session management"],"sub_categories":[],"readme":"# Tmux SessionX\n\nA fuzzy Tmux session manager with preview capabilities, deleting, renaming and more!\n\n![image](./img/sessionxv2.png)\n\n## Prerequisites 🛠️\n\n- [tpm](https://github.com/tmux-plugins/tpm)\n- [fzf](https://github.com/junegunn/fzf)\n- [fzf-tmux](https://github.com/junegunn/fzf#fzf-tmux-script)\n- [bat](https://github.com/sharkdp/bat)\n- Optional: [zoxide](https://github.com/ajeetdsouza/zoxide)\n\n## Install 💻\n\nAdd this to your `.tmux.conf` and run `Ctrl-I` for TPM to install the plugin.\n\n```conf\nset -g @plugin 'omerxx/tmux-sessionx'\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n  Install on Nix\n  \u003c/summary\u003e\n\nCurrently only supported using flakes.\n\n#### In your flake.nix inputs\n\n```nix\n\ninputs.tmux-sessionx.url = \"github:omerxx/tmux-sessionx\";\n\n# ...\n\n# include inputs as special args for your systems configuration if you havent done already\n# this makes the inputs available to all your modules\nnixosConfigurations.\"system-name\" = nixpkgs.lib.nixosSystem {\n    specialArgs = {inherit inputs;};\n    modules = [\n        # most likely your configuration.nix\n        # as well as others\n    ];\n  };\n```\n\n#### In your tmux.nix configuration or anywhere else in your configuration\n\n```nix\n\nprograms.tmux.plugins = [\n  {\n    # Need to change \u003csystem\u003e to your aarch or use ${pkgs.system} to interpolate aarch\n    plugin = inputs.tmux-sessionx.packages.\u003csystem\u003e.default;\n    extraConfig = ''''\n  }\n]\n```\n\n\u003c/details\u003e\n\n## Configure ⚙️\n\nThe default binding for this plugin is `\u003cprefix\u003e+O`\nYou can change it by adding this line with your desired key:\n\n```bash\n# I recommend using `o` if not already in use, for least key strokes when launching\nset -g @sessionx-bind '\u003cmykey\u003e'\n```\n\n### Additional configuration options:\n\n```bash\n# By default, tmux `\u003cprefix\u003e` key needs to pressed before `\u003cmykey\u003e` to launch\n# sessionx. In case you just want to bind '\u003cmykey\u003e' without the tmux '\u003cprefix\u003e'\n# add the following line to turn the prefix off. This option is set to\n# on by defaut.\nset -g @sessionx-prefix off\n\n# `C-x` is customizeable, by default it indexes directories in `$HOME/.config`,\n# but this can be changed by adding the config below.\n# e.g. set -g @sessionx-x-path '~/dotfiles'\nset -g @sessionx-x-path '\u003csome-path\u003e'\n\n# A comma delimited absolute-paths list of custom paths\n# always visible in results and ready to create a session from.\n# Tip: if you're using zoxide mode, there's a good chance this is redundant\nset -g @sessionx-custom-paths '/Users/me/projects,/Users/me/second-brain'\n\n# A boolean flag, if set to true, will also display subdirectories\n# under the aforementioned custom paths, e.g. /Users/me/projects/tmux-sessionx\nset -g @sessionx-custom-paths-subdirectories 'false'\n\n# Uses `fzf --tmux` instead of the `fzf-tmux` script (requires fzf \u003e= 0.53).\nset -g @sessionx-fzf-builtin-tmux 'on'\n\n# By default, the current session will not be shown on first view\n# This is to support quick switch of sessions\n# Only after other actions (e.g. rename) will the current session appear\n# Setting this option to 'false' changes this default behavior\nset -g @sessionx-filter-current 'false'\n\n# Window mode can be turned on so that the default layout\n# Has all the windows listed rather than sessions only\nset -g @sessionx-window-mode 'on'\n\n# Tree mode can be enabled which means that instead of a preview,\n# a hierarchy of sessions and windows will be shown\nset -g @sessionx-tree-mode 'on'\n\n# Preview location and screenspace can be adjusted with these\n# Reminder: it can be toggled on/off with `?`\nset -g @sessionx-preview-location 'right'\nset -g @sessionx-preview-ratio '55%'\n\n# The preview can also be disabled altogether\nset -g @sessionx-preview-enabled 'false'\n\n# Change window dimensions\nset -g @sessionx-window-height '90%'\nset -g @sessionx-window-width '75%'\n\n# If you want change the layout to top you can set\nset -g @sessionx-layout 'reverse'\n\n# If you want to change the prompt, the space is needed to not overlap the icon\nset -g @sessionx-prompt \" \"\n\n# If you want to change the pointer\nset -g @sessionx-pointer \"▶ \"\n\n# Customize `ls` command to display your directories nicely (default: `ls`)\n# Can be used with `exa`, `lsd`, or other command of your choice to\n# set preview window to match your preference\nset -g @sessionx-ls-command 'lsd --tree --color=always --icon=always'\n\n# When set to 'on' a non-result will be sent to zoxide for path matching\n# Requires zoxide installed\nset -g @sessionx-zoxide-mode 'on'\n\n# If you want to pass in your own FZF options. This is passed in before all other\n# arguments to FZF to ensure that other options like `sessionx-pointer` and\n# `sessionx-window-height/width` still work. See `man fzf` for config options.\nset -g @sessionx-additional-options \"--color pointer:9,spinner:92,marker:46\"\n\n# If you're running fzf lower than 0.35.0 there are a few missing features\n# Upgrade, or use this setting for support\nset -g @sessionx-legacy-fzf-support 'on'\n\n# With Tmuxinator turned 'on' (off by default), the plugin will take a given name\n# and look for a tmuxinator project with that name.\n# If found, it'll launch the template using tmuxinator\nset -g @sessionx-tmuxinator-mode 'off'\n\n# Turn on fzf-marks (default: off) mode to launch a new session from your marks\nset -g @sessionx-fzf-marks-mode 'off'\n\n# If you want to filter sessions, use a comma separated list of session names\n# e.g. set -g @sessionx-filtered-sessions 'scratch,somesession'\n# This will filter out sessions that contain 'scratch' (used by tmux-floax)\n# and 'somesession'\nset -g @sessionx-filtered-sessions 'scratch,somesession'\n```\n\n## Working with SessionX 👷\n\nLaunching the plugin pops up an fzf-tmux \"popup\" with fuzzy search over existing session (-current session).\nIf you insert a non-existing name and hit enter, a new session with that name will be created.\n\n- `alt+backspace` will delete the selected session\n- `Ctrl-u` scroll preview up\n- `Ctrl-d` scroll preview down\n- `Ctrl-n` select preview up\n- `Ctrl-p` select preview down\n- `Ctrl-r` \"read\": will launch a `read` prompt to rename a session within the list\n- `Ctrl-w` \"window\": will reload the list with all the available _windows_ and their preview\n- `Ctrl-x` will fuzzy read `~/.config` or a configurable path of your choice (with `@session-x-path`)\n- `Ctrl-e` \"expand\": will expand `PWD` and search for local directories to create additional session from\n- `Ctrl-b` \"back\": reloads the first query. Useful when going into window or expand mode, to go back\n- `Ctrl-t` \"tree\": reloads the preview with the tree of sessions+windows familiar from the native session manager (C-S)\n- `Ctrl-/` \"tmuxinator\": fetches a list of tmuxinator sessions and previews them\n- `Ctrl-g` \"fzf-marks\": show fzf-marks marks\n- `?` toggles the preview pane\n\n### Rebind keys:\n\nIf you want to change the default key bindings, you can do using this configuration options:\n\n```bash\n# Configuring Key Bindings:\n# I've remapped these commands to 'alt'.\n# To modify default key bindings, you can use these configuration options:\n\n# This command is equivalent to the 'Enter' key.\nset -g @sessionx-bind-accept 'alt-j'\n\n# Changing this will interactively accept a session\n# when there's only one match\n# NOTE! auto-accept will many times prevent from\n# creating new sessions.\n# It is best combined with `@sessionx-custom-paths`\nset -g @sessionx-auto-accept 'off'\n\n# This command opens the current window list.\n# By default, it is set to `ctrl-w`.\nset -g @sessionx-bind-window-mode 'alt-s'\n\n# This command opens the tree.\n# By default, it is set to `ctrl-t`.\nset -g @sessionx-bind-tree-mode 'alt-w'\n\n# This command opens the configuration path.\n# By default, it is set to `ctrl-x`.\nset -g @sessionx-bind-new-window 'alt-c'\n\n# By default, it is set to `ctrl-r`.\nset -g @sessionx-bind-rename-session 'alt-r'\n\n# This command rebinds scrolling up/down inside the preview.\nset -g @sessionx-bind-scroll-up 'alt-m'\nset -g @sessionx-bind-scroll-down 'alt-n'\n\n# Sessionx Commands:\n# These commands are used within sessionx when it's open.\n\n# This command is equivalent to killing the selected session.\nset -g @sessionx-bind-kill-session 'alt-x'\n\n# This command opens the configuration path.\nset -g @sessionx-bind-configuration-path 'alt-e'\n\n# This command goes back to the previous command.\nset -g @sessionx-bind-back 'alt-h'\n\n# These commands are bindings to select arrows.\nset -g @sessionx-bind-select-up 'alt-l'\nset -g @sessionx-bind-select-down 'alt-k'\n\n# These commands are bindings to delete characters.\nset -g @sessionx-bind-delete-char 'alt-p'\n\n# These commands are bindings to exit sessionx.\nset -g @sessionx-bind-abort 'alt-q'\n\n# This command opens the tmuxinator list.\nset -g @sessionx-bind-tmuxinator-list 'alt-t'\n\n# This command open fzf-marks marks.\nset -g @sessionx-bind-fzf-marks 'alt-g'\n```\n\n## [Tmuxinator](https://github.com/tmuxinator/tmuxinator) Integration 🚀\n\nIf you want sessionx to detect existing tmuxinator projects, you can set a `sessionx-tmuxinator-mode` in your config (see snippet below).\nWith Tmuxinator turned 'on' (off by default), the plugin will take a given name and look for a tmuxinator project with that name. If found, it'll **launch the template using tmuxinator**!.\nThere's also a binding to list tmuxinator projects, defaulting to `Ctrl-/`, configurable via:\n\n```bash\n# Tmuxinator mode on\nset -g @sessionx-tmuxinator-mode 'on'\n\n# Changing the binding from the default Ctrl-/\nset -g @sessionx-bind-tmuxinator-list 'alt-t'\n```\n\n## [fzf-marks](https://github.com/urbainvaes/fzf-marks) Integration 🎯\n\nYou can turn on fzf-marks mode with `sessionx-fzf-marks-mode` to quickly jump to your marks in a new session.\nSessionx will look for marks file in a default location first (`~/.fzf-marks`). **Important**: If the fzf-marks file does not exist,\nfzf-marks mode will not turn on. Currently, you have to manually specify the marks file with `sessionx-fzf-marks-file`\nif you change it to other location (see snippet below).\n\n```bash\n# fzf-marks integration 'on' (default: off)\nset -g @sessionx-fzf-marks-mode 'on'\n\n# Change fzf-marks file to a custom location\nset -g @sessionx-fzf-marks-file '~/.config/fzf-marks'\n\n# Rebind from the default key Ctrl-g\nset -g @sessionx-bind-fzf-marks 'alt-g'\n```\n\n## WARNING ⚠️\n\n- If you're running `fzf` lower than [0.35.0](https://github.com/junegunn/fzf/releases/tag/0.35.0) there are a few missing missing features that might break the plugin. Either consider upgrading or add `@sessionx-legacy-fzf-support 'on'` to your config (see [configuration](#additional-configuration-options))\n- This plugin is not designed to be used outside Tmux, although PRs are happily received!\n\n## Thanks ❤️\n\nInspired by these:\n\n- https://github.com/joshmedeski/t-smart-tmux-session-manager\n- https://github.com/ThePrimeagen/.dotfiles/blob/master/bin/.local/scripts/tmux-sessionizer\n- https://crates.io/crates/tmux-sessionizer\n- https://github.com/petobens/dotfiles/commit/c21c306660142d93d283186210ad9d301a2f5186\n\n## Contributors\n\n\u003ca href=\"https://github.com/omerxx/tmux-sessionx/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=omerxx/tmux-sessionx\" /\u003e\n\u003c/a\u003e\n\nMade with [contrib.rocks](https://contrib.rocks).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomerxx%2Ftmux-sessionx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomerxx%2Ftmux-sessionx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomerxx%2Ftmux-sessionx/lists"}