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/
├── .agents/ # Project-local AI skills and helper scripts
├── .github/ # CI workflows
├── brew/ # Homebrew Brewfile
├── config/ # App configs (claude, gemini, ghostty, opencode, yazi)
├── docs/ # Documentation, plans, and lessons
├── external/ # External source assets (aliases, prompt helpers)
├── git/ # Git configuration
├── manual/ # Manual install configs (see manual/README.md)
├── misc/ # Other configs (tmux, vimrc, vim runtime, etc.)
├── zsh/ # Zsh configuration (modular)
│ ├── core/ # Core functionality (PATH, completion, history, prompt)
│ ├── tools/ # Tool configurations (kubectl, git, fzf, etc.)
│ ├── aliases/ # Categorized aliases
│ ├── env.zsh # Early environment setup
│ └── rc.zsh # Main zsh entrypoint
├── AGENTS.md # AI agent guide
├── install.sh # Installation script
├── Makefile # Common setup, test, and maintenance commands
├── secrets.example # Template for local secrets
└── 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
make install also manages Claude and OpenCode paths, including
~/.claude/settings.json and paths under ~/.config/opencode/, including
opencode.json, oh-my-opencode-slim.json, commands/, agents/,
oh-my-opencode-slim/. If those paths already exist, the installer moves them into
~/.dotfiles_backup/... before creating symlinks.
After installation, edit config/claude/settings.json in this repo, not ~/.claude/settings.json.
See available commands: make help
🛠️ Main Tools
Kubernetes & Container
- kubectl (+ 800 aliases), k9s, helm, kustomize
Git & Version Control
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
🎯 Design Principles
-
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
-
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
-
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