The zsh-navigator plugin allows you to quickly navigate your workspace using fzf and optionally manage tmux sessions or switch directories.
Inspired by ThePrimeagen tmux-sessionizer script.
- Oh My Zsh or Zinit:
- Add the plugin to your
.zshrc: zinit light Andree37/zsh-navigator - Or for Oh My Zsh:
- Add the plugin to your
git clone https://github.com/Andree37/zsh-navigator.git $ZSH_CUSTOM/plugins/zsh-navigatorAdd the plugin to your .zshrc:
plugins=(zsh-navigator)- Reload your Zsh configuration:
source ~/.zshrc| Variable | Default | Type | Description | Examples |
|---|---|---|---|---|
NAVIGATOR_MODE |
tmux |
Mode | Set the navigation mode. | tmux, cd |
NAVIGATOR_KEYBIND_ENABLED |
true |
Keybinding | Enable keybindings. | true, false |
NAVIGATOR_KEYBIND |
^f |
Keybinding | Keybinding to launch the navigator. | ^g, ^n |
NAVIGATOR_ORIGINAL_PATH_KEYBIND |
^h |
Keybinding | Keybinding to return to the original directory. | ^x, ^o |
NAVIGATOR_STRUCTURE |
unsorted |
Structure | Define the workspace structure. | workspace, workspace_src, unsorted |
NAVIGATOR_BASE_DIR |
$HOME/github |
Directory | Set the base directory for navigation. | /path/to/projects |
NAVIGATOR_MODE: Controls how the navigator operates (tmuxfor session management,cdfor changing directories).NAVIGATOR_KEYBIND_ENABLED: Toggles keybinding functionality (trueto enable,falseto disable).NAVIGATOR_KEYBIND: Defines the keybinding for launching the navigator (default isCtrl+f).NAVIGATOR_ORIGINAL_PATH_KEYBIND: Sets the keybinding for returning to the original directory (default isCtrl+h).NAVIGATOR_STRUCTURE: Configures workspace organization (workspace,workspace_src, orunsorted).NAVIGATOR_BASE_DIR: Specifies the root directory for navigation.
The NAVIGATOR_STRUCTURE variable allows you to define the structure of your workspace. The following options are available:
-
workspace: Expects a workspace directory with subdirectories for each project. For example:~/Projects ├── package1 ├── package2 ├── package3 -
workspace_src: Expects a workspace directory with subdirectories for each project containing asrcdirectory. For example:~/Projects ├── src │ ├── package1 │ ├── package2 │ ├── package3 -
unsorted: Does not expect any specific structure. All directories are listed without any assumptions and this is the default option.
Combine these settings in your ~/.zshrc for a customized experience:
plugins=(git zsh-navigator)
# Enable keybindings
export NAVIGATOR_KEYBIND_ENABLED=true
export NAVIGATOR_KEYBIND="^f"
export NAVIGATOR_ORIGINAL_PATH_KEYBIND="^h"
# Set navigation mode
export NAVIGATOR_MODE="tmux"
# Define workspace structure
export NAVIGATOR_STRUCTURE="workspace"
# Set base directory
export NAVIGATOR_BASE_DIR="$HOME/Projects"-
Run the navigator:
- Manually:
navigator - Or, if keybinding is enabled: Press your configured key (e.g.,
Ctrl+f).
- Manually:
-
Use
fzfto select a directory. -
Depending on the mode:
- TMUX Mode: Opens or switches to a
tmuxsession. - CD Mode: Navigates to the selected directory in your terminal.
- TMUX Mode: Opens or switches to a