Zsh Starship Config - npm Installer

Modern Zsh + Starship + Nerd Fonts setup via npm

A robust and feature-rich CLI installer that provides a complete Zsh, Starship, tmux, and development environment setup with advanced features like rollback, configuration management, and dry-run modes.

Features

✨ Comprehensive Installation: Zsh, Oh My Zsh, Starship, tmux, Nerd Fonts, eza, and modern tools
🎨 9 Tmux Themes: cobalt, green, blue, purple, orange, red, nord, everforest, gruvbox, cream
🔄 Rollback System: Undo changes if something goes wrong
💾 Backup Management: Automatic backups before modifications
🔧 Configuration Management: Persistent configuration with CLI and interactive modes
🎯 Dry-run Mode: Preview changes without applying them
📊 Status Monitoring: Real-time system health and component status
🎨 Clipboard Support: Native OSC 52 clipboard for Linux/Wayland with mouse support

Installation

Quick Install

# Install globally via npm
npm install -g @jaggerxtrm/xzsc

# Run installer
zsc install

Install Specific Components

# Install only Zsh and Starship
zsc install --only zsh --only starship

# Install tmux themes only
zsc install --only tmuxThemes

# Install with custom options
zsc install --font-type nerd --shell zsh

Usage

Basic Commands

# Show help
zsc help

# Show version
zsc --version

# Check installation status
zsc status

# Apply tmux theme
zsc theme nord

# Auto-detect session and apply theme
zsc theme --auto

# List available themes
zsc theme --list

# Manage configuration
zsc config --list

Advanced Usage

Dry-run Mode (Preview Changes)

# Preview installation without applying changes
zsc install --dry-run

# Preview theme application
zsc theme cobalt --preview

# Preview update
zsc update --dry-run

Component Filtering

# Install everything except fonts
zsc install --exclude fonts

# Update only specific components
zsc update --only starship --only tmux

# Update multiple specific components
zsc update tmux themes eza

Configuration Management

# Interactive configuration
zsc config

# Get configuration value
zsc config --get components.zsh.enabled

# Set configuration value
zsc config --set preferences.autoUpdate false

# List all configuration
zsc config --list

# Reset to defaults
zsc config --reset

# Export configuration
zsc config --export my-config.json

Backup and Rollback

# Create backup
zsc backup

# List rollback points
zsc rollback --list

# Rollback last change
zsc rollback

# Rollback multiple steps
zsc rollback --step 2

# Dry-run rollback
zsc rollback --dry-run

Component Reference

Available Components

Component	Description	Dependencies
`zsh`	Zsh shell and configuration	-
`ohMyZsh`	Oh My Zsh framework	zsh
`plugins`	Zsh plugins (autosuggestions, syntax-highlighting, etc.)	zsh, ohMyZsh
`starship`	Starship prompt	-
`fonts`	Nerd Fonts installation	-
`tmux`	Tmux terminal multiplexer	-
`tmuxPlugins`	Tmux plugins via TPM	tmux
`tmuxThemes`	Tmux color themes	tmux
`eza`	Modern ls replacement	-
`tools`	Modern tools (bat, ripgrep, fd, zoxide, fzf)	-
`statusline`	Claude Code status line configuration	starship
`zshrc`	Zsh configuration file	zsh, ohMyZsh, starship
`hooks`	Git hooks and automation	zsh

Aliases

You can use aliases instead of component names:

all - All components
full - All components (same as all)
minimal - zsh, starship, fonts, zshrc
dev - All components (same as all)
basic - zsh, ohMyZsh, plugins, starship, fonts, zshrc

Tmux Themes

Available Themes

Theme	Description	Auto-trigger
`cobalt`	Blue/gray professional theme	-
`green`	Green development theme	dev, code
`blue`	Blue research theme	research, doc
`purple`	Purple calm theme	-
`orange`	Orange warning theme	debug, test
`red`	Red urgent theme	prod, urgent
`nord`	Nord dark theme	-
`everforest`	Everforest green theme	-
`gruvbox`	Gruvbox retro theme	-
`cream`	Cream light theme	-

