A comprehensive, automated dotfiles management system for macOS development environments. Features a powerful CLI tool for setup, maintenance, and AI-powered development insights.

This repository contains my personal development environment configuration, managed through a custom CLI tool called dot. It uses GNU Stow for symlink management, Homebrew for package installation, and includes configurations for Fish shell, Neovim, Tmux, Git, and other essential development tools.

• 🚀 One-command setup - Complete development environment in minutes
• 🤖 AI Integration - pi for AI assistance
• 📦 Resilient Package Management - Continues installation even if packages fail
• 🔍 Health Monitoring - Comprehensive environment diagnostics
• 🛠️ Modular Design - Separate work and personal configurations

# Clone the repository
git clone https://github.com/dmmulroy/.dotfiles.git ~/.dotfiles
cd ~/.dotfiles

# Full setup (installs everything)
./dot init

# Or customize the installation
./dot init --skip-ssh --skip-font

After installation, the dot command will be available globally for ongoing management. Running dot without arguments shows help.

~/.dotfiles/
├── dot                 # Main CLI tool
├── home/              # Configuration files (stowed to ~)
│   ├── .config/
│   │   ├── fish/      # Fish shell configuration
│   │   ├── git/       # Git configuration
│   │   ├── nvim/      # Neovim configuration
│   │   ├── tmux/      # Tmux configuration
│   │   └── ...
│   └── .ideavimrc     # IntelliJ IDEA Vim config
├── packages/
│   ├── bundle         # Base Brewfile
│   └── bundle.work    # Work-specific packages
├── CLAUDE.md          # Instructions for AI assistants
└── README.md          # This file

The dot command is a comprehensive management tool for your dotfiles. It handles everything from initial setup to ongoing maintenance and provides AI-powered insights.

Complete environment setup with all tools and configurations.

# Full installation
dot init

# Skip SSH key generation
dot init --skip-ssh

# Skip font installation  
dot init --skip-font

# Skip both SSH and font setup
dot init --skip-ssh --skip-font

What it does:

1. Installs Homebrew (if not present)
2. Installs packages from Brewfiles
3. Creates symlinks with GNU Stow
4. Installs Bun runtime
5. Installs pi via the Vite+ tool registry
6. Generates SSH key for GitHub (optional)
7. Installs MonoLisa font (optional)
8. Sets up Fish shell with plugins

dot update

• Pulls latest dotfiles changes (auto-detects jj vs git)
• Updates Homebrew packages
• Re-stows configuration files
• Runs pi update to update pi and its configured packages
• Runs pi headlessly with /skill:sync-pocock-skills and waits for the checked-in Matt Pocock skills sync to complete

dot doctor

Comprehensive diagnostics including:

• ✅ Homebrew installation
• ✅ Essential tools (git, nvim, tmux, node, etc.)
• ✅ pi installation and core development tools
• ✅ Fish shell configuration
• ✅ PATH configuration
• ⚠️ Broken symlinks detection
• ⚠️ Missing dependencies

dot check-packages

Shows which packages are installed vs. missing from your Brewfiles.

dot retry-failed

Attempts to reinstall packages that failed during initial setup.

# Run 10 benchmarks (default)
dot benchmark-shell

# Run specific number of benchmarks
dot benchmark-shell -r 20

# Show verbose output with individual timings  
dot benchmark-shell -v

# Combine options
dot benchmark-shell -r 15 -v

Measures Fish shell startup performance with detailed analysis:

• High-precision timing via Python3 or Perl
• Performance assessment with color-coded results (excellent ≤50ms, good ≤100ms, fair ≤200ms)
• Optimization tips for slow performance
• Statistical analysis including average, min, max, and range
• Profiling guidance for detailed bottleneck identification

Example Output:

=> Fish Shell Startup Benchmark Results

Configuration:
  Shell: fish, version 4.0.2
  Runs: 10
  Test: Empty script execution

Performance Results:
  Average time: 0.061 seconds
  Fastest time: 0.048 seconds
  Slowest time: 0.078 seconds
  Time range:   0.030 seconds

Performance Assessment:
✓ Good startup performance (≤100ms)

dot completions

Generates comprehensive Fish shell completions for the dot command, including:

• All commands and subcommands
• Dynamic completions for installed packages
• Option completions with descriptions

dot edit

Opens the dotfiles directory in your default editor (defined by $EDITOR).

# Create/update symlinks for configuration files
dot stow

Re-creates symlinks from home/ directory to your home directory (~). Use this after editing configuration files.

# Install dot command globally (add to PATH)
dot link

# Remove global installation
dot unlink

Makes the dot command available from any directory by creating a symlink in /usr/local/bin or ~/.local/bin.

