Shihyu's dotfiles

Modular macOS dotfiles configuration focused on performance and maintainability.

✨ Features

• ⚡ Lightning Fast: < 0.5s shell startup time
• 📁 Modular Design: Clear structure organized by functionality
• 🔗 Symlink Mode: Changes take effect immediately, no sync needed
• 🤖 AI-Friendly: Includes AGENTS.md and dedicated skill for easy AI-assisted maintenance
• 🎯 Lazy Loading: Dev tools (nvm, pyenv, sdkman) loaded on demand
• 📝 Comprehensive Documentation: All tools documented with sources and purposes

📂 Structure

dotfiles/
├── zsh/                # Zsh configuration (modular)
│   ├── core/           # Core functionality (PATH, completion, history, prompt)
│   ├── tools/          # Tool configurations (kubectl, git, fzf, etc.)
│   └── aliases/        # Categorized aliases
├── git/                # Git configuration
├── brew/               # Homebrew Brewfile
├── manual/             # Manual install configs (see manual/README.md)
│   └── karabiner/      # Karabiner-Elements rules
├── misc/               # Other configs (tmux, vimrc, vim runtime, etc.)
├── external/           # External source assets (aliases, prompt helpers)
├── docs/               # Documentation
├── AGENTS.md           # AI agent guide
├── install.sh          # Installation script
└── uninstall.sh        # Uninstallation script

🚀 Quick Start

AI-assisted Setup

Tell Agent:

Fetch and follow instructions from https://raw.githubusercontent.com/shihyuho/dotfiles/refs/heads/main/docs/INSTALL.md

Manual Setup

DOTFILES_DIR="${DOTFILES_DIR:-$HOME/.config/dotfiles}"

# Clone repository
git clone https://github.com/shihyuho/dotfiles.git "$DOTFILES_DIR"
cd "$DOTFILES_DIR"

# Complete setup (symlinks + Homebrew packages)
make setup

# Or step by step:
make install  # Create symlinks only
make brew     # Install Homebrew packages only

# First-time setup: create local secrets file
cp "$DOTFILES_DIR/secrets.example" ~/.secrets
chmod 600 ~/.secrets
# Then edit ~/.secrets and set sensitive env vars

# Uninstall managed symlinks (optional)
make uninstall

# Restart shell
exec zsh

See available commands: make help

🛠️ Main Tools

Kubernetes & Container

• kubectl (+ 800 aliases), k9s, helm, kustomize

Git & Version Control

• git, lazygit, gh, ghq

Shell Enhancement

• fzf, zoxide, exa, ripgrep

Development Languages

• Go, Node.js (nvm), Python (pyenv), Java (sdkman)

See docs/TOOLS.md for complete tool list.

📖 Documentation

• AGENTS.md: AI agent guide (architecture principles, modification rules)
• docs/INSTALL.md: AI installation playbook
• docs/SETUP.md: Human installation guide
• docs/TOOLS.md: Tool list and sources

🎯 Design Principles

1. Performance First: Startup speed < 0.5s

   • Use fast-path defaults for common Homebrew prefixes with fallback detection for non-standard installs
   • Smart caching (completion, git info)
   • Lazy loading for dev tools

2. Modular: Organized by functionality, easy to maintain

   • Core configs (zsh/core/): Loaded in numeric order
   • Tool configs (zsh/tools/): Conditional loading
   • Dev tools (zsh/tools/dev/): Lazy loading

3. AI-Friendly:

   • Detailed AGENTS.md included
   • Config files include metadata (source, purpose, update date)
   • Dedicated skill: .agents/skills/dotfiles-manager/ (project-level)

🔧 Maintenance

Adding New Tools

# 1. Edit Brewfile
echo 'brew "tool-name"' >> brew/Brewfile

# 2. Install
make brew

# 3. Check status
make check-tool TOOL=tool-name

# 4. Test
make test

Testing & Verification

# Run all tests
make test

# Run CI-friendly tests
make test-ci

# Detailed startup analysis
make measure-startup

# Check specific tool
make check-tool TOOL=kubectl

Updating Configuration

Since using symlink mode, directly edit files in dotfiles repo:

DOTFILES_DIR="${DOTFILES_DIR:-$HOME/.config/dotfiles}"
vim "$DOTFILES_DIR/zsh/core/30-prompt.zsh"
exec zsh  # Reload
make test  # Verify changes

Uninstalling Dotfiles

# Remove only symlinks managed by this repository
make uninstall

Updating External Aliases

# Update all
make update-aliases

# Update specific
make update-aliases TARGET=kubectl

🤖 AI Collaboration

This dotfiles is designed for AI collaboration:

1. Read AGENTS.md: Understand architecture principles and modification rules
2. Use dotfiles-manager skill: Provides standardized operation workflows
3. Follow testing standards: Test startup speed and functionality after each modification

AI agents can safely help with:

• Adding new tool configurations
• Updating external alias files
• Optimizing startup speed
• Cleaning up unused tools

📊 Performance

• Startup time: 0.16-0.22s (tested on M2 MacBook Air)
• Target: every run < 0.5s
• Lazy loading saves: ~200ms (nvm + pyenv + sdkman)

📜 License

MIT