zsh-dev-navigator

A minimal Zsh plugin that lets you quickly jump into your development directories with a single command.
dev acts as a smart replacement for cd, allowing you to navigate into project folders instantly with recursive autocompletion — and even open them directly in VS Code.

---

⚡ Quick Start

dev api-server
# → cd ~/dev/api-server

Or open the project in your configured editor:

dev -o api-server
# → Opens ~/dev/api-server in your configured editor (default: VS Code)

Create a new project directory:

dev -c new-project
# → Creates ~/dev/new-project and navigates to it

Create a new project with git repository:

dev -cg new-project
# → Creates ~/dev/new-project, initializes git, and navigates to it

Execute a file (with confirmation):

dev script.sh
# → Asks for confirmation, then executes ~/dev/script.sh

Execute a file with arguments:

dev test.sh -ac --verbose
# → Target is a file: ~/dev/test.sh
# → With arguments: -ac --verbose
# → Do you want to execute this file? [y/N]: y
# → Executes: ~/dev/test.sh -ac --verbose

# Or interactively:
dev test.sh
# → Do you want to execute this file? [y/N]: y
# → Enter arguments (or press Enter for none): -ac --verbose
# → Executing with arguments: -ac --verbose

Open a file in editor:

dev -o config.json
# → Opens ~/dev/config.json in your configured editor

---

✨ Features

• ⚡ Quickly cd into any development project with a simple command.
• 📁 Smart recursive autocompletion for subfolders.
• 🧭 Defaults to your base development folder when no argument is provided.
• 🪄 Optional flags to extend functionality — e.g., open projects directly in your preferred editor.
• 🆕 Create new project directories on-the-fly with the -c flag.
• 🔧 Initialize git repositories automatically with the -cg flag.
• ⚙️ Configurable base directory and default editor via configuration file.
• 🤖 Auto git init option to initialize git repositories with -c flag automatically.
• 📄 File execution support with confirmation prompts for executable files.
• 📝 File editing with -o flag to open files directly in your configured editor.
• 🧠 Intelligent file/directory detection based on file extensions.
• 🆕 File creation with automatic parent directory creation.
• 🔄 Fallback mode for users without fzf installed.
• 🔍 Fuzzy finder integration (fzf) for interactive project selection when no argument is provided.
• 🎯 Support for multiple editors: VS Code, Cursor, Windsurf, Sublime Text, Vim, and more.

---

📦 Installation

Oh My Zsh

1. Clone the plugin into your Oh My Zsh custom plugins folder:

   git clone https://github.com/dvigo/zsh-dev-navigator.git ~/.oh-my-zsh/custom/plugins/zsh-dev-navigator

2. Enable it in your ~/.zshrc:

   plugins=(... zsh-dev-navigator)

3. Reload Zsh:

   source ~/.zshrc

---

🎥 Demo

Basic usage:

dev api-server

Result:

📂 Moved to: ~/dev/api-server

Autocompletion:
Start typing and press <TAB> to explore all projects and subfolders:

dev fr<TAB>
# frontend-app
# frontend-utils
# frontend-tests

Open in your preferred editor:

dev -o frontend-app
# → Opens ~/dev/frontend-app in your configured editor (e.g., Cursor, VS Code, etc.)

Interactive project selection with fuzzy finder:

dev
# → Opens fzf interface to select from available projects
# → Press ESC to navigate to the root dev folder

Create new project:

dev -c new-project
# → Creates ~/dev/new-project and navigates to it

Create new project with git:

dev -cg new-project
# → Creates ~/dev/new-project, initializes git, and navigates to it

---

⚙️ Configuration

The plugin uses a configuration file located in the plugin directory. You can customize the following settings:

Configuration File

The plugin includes a config file with the following options:

# Development directory - where your projects are located
# This can be an absolute path or use ~ for home directory
dev_directory = ~/dev

# Default editor to use with the -o flag
# Supported editors: code, cursor, windsurf, subl, vim, nvim, emacs, atom, webstorm, idea, pycharm
editor = code

# Automatically initialize git repository when creating new directories with -c flag
# Set to true to enable automatic git init, false to disable
auto_git_init = false

Customizing Settings

1. Development Directory: Change the dev_directory setting to point to your projects folder:

   dev_directory = ~/Development
   dev_directory = /path/to/your/projects

2. Default Editor: Set your preferred editor for the -o flag:

   editor = cursor        # Cursor editor
   editor = windsurf      # Windsurf editor  
   editor = code          # VS Code
   editor = subl          # Sublime Text
   editor = vim           # Vim
   editor = nvim          # Neovim

3. Custom Editor Path: You can also specify a full path to a custom editor:

   editor = /usr/local/bin/my-custom-editor

4. Automatic Git Initialization: Enable automatic git init when creating directories with -c:

   auto_git_init = true   # Always initialize git with -c flag
   auto_git_init = false  # Only initialize git with -cg flag (default)

