A comprehensive, automated macOS development environment with modern tools and configurations
- 🚀 Quick Start
- ⚡ What's Included
- 🔧 Installation
- 📁 Configuration Structure
- 🛠️ Tools & Applications
- 🎨 Customization
- 🤖 Claude Code Workflow
- 🔄 Management
- 💡 Pro Tips
- 🔍 Troubleshooting
- macOS (this setup is designed for macOS only)
- Command Line Tools for Xcode
- Internet connection for downloading tools
# Clone and install core components (use bash explicitly for color support)
cd ~ && git clone https://github.com/yoaquim/.dotfiles.git && cd .dotfiles && bash ./install.sh# Setup Node.js and Python environments (use bash explicitly)
bash ./post-setup.sh# Setup AstroNvim for Neovim (requires SSH keys configured for GitHub)
bash ./setup-astronvim.shNote: Step 3 requires SSH keys (
~/.ssh/gitand~/.ssh/git.pub) to be configured and added to your GitHub account. The script will check for these before proceeding.
# 1. Clone the repository
cd ~/
git clone https://github.com/yoaquim/.dotfiles.git
# 2. Run core installation script (use bash explicitly for colors)
cd ~/.dotfiles
bash ./install.sh
# 3. Setup language environments (use bash explicitly)
bash ./post-setup.sh
# 4. Setup AstroNvim (requires SSH keys for GitHub)
bash ./setup-astronvim.sh- Modern Bash with vim-style editing
- 50+ custom aliases for productivity
- Advanced functions (directory bookmarking, git workflows)
- Eternal history with timestamps
- Base16 color schemes integration
- Kitty Terminal - GPU-accelerated with ligatures
- Tmux - Terminal multiplexer with custom key bindings
- Tmux Powerline - Beautiful two-line status bar
- JetBrains Mono Nerd Font - Programming font with icons
- AstroNvim - Modern Neovim distribution
- Git - Enhanced with git-delta and custom aliases
- Node.js - Latest LTS via nvm
- Python - Latest stable via pyenv
- Claude Code - AI-powered coding assistant with custom workflow
- Homebrew - Package manager with curated app list
- TPM - Tmux plugin manager
- Language Managers - nvm, pyenv, pipx
- Productivity: Alfred, Todoist, Rectangle, Hammerspoon
- Development: Docker, Postman, VS Code alternatives
- Communication: Slack, WhatsApp
- Creative: Adobe Creative Cloud, Spotify
The install.sh script provides several installation modes:
| Command | Description |
|---|---|
./install.sh |
Full installation (default) |
./install.sh --reinstall |
Reinstall configurations only |
./install.sh --force |
Force reinstall without prompts |
./install.sh --uninstall |
Remove all configurations |
./install.sh --help |
Show all options |
- Checks for macOS compatibility
- Verifies required directories and files
- Validates system dependencies
- Installs Homebrew if not present
- Updates package lists
- Configures PATH for current session
- Formulas: Development tools and utilities
- Casks: Desktop applications
- Fonts: Programming fonts with icon support
- Creates symbolic links to configuration files
- Backs up existing configurations
- Sets up directory structure
- Installs tmux plugin manager (TPM)
- Clones Base16 color schemes
- Installs latest Node.js LTS via nvm
- Installs latest Python via pyenv
- Configures default versions
- Links custom configurations
- Installs Claude Code CLI
- Completes environment setup
- Run
cd ~/.dotfiles/claude && ./setup.shafter Claude Code is installed - Symlinks skills, agents, practices, and settings into
~/.claude/
- Run
bash ./setup-astronvim.shafter SSH keys are configured - Checks for SSH keys (
~/.ssh/gitand~/.ssh/git.pub) - Clones AstroNvim template
- Links custom polish.lua and user.lua configurations
~/.dotfiles/
├── 📄 README.md # This comprehensive guide
├── 🚀 install.sh # Automated installation script
├── 🚀 post-setup.sh # Language environment setup script
├── 🚀 setup-astronvim.sh # AstroNvim setup script (requires SSH)
├── 🔧 change-shell.sh # Shell change helper script
├── 🙈 .gitignore # Git ignore rules
└── 📁 config/ # Configuration files
├── 🐚 bash/ # Bash shell configuration
│ ├── 📄 bash_profile # Main bash profile
│ ├── 📄 bash_profile_aliases # Command aliases
│ ├── 📄 bash_profile_functions # Custom functions
│ ├── 📄 bash_profile_git # Git-specific configurations
│ ├── 📄 bash_profile_tools # Tool integrations
│ ├── 📄 bash_profile_ssh # SSH agent configuration
│ ├── 📄 bash_profile_local # Local machine settings (not in git)
│ └── 📄 README.md # Bash configuration guide
├── 🐱 kitty/ # Kitty terminal configuration
│ ├── 📄 kitty.conf # Terminal settings
│ ├── 📄 sample.conf # Sample configuration
│ └── 📄 README.md # Kitty user guide
├── 🖥️ tmux/ # Tmux configuration
│ ├── 📄 tmux.conf # Tmux settings
│ ├── 📁 plugins/ # Tmux plugins
│ └── 📄 README.md # Tmux user guide
├── 🔋 tmux-powerline/ # Tmux powerline theme
│ ├── 📄 config.sh # Powerline configuration
│ ├── 📁 themes/ # Visual themes
│ └── 📄 README.md # Powerline guide
├── 🚀 nvim/ # Neovim configuration
│ ├── 📄 polish.lua # AstroNvim customizations
│ ├── 📄 user.lua # Plugin configurations
│ └── 📄 README.md # AstroNvim user guide
├── 🔨 hammerspoon/ # Hammerspoon automation
│ ├── 📄 init.lua # Hotkey and automation config
│ └── 📄 README.md # Hammerspoon user guide
├── 🌐 rclone/ # rclone cloud storage configuration
│ ├── 📄 rclone.conf # Remote config (no secrets)
│ ├── 📄 mount-cave.sh # Mount script
│ ├── 📄 com.rclone.cave.plist # LaunchAgent for auto-mount
│ └── 📄 README.md # rclone setup guide
├── 🔐 ssh/ # SSH configuration
│ └── 📄 config # SSH config file
├── 📁 git/ # Git local configuration
│ └── 📄 config.local # Machine-specific git settings (not in git)
└── 📄 gitconfig # Git configuration
└── 📁 claude/ # Claude Code global configuration
├── 📄 setup.sh # Claude setup script (symlinks into ~/.claude/)
├── 📄 settings.json # Claude Code settings + hooks
├── 📁 agents/ # Autonomous agent definitions
│ └── 📄 runner.md # Unified implementation runner
├── 📁 scripts/ # Reusable scripts for skills + hooks
│ ├── 📄 resolve-project.sh # Git repo → Linear team/project
│ ├── 📄 resolve-label.sh # Subject text → issue label
│ ├── 📄 validate-title.sh # Title style validation
│ ├── 📄 check-pr-reviews.sh # Machine review status (Codex/CodeRabbit)
│ └── 📄 repo-projects.json # Repo → Linear project mapping
├── 📁 hooks/ # Event-driven automation
│ ├── 📄 inject-practices.sh # Auto-inject practices at runner startup
│ ├── 📄 lint-spec.sh # Scope check on sketch/spec writes
│ ├── 📄 validate-issue.sh # Style check after Linear issue creation
│ ├── 📄 validate-commit.sh # Commit message style check
│ ├── 📄 validate-pr.sh # PR title style check
│ └── 📄 notify-done.sh # macOS notification when runner finishes
├── 📁 practices/ # Development practice guides
│ ├── 📄 INDEX.md # Practice index with detect rules
│ ├── 📄 tdd.md # TDD (always active)
│ ├── 📄 django.md # Django
│ ├── 📄 docker.md # Docker
│ ├── 📄 react.md # React
│ └── 📄 tailwind.md # Tailwind
└── 📁 skills/ # Custom Claude Code skills
├── 📁 setup/ # /setup — init project
├── 📁 sketch/ # /sketch — lightweight local spec
├── 📁 spec/ # /spec — Linear feature spec (ZeeSpec)
├── 📁 issue/ # /issue — single Linear issue
├── 📁 dispatch/ # /dispatch — spawn runner (tickets or sketches)
├── 📁 pr/ # /pr — review, fix, create PR
└── 📁 gh-stack/ # /gh-stack — stacked branches/PRs
After installation, configurations are linked to standard locations:
| Source | Target | Purpose |
|---|---|---|
config/bash/bash_profile |
~/.bash_profile |
Main bash configuration |
config/bash/bash_profile |
~/.bashrc |
Bash initialization |
config/bash/ |
~/.config/bash/ |
Bash configuration directory |
config/tmux/ |
~/.config/tmux/ |
Tmux configuration |
config/kitty/ |
~/.config/kitty/ |
Kitty terminal configuration |
config/gitconfig |
~/.gitconfig |
Git configuration |
config/nvim/polish.lua |
~/.config/nvim/lua/polish.lua |
Neovim customizations |
config/nvim/user.lua |
~/.config/nvim/lua/plugins/user.lua |
Neovim plugins |
config/hammerspoon/ |
~/.hammerspoon/ |
Hammerspoon automation |
config/rclone/ |
~/.config/rclone/ |
rclone cloud storage |
config/ssh/config |
~/.ssh/config |
SSH configuration |
claude/skills/ |
~/.claude/skills/ |
Claude Code skills (via claude/setup.sh) |
claude/agents/ |
~/.claude/agents/ |
Claude Code agents (via claude/setup.sh) |
claude/practices/ |
~/.claude/practices/ |
Claude Code practices (via claude/setup.sh) |
claude/settings.json |
~/.claude/settings.json |
Claude Code settings (via claude/setup.sh) |
| Tool | Purpose | Configuration |
|---|---|---|
| Bash | Modern shell with enhancements | config/bash/ |
| Git | Version control with aliases | config/gitconfig |
| Tmux | Terminal multiplexer | config/tmux/ |
| Neovim | Modern text editor | config/nvim/ |
| Kitty | GPU-accelerated terminal | config/kitty/ |
| Hammerspoon | macOS automation and hotkeys | config/hammerspoon/ |
| Claude Code | AI coding assistant with workflow | claude/ |
| Tool | Purpose | Auto-Setup |
|---|---|---|
| Homebrew | macOS package manager | ✅ |
| NVM | Node.js version manager | ✅ |
| Pyenv | Python version manager | ✅ |
| TPM | Tmux plugin manager | ✅ |
- Alfred - Productivity app and launcher
- Todoist - Task management
- Rectangle - Window management
- Postman - API testing tool
- Claude - AI coding assistant
- 1Password - Password manager
Note: Docker is currently disabled in the installation due to package conflicts. Install manually with
brew install --cask dockerif needed.
- Slack - Team communication
- WhatsApp - Messaging
- Adobe Creative Cloud - Design tools
- Spotify - Music streaming
- Notion - Note-taking and productivity
- Google Chrome - Web browser
- TlDr - Simplified man pages
- Bottom - System monitor
- Lazygit - Git TUI
- Ripgrep - Fast text search
- fd - Fast file finder
- Tree-sitter - Parser generator
- Go - Programming language
- gdu - Disk usage analyzer
- Calibre - E-book management
- Quarto - Scientific publishing
- Folx - Download manager
- Hidden Bar - Menu bar management
The setup uses Base16 color schemes for consistent theming:
- Location:
~/.config/base16-shell/ - Usage:
base16_<theme-name>in terminal - Integration: Works with tmux, vim, and shell
Create machine-specific settings:
# Edit local bash settings
nvim ~/.config/bash/bash_profile_local
# Add personal aliases, functions, exports
export MY_CUSTOM_VAR="value"
alias my_alias="command"# Edit powerline configuration
nvim ~/.config/tmux-powerline/config.sh
# Customize segments, colors, and layout# Edit kitty configuration
nvim ~/.config/kitty/kitty.conf
# Customize fonts, colors, and behavior# Inside tmux session
` I # Install plugins
` U # Update plugins
` alt + u # Uninstall plugins# Inside neovim
:Lazy # Open plugin managerCustom Claude Code configuration with skills, agents, hooks, and practices.
cd ~/.dotfiles/claude && ./setup.shSymlinks skills, agents, hooks, scripts, practices, and settings into ~/.claude/.
| Skill | Purpose |
|---|---|
/setup |
Init project: CLAUDE.md, git, hooks, deps |
/sketch <name> |
Lightweight local spec (ZeeSpec-lite) |
/spec |
Linear feature spec with sub-issues (ZeeSpec) |
/issue |
Single well-formed Linear issue |
/dispatch <id|name> |
Spawn runner from Linear ticket or sketch |
/pr |
Review, fix, create PR |
/gh-stack |
Stacked branches and PRs |
Local (no Linear):
/sketch jwt-auth → /dispatch jwt-auth → runner → /pr
Linear:
/spec → /dispatch ENG-142 → runner → /pr
| Hook | Trigger | Purpose |
|---|---|---|
inject-practices.sh |
Runner SessionStart | Auto-detect and inject practices |
lint-spec.sh |
Write/Edit on sketches | Scope check (>8 steps, >10 files) |
validate-issue.sh |
Linear save_issue |
Issue title/description style |
validate-commit.sh |
git commit |
Commit message style |
validate-pr.sh |
gh pr create |
PR title style |
notify-done.sh |
Stop | macOS notification when session ends |
One unified runner agent handles all dispatched work. On completion: pushes, creates PR via /pr, iterates on Codex/CodeRabbit comments until machine reviews are green.
Auto-detected at runner startup via inject-practices.sh. TDD is always active; Django, Docker, React, Tailwind activate based on project files.
Edit in ~/.dotfiles/claude/ — changes apply globally via symlinks.
# Navigate to dotfiles directory
cd ~/.dotfiles
# Pull latest changes
git pull
# Reinstall configurations
./install.sh --reinstallThe installation script automatically creates backups:
- Format:
filename.backup.YYYYMMDD_HHMMSS - Location: Same directory as original file
- Restore: Manually copy backup over current file
# Update only specific configurations
./install.sh --reinstall
# Force update without prompts
./install.sh --force
# Update specific tools
brew update && brew upgrade# Use directory bookmarking
mark project # Bookmark current directory
j project # Jump to bookmarked directory
marks # List all bookmarks# Quick commit and push
gup "commit message" # Commit and push in one command
# Branch management
gcg feature # Checkout first branch matching "feature"
gbcp # Copy current branch name to clipboard# Create development session
tmux new-session -s dev -d
tmux send-keys -t dev 'cd ~/project && nvim' Enter
tmux split-window -t dev -h
tmux send-keys -t dev 'npm run dev' Enter
tmux attach -t dev# Clone on different machines
git clone https://github.com/yoaquim/.dotfiles.git
# Customize per machine
echo "export HOST_SPECIFIC_VAR='value'" >> ~/.config/bash/bash_profile_local
# Machine-specific git settings (e.g., CodeRabbit machineId)
nvim ~/.config/git/config.local# Add new tools to bash_profile_tools
echo 'eval "$(tool init bash)"' >> ~/.config/bash/bash_profile_tools
# Reload configuration
sb # Source bash profile- Create tmux session for project
- Use directory bookmarking for quick access
- Leverage git aliases for efficient version control
- Use kitty tabs for different contexts
- Local: Full development environment
- Remote: Use kitty's SSH integration
- Containers: Docker development workflow
# Check system compatibility
uname -a
# Install command line tools
xcode-select --install
# Try manual installation
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"# Add homebrew bash to allowed shells
sudo sh -c 'echo /opt/homebrew/bin/bash >> /etc/shells'
# Change default shell
chsh -s /opt/homebrew/bin/bash
# Verify change
echo $SHELL# Check tpm installation
ls -la ~/.config/tmux/plugins/tpm
# Reinstall tpm
rm -rf ~/.config/tmux/plugins/tpm
git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm
# Install plugins in tmux
` I# Check AstroNvim installation
ls -la ~/.config/nvim
# Verify symlinks
ls -la ~/.config/nvim/lua/polish.lua
ls -la ~/.config/nvim/lua/plugins/user.lua
# Reinstall AstroNvim (requires SSH keys)
bash ./setup-astronvim.sh --force# Check SSH keys exist
ls -la ~/.ssh/git*
# Test GitHub SSH connection
ssh -T git@github.com
# If SSH is not configured, generate keys
ssh-keygen -t ed25519 -f ~/.ssh/git -C "your_email@example.com"
# Add key to ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/git
# Add public key to GitHub: https://github.com/settings/keys
cat ~/.ssh/git.pub
# Then retry AstroNvim setup
bash ./setup-astronvim.sh# List installed fonts
brew list --cask | grep font
# Install missing fonts
brew install --cask font-jetbrains-mono-nerd-font
# Check font in terminal
echo "Testing font: 🔥 → ← ↑ ↓"# Update system
brew update && brew upgrade
# Update configurations
cd ~/.dotfiles && git pull && ./install.sh --reinstall
# Update language versions
nvm install --lts
pyenv install --list | grep -E '^\s*3\.[0-9]+\.[0-9]+$' | tail -1# Clean homebrew
brew cleanup
# Clean old backups
find ~ -name "*.backup.*" -type f -mtime +30 -delete
# Clean tmux sessions
tmux list-sessions | grep -v attached | cut -d: -f1 | xargs -t -n1 tmux kill-session -t- Update
install.shwith new package - Add configuration to appropriate
config/directory - Update README with new tool documentation
- Test installation on clean system
- Fork repository for personal modifications
- Create feature branch for changes
- Test thoroughly before merging
- Document changes in README
- Bash Configuration Guide - Complete bash setup
- Kitty Terminal Guide - Terminal customization
- Tmux User Guide - Terminal multiplexer
- Tmux Powerline Guide - Status line setup
- AstroNvim Guide - Neovim configuration
- Hammerspoon Guide - macOS automation setup
- rclone Cave Guide - WebDAV cloud storage mount
- Homebrew Documentation - Package manager
- Base16 Colors - Color schemes
- AstroNvim Documentation - Neovim distribution
- Tmux Wiki - Terminal multiplexer
💡 Tip: After installation, run
source ~/.bash_profileor start a new terminal session to activate all configurations. Use the individual README files in each config directory for detailed usage instructions!
Last updated: March 2026