Modern ZSH Theme

October 20, 2025 · View on GitHub

License: MIT Platform Shell PRs Welcome

A sleek and modern ZSH theme that automatically adapts to light and dark terminal themes. This theme provides a clean and informative prompt with git integration, command execution time, virtualenv awareness, and a beautiful rainbow directory path.

Table of Contents

Prompt Layout

Here’s how the prompt looks in action:

Theme Preview Dark Theme Preview Light

Legend

  • 👤 ravindra@~

    • ravindra = username (yellow)
    • ~ = home directory root (rainbow-colored)

  • 🌈 ~/Projects/zsh-modern-theme Rainbow-colored directory path for quick readability.

    • Each path segment = different color
    • ~ replaces $HOME and is rainbow-colored

  • 🐍 env:(.venv) Active Python virtual environment.

    • Shown only if a venv is active

  • 🔄 git:(master) ✓ Git integration:

    • Branch name (purple)
    • ✓ = clean repo (green)
    • ✗ = dirty repo (red)

  • ⏱️ 11:57:08 ⌛ 0s Right-aligned time and command execution duration:

    • Current time (%*)
    • ⌛ + elapsed time of last command
    • Falls back to [s] if Unicode isn’t supported

  • ❯ Prompt symbol:

    • Green ❯ = last command succeeded
    • Red ❯ = last command failed

Key Features (shortened)

  • 🌗 Auto light/dark detection
  • 🌈 Rainbow directory path with ~ for home
  • 🔄 Git branch + status (✓/✗)
  • ⏱️ Time + command duration (⌛ / [s])
  • 🐍 Python venv awareness
  • 👤 Username context
  • ❌ Success/error colored prompt arrow
  • 🎨 Color-optimized for common terminals (iTerm2, Apple Terminal, GNOME, Konsole, tmux/screen)

Quick Start

# 1. Clone the repository
git clone https://github.com/BadRat-in/zsh-modern-theme.git $HOME/.zsh/zsh-modern-theme

# 2. Add to your ~/.zshrc
echo 'source $HOME/.zsh/zsh-modern-theme/zsh-modern-theme.zsh' >> ~/.zshrc

# 3. Reload your shell
source ~/.zshrc

That's it! The theme will automatically create a config file at ~/.config/zsh-modern-theme/.config.json with default settings.

Installation

Manual Installation

  1. Clone the repository:
git clone https://github.com/BadRat-in/zsh-modern-theme.git $HOME/.zsh/zsh-modern-theme
  1. Source it in your ~/.zshrc:
source $HOME/.zsh/zsh-modern-theme/modern-theme.zsh
  1. Reload ZSH:
source ~/.zshrc

Customization

You can customize the theme through configuration files and by overriding variables in your ~/.zshrc.

Configuration File

The theme stores its configuration in ~/.config/zsh-modern-theme/.config.json. The configuration file is automatically created with default settings when you first load the theme.

Configuration file location: ~/.config/zsh-modern-theme/.config.json

How Configuration Works

  1. First Time Users: When you first load the theme, it automatically creates the config directory and file with sensible defaults
  2. If Deleted: If you delete the config file, it will be regenerated with defaults the next time you reload your shell
  3. Custom Settings: Any changes you make to the config file persist across shell sessions

Default Configuration

Here's what the default configuration looks like:

{
  "_comment": "ZSH Modern Theme Configuration",
  "_description": "This file is automatically generated with default settings. Edit values to customize your prompt.",

  "duration_format": "auto",
  "_duration_format_options": {
    "auto": "Automatically formats based on duration (< 60s shows seconds, >= 60s shows m:s or h:m:s)",
    "seconds": "Always show in seconds only (e.g., 83s)",
    "minutes-seconds": "Always show in minutes:seconds format (e.g., 1:23)"
  },

  "git": {
    "clean_symbol": "✓",
    "dirty_symbol": "✗",
    "show_status": true,
    "_symbols_info": "Use Unicode symbols or ASCII alternatives (e.g., '+', 'x', '*')"
  },

  "virtualenv": {
    "show": true,
    "_info": "Show Python virtual environment name in prompt"
  },

  "time": {
    "show": true,
    "show_command_duration": true,
    "timer_icon": "⌛",
    "_timer_icon_options": "Examples: '⌛', '⏱️', '⏲️', '[t]', '(s)'"
  }
}

Note: Fields starting with _ are comments for documentation and are ignored by the parser.

Configuration Options

1. Duration Format

Control how command execution time is displayed:

"duration_format": "auto"

Available options:

  • "auto" (default) - Automatically formats based on duration:

    • Less than 60 seconds: Shows as 25s
    • 60-3599 seconds: Shows as 2m 35s
    • 3600+ seconds: Shows as 1h 15m 30s

  • "seconds" - Always displays in seconds only:

    • Example: 83s (even for durations over 1 minute)
    • Useful for precise timing and scripting

  • "minutes-seconds" - Always displays in MM:SS format:

    • Example: 0:45 for 45 seconds, 1:23 for 83 seconds
    • More user-friendly for longer commands
    • Automatically zero-pads seconds (e.g., 2:05)

📖 See detailed duration format examples →

2. Git Configuration

Customize git status display:

"git": {
  "clean_symbol": "✓",
  "dirty_symbol": "✗",
  "show_status": true
}

