{"id":13567481,"url":"https://github.com/27medkamal/tmux-session-wizard","last_synced_at":"2026-04-09T03:36:30.314Z","repository":{"id":96416754,"uuid":"542078832","full_name":"27medkamal/tmux-session-wizard","owner":"27medkamal","description":"One prefix to control all your session creation, naming, switching, etc using fzf \u0026 zoxide","archived":false,"fork":false,"pushed_at":"2025-02-28T05:06:28.000Z","size":65,"stargazers_count":251,"open_issues_count":3,"forks_count":23,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-03-05T14:29:42.850Z","etag":null,"topics":["dotfiles","fzf","productivity","session","session-management","tmux","zoxide"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/27medkamal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2022-09-27T12:41:57.000Z","updated_at":"2026-02-19T14:26:07.000Z","dependencies_parsed_at":"2024-01-17T05:11:25.130Z","dependency_job_id":"38afb805-169f-43dc-8081-2f05eee22947","html_url":"https://github.com/27medkamal/tmux-session-wizard","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/27medkamal/tmux-session-wizard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/27medkamal%2Ftmux-session-wizard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/27medkamal%2Ftmux-session-wizard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/27medkamal%2Ftmux-session-wizard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/27medkamal%2Ftmux-session-wizard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/27medkamal","download_url":"https://codeload.github.com/27medkamal/tmux-session-wizard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/27medkamal%2Ftmux-session-wizard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31584809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"online","status_checked_at":"2026-04-09T02:00:06.848Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["dotfiles","fzf","productivity","session","session-management","tmux","zoxide"],"created_at":"2024-08-01T13:02:32.573Z","updated_at":"2026-04-09T03:36:30.308Z","avatar_url":"https://github.com/27medkamal.png","language":"Shell","funding_links":[],"categories":["Shell","Plugins"],"sub_categories":[],"readme":"# Tmux session wizard\n\n![GitHub](https://img.shields.io/github/license/27medkamal/tmux-session-wizard)\n![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/27medkamal/tmux-session-wizard)\n\n\u003cimg width=\"500\" alt=\"tmux-session-wizard\" src=\"https://user-images.githubusercontent.com/14043848/195257556-bc2cfe0a-a1c7-4e29-9741-776eaf0caa06.png\"\u003e\n\nOne prefix key to rule them all (with [fzf](https://github.com/junegunn/fzf) \u0026 [zoxide](https://github.com/ajeetdsouza/zoxide)):\n\n- Creating a new session from a list of recently accessed directories\n- Naming a session after a directory/project\n- Switching sessions\n- Viewing current or creating new sessions in one popup\n\n### Elevator Pitch\n\nTmux is powerful, yes, but why is creating/switching sessions (arguably its main feature) is so damn hard to do? To create a new session for a project you have to run `tmux new-session -s \u003csession-name\u003e -c \u003cproject-directory\u003e`. What if you're inside tmux? Oh, wait you have to use `-d` followed by `tmux switch-client -t \u003csession-name\u003e`. Oh, wait again! What if you're outside tmux and you want to attach to an existing session? now you have to run `tmux attach -t \u003csession-name\u003e` instead. What if you can't remember whether you have a session for that project or not. Guess what? Now you have to run `tmux has-session -t \u003csession-name\u003e`. What if your project folder contains characters not accepted by tmux as a session name? What if you want to show a list of existing sessions? You run `tmux list-sessions`. What if you want to create a session for a project you've recently navigated to? What if, what if, what if.... HOW IS THAT BETTER THAN HAVING 20 TERMINAL WINDOWS OPEN?\n\nWhat if you could use 1 prefix key to do all of this? Read on!\n\n### Features\n\n`prefix + T` (customisable) - displays a pop-up with [fzf](https://github.com/junegunn/fzf) which displays the existing sessions followed by recently accessed directories (using [zoxide](https://github.com/ajeetdsouza/zoxide)). Choose the session or the directory and voila! You're in that session. If the session doesn't exist, it will be created.\n\n### Required\n\nYou must have [fzf](https://github.com/junegunn/fzf), [zoxide](https://github.com/ajeetdsouza/zoxide) installed and available in your path.\n\n### Installation with [Tmux Plugin Manager](https://github.com/tmux-plugins/tpm) (recommended)\n\nAdd plugin to the list of TPM plugins in `.tmux.conf`:\n\n```tmux\nset -g @plugin '27medkamal/tmux-session-wizard'\n```\n\nHit `prefix + I` to fetch the plugin and source it. That's it!\n\n### Manual Installation\n\nClone the repo:\n\n    git clone https://github.com/27medkamal/tmux-session-wizard ~/clone/path\n\nAdd this line to the bottom of `.tmux.conf`:\n\n```tmux\nrun-shell ~/clone/path/tmux-session-wizard.tmux\n```\n\nReload TMUX environment with `$ tmux source-file ~/.tmux.conf`, and that's it.\n\n### Customisation\n\nYou can customise the prefix key by adding this line to your `.tmux.conf`:\n\n```tmux\nset -g @session-wizard 'T'\nset -g @session-wizard 'T K' # for multiple key bindings\n```\n\nYou can also customise the height and width of the tmux popup by adding the follwing lines to your `.tmux.conf`:\n\n```tmux\nset -g @session-wizard-height 40\nset -g @session-wizard-width 80\n```\n\nTo customise the way session names are created, use `@session-wizard-mode` option. Allowed values are:\n\n- `directory` (default)\n- `full-path`\n- `short-path`\n\n```tmux\nset -g @session-wizard-mode \"full-path\"\n```\n\nBy default, `tmux-session-wizard` gives you a list of open sessions (hence the name). An alternative is that it gives you a list of _windows_ to choose from. This can be turned on using the setting `@session-wizard-windows`. Add this line to your `.tmux.conf` to enable this behaviour:\n\n```tmux\nset -g @session-wizard-windows on # default is off\n```\n\n### (Optional) Using the script outside of tmux\n\n**Note:** you'll need to check the path of your tpm plugins. It may be `~/.tmux/plugins` or `~/.config/tmux/plugins` depending on where your `tmux.conf` is located.\n\n\u003cdetails\u003e\n\u003csummary\u003ebash\u003c/summary\u003e\n\nAdd the following line to `~/.bashrc`\n\n```sh\n# ~/.tmux/plugins\nexport PATH=$HOME/.tmux/plugins/tmux-session-wizard/bin:$PATH\n# ~/.config/tmux/plugins\nexport PATH=$HOME/.config/tmux/plugins/tmux-session-wizard/bin:$PATH\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ezsh\u003c/summary\u003e\n\nAdd the following line to `~/.zprofile`\n\n```sh\n# ~/.tmux/plugins\nexport PATH=$HOME/.tmux/plugins/tmux-session-wizard/bin:$PATH\n# ~/.config/tmux/plugins\nexport PATH=$HOME/.config/tmux/plugins/tmux-session-wizard/bin:$PATH\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003efish\u003c/summary\u003e\n\nAdd the following line to `~/.config/fish/config.fish`\n\n```fish\n# ~/.tmux/plugins\nfish_add_path $HOME/.tmux/plugins/tmux-session-wizard/bin\n# ~/.config/tmux/plugins\nfish_add_path $HOME/.config/tmux/plugins/tmux-session-wizard/bin\n```\n\n\u003c/details\u003e\n\nYou can then run `t` from anywhere to use the script.\n\nYou can also run `t` with a relative or absolute path to a directory (similar to [zoxide](https://github.com/ajeetdsouza/zoxide)) to create a session for that directory. For example, `t ~/projects/my-project` will create a session named `my-project` and cd into that directory.\n\nAlso, depending on the terminal emulator you use, you can make it always start what that script.\n\n### Development\n\nThe development environment is built with Nix and Nix's Flakes, if you have it on your system then just run `nix develop` and you are ready to go. Other method is to build the Docker image based on provided Dockerfile:\n\n```bash\ndocker build --tag tmux-session-wizard:dev --file ./Dockerfile .\n```\n\nTo run the tests, just run `bats -r ./tests` for local development environment or `docker run --rm -it -u $(id -u):$(id -g) -v $PWD:$PWD -w $PWD tmux-session-wizard:dev bats -r ./tests` if you are using Docker.\n\nThere is also the helper script for it _./scripts/run-tests.sh_, run `./scripts/run-tests.sh -h` to get more information about usage.\n\n### Inspiration\n\n- ThePrimeagen's [tmux-sessionizer](https://github.com/ThePrimeagen/.dotfiles/blob/master/bin/.local/scripts/tmux-sessionizer)\n- Josh Medeski's [t-smart-tmux-session-manager](https://github.com/joshmedeski/t-smart-tmux-session-manager)\n\n### Contributors 🙌\n\n\u003ca href=\"https://github.com/27medkamal/tmux-session-wizard/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=27medkamal/tmux-session-wizard\" /\u003e\n\u003c/a\u003e\n\n### License\n\n[MIT](LICENCE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F27medkamal%2Ftmux-session-wizard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F27medkamal%2Ftmux-session-wizard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F27medkamal%2Ftmux-session-wizard/lists"}