The system provides comprehensive package management through the dot package command and uses two Brewfiles for different contexts:

# List packages
dot package list              # List all packages
dot package list base         # List base packages only
dot package list work         # List work packages only

# Add packages
dot package add git           # Add git formula to base bundle
dot package add docker cask   # Add docker cask to base bundle  
dot package add kubectl brew work  # Add kubectl to work bundle

# Update packages
dot package update            # Update all installed packages
dot package update git        # Update specific package
dot package update all base   # Update only base bundle packages
dot package update all work   # Update only work bundle packages

# Remove packages
dot package remove git        # Remove git from any bundle
dot package remove docker base  # Remove docker from base bundle only

packages/bundle - Base packages for all machines:

• Development tools: neovim, tmux, fish, git
• CLI utilities: ripgrep, fd, fzf, starship
• Applications: Arc browser, Raycast, OrbStack
• AI tools: aider

packages/bundle.work - Work-specific additions:

• AWS/Kubernetes tools
• Enterprise development tools

• Auto-detection: Package type (brew vs cask) automatically detected
• Sorted maintenance: Packages kept alphabetically sorted within each type
• Installation integration: Adding packages installs them immediately
• Update flexibility: Can update all packages, specific packages, or by bundle
• Cleanup included: Update command includes Homebrew refresh and optional cleanup

• Fish Shell: Custom functions, environment variables, and plugin management via Fisher
• Neovim: Lua-based configuration with lazy.nvim plugin manager
• Tmux: Plugin management via TPM, session persistence, Vim-style navigation
• Git: Conditional work configuration, custom aliases, GPG signing

• GNU Stow: Manages symlinks from home/ to ~
• Modular Design: Separate configs for different tools
• Conditional Loading: Work-specific Git config for ~/Code/work/
• Plugin Managers: Each tool uses its own (lazy.nvim, TPM, Fisher)
• Error Resilience: Package installation continues despite individual failures
• jj Support: Auto-detects jj-managed repos and uses appropriate update commands

• macOS (Intel or Apple Silicon)
• Internet connection
• Terminal access

1. Clone repository:

   git clone https://github.com/dmmulroy/.dotfiles.git ~/.dotfiles
   cd ~/.dotfiles

2. Run installation:

   ./dot init

3. Restart shell or source Fish config:

   # In Fish shell
   source ~/.config/fish/config.fish
   
   # Or restart terminal

4. Verify installation:

   dot doctor

Method 1: Using package commands (recommended):

# Add package using the package command
dot package add new-tool             # Adds to base bundle
dot package add new-app cask         # Adds cask to base bundle
dot package add work-tool brew work  # Adds to work bundle

Method 2: Manual editing: Edit packages/bundle or packages/bundle.work:

# Add to packages/bundle
brew "new-tool"
cask "new-app"

Then run:

dot init  # or brew bundle --file=./packages/bundle

1. Edit files in home/ directory (not your actual home directory)
2. Re-stow changes: dot stow (or dot init for full setup)
3. Test configuration changes

The system automatically applies work-specific Git configuration for repositories under ~/Code/work/.

Command not found: dot

# Source Fish configuration
source ~/.config/fish/config.fish

# Or add to PATH manually
export PATH="$HOME/.dotfiles:$PATH"

Package installation failures:

# Check what failed
dot check-packages

# Retry failed packages
dot retry-failed

Broken symlinks:

# Diagnose issues
dot doctor

# Re-create symlinks
dot stow

pi installation issues:

# Ensure Vite+ is installed, then install pi from the tool registry
curl -fsSL https://vite.plus | bash
vp install -g @mariozechner/pi-coding-agent

• Run dot help for command overview
• Run dot <command> --help for specific command help
• Check dot doctor for environment issues
• Review logs in failed package files: packages/failed_packages_*.txt

1. Fork the repository
2. Create a feature branch
3. Make changes in the home/ directory structure
4. Test with dot doctor and dot check-packages
5. Submit a pull request

# Make modifications to dotfiles
# ...

# Test changes
dot doctor

# Re-stow if needed
dot stow

# Install only base packages, skip optional components
dot init --skip-ssh --skip-font

# Check what's missing
dot check-packages

# Install work packages later
brew bundle --file=./packages/bundle.work

# Generate Fish shell completions
dot completions

# Completions include dynamic suggestions for:
# - Package names when using package remove/update
# - All commands, subcommands, and options

This repository is for personal use. Feel free to fork and adapt for your own needs.

• GNU Stow for symlink management
• Homebrew for package management
• pi for AI assistance
• The dotfiles community for inspiration and best practices