Dotfiles

Personal macOS development environment managed with chezmoi.

Table of Contents

• Quick Start
• What's Included
• Core Tools
  • Priority 1: Essential Configuration
  • Priority 2: Supporting Tools
  • Priority 3: Supplementary Tools
• Documentation
  • Getting Started
  • Reference Guides
  • Workflows
  • Tool-Specific Documentation
• Key Features
  • Secrets Management
  • Multi-Machine Support
  • Automation Scripts
  • Quality Gates
• Common Tasks
  • Making Configuration Changes
  • Syncing Multiple Machines
  • Finding Keyboard Shortcuts
  • Troubleshooting Common Issues
• Manual Dependencies
• Chezmoi Quick Reference
  • Essential Commands
  • State Terminology
  • File Naming Conventions
• Secrets and Encryption
  • GPG Encryption
  • 1Password Integration
  • Pre-commit Secret Scanning
• GitHub Actions
• Neovim Configuration
• Support
  • Getting Help
  • Contributing
• License
• Acknowledgments

Quick Start

New to these dotfiles? Start here:

1. Installation Guide - Complete setup instructions for fresh macOS installation (~60 minutes)
2. Chezmoi Workflow - How to make configuration changes safely
3. Keymaps Reference - Find any keyboard shortcut across all tools
4. Troubleshooting - Common issues and solutions

What's Included

This repository contains configurations for a complete macOS development environment with:

• Shell: Fish with Starship prompt and 77+ custom functions
• Editor: Neovim with LSP, plugins, and extensive customization
• Window Management: Yabai + skhd + Karabiner for tiling and keyboard-driven workflow
• Terminal: Ghostty, Tmux, Zellij for multiplexing
• Git: Custom aliases, Delta diff viewer, lazygit TUI
• File Management: Yazi TUI file manager with custom keybindings
• Development Tools: Language servers, formatters, linters, and build tools
• Security: Pre-commit hooks with gitleaks, GPG encryption, secrets management

Core Tools

Priority 1: Essential Configuration

Tool	Purpose	Config Location
Fish Shell	Primary shell with 77+ custom functions	dot_config/fish/
Neovim	Primary text editor with LSP and plugins	dot_config/exact_nvim/
Yabai	Tiling window manager	dot_config/exact_yabai/
Skhd	Hotkey daemon for window management	dot_config/exact_skhd/
Karabiner	Hardware keyboard remapping	dot_config/karabiner/
Git	Version control with Delta diff viewer	dot_gitconfig, dot_config/git/
Starship	Shell prompt	dot_config/starship.toml
Chezmoi	Dotfiles management	.chezmoi.toml.tmpl, .chezmoiscripts/

Priority 2: Supporting Tools

Tool	Purpose	Config Location
Ghostty	Terminal emulator	dot_config/ghostty/
Tmux	Terminal multiplexer	dot_config/tmux/
Zellij	Modern terminal workspace	dot_config/zellij/
Yazi	TUI file manager	dot_config/yazi/
Lazygit	TUI git client	dot_config/lazygit/
Lazydocker	TUI docker client	dot_config/lazydocker/
Atuin	Shell history with sync	dot_config/atuin/
Bat	Enhanced cat with syntax highlighting	dot_config/bat/
Bottom/Btop	System monitoring	dot_config/bottom/, dot_config/btop/
Ripgrep	Fast text search	dot_config/ripgrep/

Priority 3: Supplementary Tools

Additional configured tools: AiChat, Delta, Eza, Fish plugins (Fisher), FZF, Television, and more. See Brewfile for the complete list of 100+ installed packages.

Documentation

Getting Started

• INSTALL.md - Step-by-step installation guide
• CHEZMOI.md - Chezmoi workflow for configuration changes

Reference Guides

• docs/KEYMAPS.md - Unified keyboard shortcuts reference
• docs/ARCHITECTURE.md - System architecture and tool interactions
• docs/DESIGN.md - Design philosophy and rationale

Workflows

• docs/workflows/new-machine-setup.md - Setting up additional machines
• docs/workflows/configuration-changes.md - Making safe modifications
• docs/workflows/multi-machine-sync.md - Keeping machines in sync
• docs/workflows/secrets-management.md - Managing secrets and encryption

Tool-Specific Documentation

Each major tool has its own README with configuration details and customization guides:

• Fish Shell - Shell configuration and custom functions
• Neovim - Editor plugins and LSP setup
• Yabai - Window management rules
• Skhd - Hotkey configuration
• Karabiner - Hardware key remapping
• Chezmoi Scripts - Automation scripts and execution order

Key Features

Secrets Management

This repository uses a multi-layered approach to secrets:

• Git submodule (secrets/) for sensitive configuration files
• GPG encryption for individual encrypted files (using encrypted_* prefix)
• 1Password integration for programmatic secret access
• Pre-commit scanning with gitleaks to prevent accidental secret commits

See docs/workflows/secrets-management.md for detailed workflows.

Multi-Machine Support

The configuration automatically detects SSH vs local machines and adjusts:

• Local machines: Full GUI applications (Hammerspoon, Cursor, Ghostty, etc.)
• Remote SSH machines: Minimal CLI-only setup via Brewfile_ssh
• Machine-specific configs: Use .chezmoidata/ for machine-specific settings

Automation Scripts

Six chezmoi scripts handle setup automatically:

1. Secrets submodule initialization - Sets up private secrets repository
2. Homebrew installation - Installs Homebrew and runs brew bundle
3. Additional tools - Installs tools not in Homebrew
4. Python tools via uv - Manages Python development tools
5. macOS settings - Configures system preferences
6. Fish setup - Links Fisher plugin files