Auto-Theming

When you create tmux sessions, the theme is automatically applied based on the session name:

dev*, code* → green theme
research*, doc* → blue theme
debug*, test* → orange theme
prod*, urgent* → red theme

Tmux Configuration

The installer automatically configures tmux with:

Native clipboard (OSC 52): Works over SSH, no external tools needed
Enhanced tmux-yank: Improved copy/paste with mouse support
9 themes: Pre-configured color themes
Dual status bar: Current path and keybind cheatsheet
TPM plugins: tmux-sensible, tmux-resurrect, tmux-continuum
Auto reload: Configuration automatically reloaded after changes

Configuration

Configuration File

Configuration is stored in ~/.zsc/config.json:

{
  "version": "1.0.0",
  "components": {
    "zsh": {
      "enabled": true,
      "shell": "zsh",
      "configPath": "~/.zshrc",
      "plugins": ["zsh-autosuggestions", "zsh-syntax-highlighting", "zsh-history-substring-search"]
    },
    "starship": {
      "enabled": true,
      "configPath": "~/.config/starship.toml",
      "binaryPath": "~/.local/bin/starship"
    },
    "tmux": {
      "enabled": true,
      "configPath": "~/.tmux.conf",
      "themePath": "~/.tmux/themes.sh",
      "plugins": ["tmux-sensible", "tmux-resurrect", "tmux-continuum"],
      "tpmPath": "~/.tmux/plugins/tpm"
    }
  },
  "preferences": {
    "autoUpdate": true,
    "checkForUpdates": true,
    "createBackups": true,
    "backupPrefix": "backup",
    "keepBackups": 5,
    "parallelInstall": false
  },
  "paths": {
    "cacheDir": "~/.zsc/cache",
    "logsDir": "~/.zsc/logs",
    "backupDir": "~/.zsc/backups"
  }
}

Configuration Options

Option	Default	Description
`autoUpdate`	true	Automatically check for updates
`createBackups`	true	Create backups before modifications
`keepBackups`	5	Number of backups to keep
`backupPrefix`	'backup'	Prefix for backup files
`parallelInstall`	false	Run installations in parallel

Advanced Features

Dry-run Mode

Preview changes without applying them:

# Preview installation
zsc install --dry-run

# Preview theme application
zsc theme nord --preview

# Preview update
zsc update --dry-run

Dry-run mode shows:

What would be installed/updated
Files that would be created/modified
Commands that would be executed
Configuration changes that would be made

Rollback System

Undo changes if something goes wrong:

# List available rollback points
zsc rollback --list

# Rollback last change
zsc rollback

# Rollback multiple changes
zsc rollback --step 3

# Dry-run rollback
zsc rollback --dry-run

Rollback features:

Multi-step rollback support
Automatic backup creation before changes
Rollback point tracking
Safe restoration with verification

Backup Management

Create and manage backups:

# Create manual backup
zsc backup

# Backup with options
zsc backup --output ~/backups --compress

# Include data files in backup
zsc backup --include-data

# View backup statistics
zsc status

Examples

Complete Installation

# Full installation with all defaults
zsc install

# Non-interactive mode (for scripts/Docker)
zsc install --yes

# Verbose installation
zsc install --verbose

Selective Installation

# Minimal installation
zsc install minimal

# Install development tools only
zsc install tools

# Install tmux setup only
zsc install tmux tmuxPlugins tmuxThemes

# Exclude specific components
zsc install --exclude fonts

Update Workflow

# Update all installed components
zsc update

# Update specific components
zsc update starship tmux

# Update with backup creation
zsc update --yes

# Update in dry-run mode
zsc update --dry-run

Theme Management

# Apply specific theme to current session
zsc theme nord

# Apply theme to specific session
zsc theme cobalt myproject

# Auto-detect session
zsc theme --auto

# List all themes
zsc theme --list

# Preview theme without applying
zsc theme everforest --preview

Configuration Management