Options:

  • clean_symbol: Symbol shown when git repo is clean (default: "✓")

    • Examples: "✓", "✔", "+", "ok", "clean"

  • dirty_symbol: Symbol shown when git repo has changes (default: "✗")

    • Examples: "✗", "✘", "x", "*", "dirty"

  • show_status: Show/hide git status indicator (default: true)

    • Set to false to hide the clean/dirty symbol (only shows branch name)

Example - ASCII symbols:

"git": {
  "clean_symbol": "+",
  "dirty_symbol": "x",
  "show_status": true
}
3. Virtual Environment

Control Python virtualenv display:

"virtualenv": {
  "show": true
}

Options:

  • show: Show/hide virtualenv in prompt (default: true)
    • Set to false to hide env:(venv_name) from prompt
4. Time Display

Configure time and duration display:

"time": {
  "show": true,
  "show_command_duration": true,
  "timer_icon": "⌛"
}

Options:

  • show: Show/hide current time (default: true)

    • Set to false to hide HH:MM:SS from prompt

  • show_command_duration: Show/hide command execution duration (default: true)

    • Set to false to hide duration timer

  • timer_icon: Icon displayed before duration (default: "⌛" or "[s]" for non-Unicode terminals)

    • Unicode examples: "⌛", "⏱️", "⏲️", "⏰", "🕐"
    • ASCII examples: "[t]", "(s)", "[s]", "T:"

Example - Minimal time display:

"time": {
  "show": false,
  "show_command_duration": true,
  "timer_icon": "[s]"
}

This shows only command duration without current time.

Example Configurations

Minimal prompt (no time info):

{
  "duration_format": "auto",
  "git": {
    "clean_symbol": "✓",
    "dirty_symbol": "✗",
    "show_status": true
  },
  "virtualenv": {
    "show": true
  },
  "time": {
    "show": false,
    "show_command_duration": false,
    "timer_icon": "⌛"
  }
}

ASCII-only symbols:

{
  "duration_format": "seconds",
  "git": {
    "clean_symbol": "+",
    "dirty_symbol": "x",
    "show_status": true
  },
  "virtualenv": {
    "show": true
  },
  "time": {
    "show": true,
    "show_command_duration": true,
    "timer_icon": "[s]"
  }
}

Focus on command duration:

{
  "duration_format": "minutes-seconds",
  "git": {
    "clean_symbol": "✓",
    "dirty_symbol": "✗",
    "show_status": false
  },
  "virtualenv": {
    "show": false
  },
  "time": {
    "show": false,
    "show_command_duration": true,
    "timer_icon": "⏱️"
  }
}

Applying Configuration Changes

After editing the configuration file, reload your shell:

source ~/.zshrc

Or simply start a new terminal session.

Colors

The theme auto-selects colors, but you can override:

# Dark theme
typeset -g PROMPT_COLOR=$'%F{033}'    # Bright blue
typeset -g USER_COLOR=$'%F{226}'      # Bright yellow

# Light theme
typeset -g PROMPT_COLOR=$'%F{033}'    # Dark blue
typeset -g USER_COLOR=$'%F{094}'      # Dark gold

You can also redefine the rainbow path colors:

typeset -g RAINBOW_COLORS=(
  $'%F{208}'  # orange
  $'%F{220}'  # yellow
  $'%F{082}'  # green
  $'%F{039}'  # blue
  $'%F{171}'  # purple
  $'%F{033}'  # deep blue
)

Git Symbols

typeset -g GIT_CLEAN_SYMBOL='✓'
typeset -g GIT_DIRTY_SYMBOL='✗'
typeset -g GIT_SUFFIX=''   # optional suffix after branch name

FAQ

What happens on first install?

The theme automatically creates a configuration file at ~/.config/zsh-modern-theme/.config.json with default settings. No manual setup required!

What if I delete the config file?

No problem! The theme will automatically regenerate it with default settings the next time you reload your shell. Your prompt will continue working seamlessly.

Can I use ASCII symbols instead of Unicode?

Yes! Edit your config file and change symbols to ASCII alternatives:

{
  "git": {
    "clean_symbol": "+",
    "dirty_symbol": "x"
  },
  "time": {
    "timer_icon": "[s]"
  }
}

How do I hide certain elements?

Set the corresponding show option to false in your config file:

{
  "virtualenv": { "show": false },
  "time": { "show": false }
}

Where is the config file located?

~/.config/zsh-modern-theme/.config.json

Does it work with tmux/screen?

Yes! The theme includes special detection for terminal multiplexers and adapts accordingly.

What terminals are supported?

The theme works with all modern terminals and has been tested on:

  • iTerm2 (macOS)
  • Apple Terminal (macOS)
  • GNOME Terminal (Linux)
  • Konsole (Linux)
  • Alacritty
  • Kitty
  • tmux/screen

How do I reload my configuration?

After editing the config file, simply reload your shell:

source ~/.zshrc

Or start a new terminal session.

Contributing

Contributions welcome! PRs and issues encouraged.

See CONTRIBUTING.md for guidelines.

License

MIT License – see LICENSE.

Author

Ravindra Singh GitHub: @BadRat-in

Acknowledgments

  • Inspired by various ZSH themes in the community
  • Thanks to the Oh My Zsh project

Additional Resources