See .chezmoiscripts/README.md for execution order and details.

Quality Gates

• Pre-commit hooks: Gitleaks scans for secrets before every commit
• Code formatters: Stylua, fish_indent, shfmt, prettierd, yapf
• Linters: Configured for Python, JavaScript/TypeScript, and shell scripts

Common Tasks

Making Configuration Changes

# Edit a configuration file
chezmoi edit ~/.config/fish/config.fish

# Preview changes before applying
chezmoi diff

# Apply changes to your system
chezmoi apply

# Commit changes to repository
cd ~/.local/share/chezmoi
git add .
git commit -m "Update fish config"
git push

See CHEZMOI.md for the complete workflow .

Syncing Multiple Machines

# Pull latest changes from repository
chezmoi update

# Push local changes to repository
cd ~/.local/share/chezmoi
git push

Finding Keyboard Shortcuts

See docs/KEYMAPS.md for searchable keymap reference across all layers .

Troubleshooting Common Issues

See TROUBLESHOOTING.md for solutions to common problems .

Manual Dependencies

These tools are not installed automatically and require manual installation:

• Docker Desktop: Download from docker.com
• YabaiIndicator: Menu bar status for yabai - GitHub
• Firefox Extensions (if using Firefox):
  • Sidebery - Container management
  • Vimium - Vim-like navigation
  • Firenvim - Neovim in browser

Optional: Vim Motion Apps for macOS

Tools for Vim-like navigation system-wide:

• Homerow - Vimium-like labeled-link navigation (highly recommended)
• kindaVim - Vim motions for text editing
• ti-vim - Alternative Vim motion implementation
• Wooshy - Mouse-free interaction
• Scrolla - Scrolling enhancements

Chezmoi Quick Reference

Essential Commands

# Edit files in chezmoi source state
chezmoi edit <file>

# Show differences between source and destination
chezmoi diff

# Apply changes from source to destination
chezmoi apply

# Pull latest changes and apply
chezmoi update

# Change to chezmoi source directory
chezmoi cd

State Terminology

• Source state: Files in ~/.local/share/chezmoi/ (the chezmoi directory)
• Destination state: Current files in your home directory
• Target state: Desired state that chezmoi will apply

File Naming Conventions

• dot_* → . (dotfiles)
• exact_* → Directory managed exactly (removes untracked files)
• private_* → File with restricted permissions (0600)
• executable_* → File with execute permissions
• symlink_* → Symbolic link
• encrypted_* → GPG-encrypted file
• *.tmpl → Template file (processed with Go templates)

See CHEZMOI.md for detailed explanations .

Secrets and Encryption

GPG Encryption

Files with encrypted_ prefix are automatically encrypted/decrypted by chezmoi:

# Add an encrypted file
chezmoi add --encrypt ~/.config/tool/secret-config.conf

# Edit encrypted files
chezmoi edit ~/.config/tool/encrypted_secret-config.conf

1Password Integration

Configuration uses 1Password service accounts:

• Set OP_SERVICE_ACCOUNT_TOKEN environment variable
• Configured for onepassword.mode="service" in .chezmoi.toml
• Access secrets in templates: {{ (onepassword "item-name").password }}

Pre-commit Secret Scanning

Gitleaks automatically scans every commit for potential secrets:

# Manually scan repository
cd ~/.local/share/chezmoi
pre-commit run --all-files

# Scan including git history
gitleaks detect --report-path gitleaks-report.json

See .gitleaksignore to suppress false positives.

GitHub Actions

This repository syncs between private and public versions:

• Private repository: Contains all configurations including secrets
• Public repository: Sanitized version excluding secrets and encrypted files
• Workflows: daily_sync_main.yaml and daily_sync_dev.yaml automate synchronization

Files excluded from public sync are defined in .chezmoiignore.

Neovim Configuration

The Neovim configuration is managed with chezmoi.nvim:

# Edit Neovim config
vc  # Fish function alias for editing vim config

# Manual editing
chezmoi edit ~/.config/nvim/lua/config/keymaps.lua

Note: Changes made in ~/.local/share/chezmoi are automatically applied to the target state when using chezmoi.nvim, so you don't need to run chezmoi apply manually.

Support

Getting Help

1. Check TROUBLESHOOTING.md for comprehensive troubleshooting coverage:
   • macOS accessibility and Input Monitoring permissions
   • Pre-commit hooks and gitleaks errors
   • Neovim LSP issues and Mason setup
   • Chezmoi apply conflicts and template errors
   • GitHub Actions sync failures
   • Shell, terminal, and tool-specific issues
2. Review tool-specific READMEs in ~/.config/<tool>/README.md
3. Consult official tool documentation (linked in each README)
4. Search GitHub issues in this repository

Contributing

To improve this configuration:

1. Use the chezmoi workflow: chezmoi edit <file>
2. Test changes locally before committing
3. Follow existing patterns and conventions
4. Update relevant documentation
5. Run pre-commit hooks: pre-commit run --all-files
6. Submit changes via pull request

License

Personal dotfiles configuration. Feel free to use as reference or fork for your own use.

Acknowledgments

Built on the shoulders of:

• chezmoi - Dotfiles management
• Fish shell - Friendly interactive shell
• Neovim - Hyperextensible Vim-based text editor
• Yabai - Tiling window manager
• Starship - Cross-shell prompt

And the countless open-source projects that make this development environment possible.