# Interactive configuration
zsc config

# Get specific configuration
zsc config --get preferences.autoUpdate

# Set specific configuration
zsc config --set preferences.parallelInstall true

# Delete configuration value
zsc config --delete components.tmux.enabled

# Export configuration
zsc config --export ~/zsc-config-backup.json

# Reset to defaults
zsc config --reset

Status Monitoring

# Show all status
zsc status

# Show specific component status
zsc status --only tmux

# Export status as JSON
zsc status --json

# Export status to file
zsc status --export ~/zsc-status.json

Error Recovery

# Check what failed
zsc status

# Rollback last changes
zsc rollback

# Retry installation with different options
zsc install --yes --verbose

Troubleshooting

Installation Issues

Issue: Permission denied errors

# Solution: Run with appropriate permissions or use sudo
sudo zsc install

# Or check file permissions
ls -la ~/.zshrc ~/.config/

Issue: Dependencies not found

# Solution: Check what's missing
zsc status

# Install missing dependencies
zsc install --only <missing-component>

Issue: Theme not applying

# Solution: Check tmux is running
echo $TMUX

# Check theme script exists
ls -la ~/.tmux/themes.sh

# Verify tmux configuration
tmux show-options -g | grep theme

Clipboard Issues

Issue: Clipboard not working over SSH

# Solution: OSC 52 clipboard works over SSH, verify:
# 1. Terminal setting: "set -s set-clipboard on"
# 2. Tmux config: "set -g set-clipboard on"
# 3. Check tmux-yank is installed: ls ~/.tmux/plugins/tpm/

Issue: tmux-yank not installing via TPM

# Manual install of tmux-yank
cd ~/.tmux/plugins/tpm
git clone https://github.com/tmux-plugins/tmux-yank

# Reload tmux config
tmux source-file ~/.tmux.conf

Rollback Issues

Issue: Rollback not working

# Check available rollback points
zsc rollback --list

# Verify rollback files exist
ls -la ~/.zsc/backups/

# Force rollback to specific point
zsc rollback --step 1 --force

Migration from Shell Script

If you're currently using the shell script installer (install.sh), here's how to migrate:

Before Migration

Backup current configuration:

zsc backup --output ~/migration-backup --compress

Check current installation:

zsc status

Uninstall shell-based components (if desired):

# Review what's installed
zsc status --json > current-config.json

Migration Process

# Fresh install with npm installer
zsc install

# This will:
# - Detect existing components
# - Update configuration
# - Preserve your customizations
# - Install missing components

After Migration

Verify installation:

zsc status

# Test core functionality
zsh -c 'echo $ZSH_VERSION'
starship --version
tmux -V

Test themes:

# List available themes
zsc theme --list

# Apply a theme
zsc theme nord

# Test clipboard
# Select text in tmux with mouse, press v to enter copy mode, press y to copy
# Paste with p in normal mode

Configuration sync:

# Review your configuration
zsc config --list

# Adjust if needed
zsc config --set preferences.autoUpdate false

System Requirements

Minimum Requirements

OS: Linux or macOS
Shell: Zsh (bash and fish support planned)
Node.js: v14.0.0 or higher
Package Manager: npm, yarn, or pnpm
Disk Space: ~100 MB for installation
Permissions: Ability to install system packages

Supported Distributions

Fedora: 35+ ✅
Ubuntu/Debian: All LTS versions ✅
Arch Linux: Tested ✅
WSL: Full support with clipboard enhancements ✅

Optional Dependencies

For enhanced features, the following are optional but recommended:

git: For version control and some features
curl: For downloading resources
tmux: For terminal multiplexing (optional but recommended)

Development

Project Structure