---

🖊️ Usage

Basic syntax:

dev <project-name>

Examples:

dev dashboard-ui
# → cd ~/dev/dashboard-ui

dev api-server/routes
# → cd ~/dev/api-server/routes

dev
# → cd ~/dev

Open a project in your configured editor:

dev -o api-server
# → Opens the project in your configured editor (Cursor, VS Code, etc.)

Create a new project directory:

dev -c new-project
# → Creates ~/dev/new-project and navigates to it

Create a new project with git repository:

dev -cg new-project
# → Creates ~/dev/new-project, initializes git, and navigates to it

Note: If you have auto_git_init = true in your config, then dev -c new-project will also initialize git automatically.

Combine flags:

dev -c -o new-app
# → Creates ~/dev/new-app and opens it in your configured editor

dev -cg -o new-git-project
# → Creates ~/dev/new-git-project, initializes git, and opens it in your editor

---

📄 File Handling

The plugin now supports working with files in addition to directories:

File Execution

When targeting a file, the plugin will ask for confirmation before execution:

dev script.sh
# → Target is a file: ~/dev/script.sh
# → Do you want to execute this file? [y/N]: y
# → Executes the file and navigates to its directory

With arguments:

dev deploy.sh --env production --force
# → Target is a file: ~/dev/deploy.sh
# → With arguments: --env production --force
# → Do you want to execute this file? [y/N]: y
# → Executes: ./deploy.sh --env production --force

Interactive argument input:

dev script.sh
# → Target is a file: ~/dev/script.sh
# → Do you want to execute this file? [y/N]: y
# → Enter arguments (or press Enter for none): -v --debug
# → Executing with arguments: -v --debug
# → Executes: ./script.sh -v --debug

Use cases:

• Run scripts with flags: dev test.sh -v
• Pass configuration: dev build.sh --config prod
• Multiple arguments: dev script.sh arg1 arg2 arg3
• Interactive mode: dev script.sh → then enter arguments when prompted

File Editing

Use the -o flag to open files directly in your configured editor:

dev -o config.json
# → Opens ~/dev/config.json in your editor
# → Navigates terminal to ~/dev/ directory

Creating New Files

The plugin intelligently detects when you're trying to work with files and offers to create them:

With -o flag (create and edit):

dev -o new-config.json
# → File does not exist: ~/dev/new-config.json
# → Do you want to create this file? [y/N]: y
# → Created and opened file in your editor

Without flags (create and optionally execute):

dev new-script.sh
# → File does not exist: ~/dev/new-script.sh
# → Do you want to create this file? [y/N]: y
# → File created: ~/dev/new-script.sh
# → Do you want to execute this file? [y/N]: n

Files in Subdirectories

The plugin automatically creates parent directories when needed:

dev -o src/components/Header.jsx
# → Creates src/components/ directory if it doesn't exist
# → Creates and opens Header.jsx in your editor

Intelligent Detection

The plugin automatically detects whether you're working with files or directories:

Files (with extensions):

• script.sh, config.json, README.md → Treated as files
• Offers creation, execution, or editing options

Directories (without extensions):

• my-project, frontend-app, api-server → Treated as directories
• Suggests using -c flag for creation

Restrictions

• Creation flags (-c, -cg) cannot be used with files
• fzf selection with -c/-cg shows only directories
• Autocompletion with -c/-cg shows only directories

---

📌 Autocompletion

The dev command includes powerful autocompletion for all subdirectories inside your base development folder.

Just type part of a project name and press <TAB> to complete it.

🔍 Fuzzy Finder Integration

When you run dev without any arguments, the plugin provides different interfaces based on availability:

With fzf (Enhanced Experience)

If fzf is installed, you get an interactive selection interface:

• Browse through all your projects with fuzzy search
• Use arrow keys or type to filter projects
• Press Enter to navigate to the selected project
• Press ESC to navigate to the root development folder instead

Without fzf (Fallback Mode)

If fzf is not available, the plugin shows a list and prompts for input:

dev
# → Available projects in ~/dev:
# → api-server
# → config.json
# → frontend-app
# → script.sh
# → Enter project/file name (or press Enter for root directory): new-file.txt

Smart Filtering

The interface adapts based on the flags used:

• Regular navigation: Shows both files and directories
• With -c or -cg: Shows only directories (prevents file creation conflicts)

---

🔧 Roadmap

• Add flag to create new project directories.
• Add flag to open projects directly in editors.
• Add support for multiple editors (VS Code, Cursor, Windsurf, Sublime, Vim, etc.).
• Add fuzzy search for project names with fzf integration.
• Add configuration file system for customizable settings.
• Add aliases or shortcuts per project.
• Add project templates for new directory creation.

---

📜 License

GNU General Public License v3.0 — See LICENSE for details.