Modern ZSH Theme

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
• Key Features
• Quick Start
• Installation
• Customization
  • Configuration File
  • Duration Format
  • Git Configuration
  • Virtual Environment
  • Time Display
  • Example Configurations
  • Colors
  • Git Symbols
• FAQ
• Contributing
• License
• Author
• Additional Resources

Prompt Layout

Here’s how the prompt looks in action:

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

2. Source it in your ~/.zshrc:

source $HOME/.zsh/zsh-modern-theme/modern-theme.zsh

3. 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

• 📖 Detailed Duration Format Examples - Comprehensive examples of all duration formats
• 📖 Contributing Guide - Guidelines for contributing to the project
• 📖 Project Structure - Complete project organization and file descriptions
• 🧪 Configuration Test Suite - Test script to verify configuration loading
• 🧪 Duration Format Tests - Test script for duration formatting