xzsc/
├── bin/
│   └── zsc.js              # Main CLI entry point
├── src/
│   ├── commands/              # Command handlers
│   │   ├── install.js
│   │   ├── update.js
│   │   ├── status.js
│   │   ├── theme.js
│   │   ├── config.js
│   │   ├── rollback.js
│   │   └── backup.js
│   └── utils/                 # Utility modules
│       ├── logger.js           # Logging with spinners
│       ├── error-handler.js    # Error handling & retry
│       ├── config-manager.js    # Configuration persistence
│       ├── component-manager.js # Component orchestration
│       ├── downloader.js       # File downloads
│       ├── backup.js          # Backup & restore
│       ├── paths.js           # Path management
│       └── system.js          # System detection
├── data/
│   ├── tmux.conf            # Tmux configuration
│   ├── starship.toml         # Starship prompt config
│   ├── themes.sh             # Tmux theme scripts
│   ├── zshrc                # Zsh configuration
│   └── ...                  # Other data files
├── scripts/
│   └── ...                  # Helper scripts
├── tests/
│   ├── setup.js             # Test setup utilities
│   ├── logger.test.js        # Logger unit tests
│   ├── error-handler.test.js # ErrorHandler unit tests
│   ├── manual-test.js        # Manual CLI tests
│   └── test-planning.md    # Test planning
├── package.json
├── jest.config.js
└── README.md

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm test -- --coverage

# Run specific test file
npm test -- logger.test.js

Contributing

Development Setup

# Clone repository
git clone https://github.com/Jaggerxtrm/xzsc.git
cd xzsc

# Install dependencies
npm install

# Run tests
npm test

# Link for development
npm link

Code Style

Use consistent formatting
Follow existing patterns
Add tests for new features
Update documentation

Submitting Changes

Create feature branch: git checkout -b feature/your-feature
Make changes and test: npm test
Commit changes: git commit -m "feat: your feature"
Push to GitHub: git push origin feature/your-feature
Create Pull Request

License

MIT License - Free to use and modify

Changelog

See CHANGELOG.md for version history and changes.

Support

GitHub Issues: https://github.com/Jaggerxtrm/xzsc/issues
Documentation: https://github.com/Jaggerxtrm/xzsc/wiki
Discussions: https://github.com/Jaggerxtrm/xzsc/discussions

Acknowledgments

Starship: https://starship.rs
Oh My Zsh: https://ohmyz.sh/
Tmux: https://github.com/tmux/tmux-wiki
Nerd Fonts: https://www.nerdfonts.com/
Tmux-yank: https://github.com/tmux-plugins/tmux-yank

Built with ❤️ for the developer community

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
.beads		.beads
.claude/tdd-guard/data		.claude/tdd-guard/data
.serena		.serena
bin		bin
data		data
scripts		scripts
src		src
tests		tests
.claude-statusline.sh		.claude-statusline.sh
.config-version		.config-version
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
EXAMPLES.md		EXAMPLES.md
QUICK_START.md		QUICK_START.md
README.md		README.md
RELEASE_NOTES_v2.0.md		RELEASE_NOTES_v2.0.md
UPGRADE.md		UPGRADE.md
VERSION		VERSION
install.sh		install.sh
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
starship-pure.toml		starship-pure.toml
starship.toml		starship.toml
update.sh		update.sh

Folders and files

Latest commit

History

Repository files navigation

Zsh Starship Config - npm Installer

Features

Installation

Quick Install

Install Specific Components

Usage

Basic Commands

Advanced Usage

Dry-run Mode (Preview Changes)

Component Filtering

Configuration Management

Backup and Rollback

Component Reference

Available Components

Aliases

Tmux Themes

Available Themes

Auto-Theming

Tmux Configuration

Configuration

Configuration File

Configuration Options

Advanced Features

Dry-run Mode

Rollback System

Backup Management

Examples

Complete Installation

Selective Installation

Update Workflow

Theme Management

Configuration Management

Status Monitoring

Error Recovery

Troubleshooting

Installation Issues

Clipboard Issues

Rollback Issues

Migration from Shell Script

Before Migration

Migration Process

After Migration

System Requirements

Minimum Requirements

Supported Distributions

Optional Dependencies

Development

Project Structure

Running Tests

Contributing

Development Setup

Code Style

Submitting Changes

License

Changelog

Support

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages