Personal macOS dotfiles with a focus on:
- β‘ fast Zsh startup
- ποΈ XDG-friendly config layout
- β»οΈ reproducible installs via Homebrew
- π minimal magic, explicit behavior
β Tested on macOS (Apple Silicon).
git clone https://github.com/kaffolder7/dotfiles ~/src/dotfiles cd ~/src/dotfiles ./install.sh --brew
The installer also symlinks the dot helper command into ~/.local/bin.
This will:
- Install Homebrew (if missing)
- Install packages from
Brewfile - Symlink dotfiles into your home directory
- Back up any existing files before replacing them
To overwrite existing files without backups:
./install.sh --brew --force
After install, you can sanity-check everything with: dot doctor.
A small built-in sanity check for this repo.
After installation, you can run:
dot doctor
This verifies:
- which install route is active (Homebrew vs Home Manager)
- required XDG paths exist and are writable
- required cache and history directories are present
- file-based secrets are set up correctly
- expected tools (
llm,codex, etc.) are available
Think of it like brew doctor, but scoped specifically to this dotfiles repo.
Itβs safe to run anytime and is especially useful:
- after a fresh install
- when switching machines
- if something feels "off" with your shell
It does not print secret values β only presence and basic health checks.
This repo supports two install styles:
Recommended for most macOS setups.
- Uses
install.sh --brew - Zsh config is loaded directly from
~/.zshrc - Homebrew manages all packages
For users already using Nix + Home Manager.
- Zsh is managed via
nix/home.nix - Dotfiles are still shared, but loaded via Home Manager
DOTFILES_ROUTE=hmis set automatically
Setup:
- Edit
flake.nixand setusernameto your macOS username (runwhoamiif unsure) - Run the initial switch:
nix run github:nix-community/home-manager -- switch --flake .#macmini # or for MacBook Pro: nix run github:nix-community/home-manager -- switch --flake .#mbp
Both routes share the same Zsh modules and XDG layout.
~/.zshrcβhome/.zshrc- Modular config loaded from:
~/.config/zsh/zshrc.d/
Features:
- Powerlevel10k (instant prompt enabled) π
- Cached completions
- Autosuggestions + autocomplete
- Syntax highlighting (loaded last)
- History + cache under XDG paths
fastfetchruns once per session (after prompt)
~/.gitconfigβhome/.gitconfig(used for the Homebrew route, otherwise configuration is managed by Home Manager)- Personal settings (e.g.
user.name,user.email, etc.) live in~/.gitconfig.local(not committed)
Create it with:
cp home/.gitconfig.local.example ~/.gitconfig.local
Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration.
~/.config/ghostty/configβxdg/ghostty/config
Includes:
- One Dark theme
- Transparent background with blur
- Sensible padding and defaults
~/.config/nano/nanorcβxdg/nano/nanorc
Homebrew is the missing package manager for macOS (or Linux).
All packages are managed via Brewfile.
- Safe by default: installs missing packages only
- To enforce a clean system (
β οΈ destructive):brew bundle --cleanup
To update the Brewfile after changes:
brew bundle dump --force
Secrets are stored as files (not env vars) under: ~/.config/secrets/.
Examples:
openai_api_keyopenai_api_key_llmopenai_api_key_codex
They are:
- ignored by git
- read only when needed
- injected per-command (not exported globally)
See xdg/zsh/zshrc.d/70-openai.zsh for details.
Create a local-only file:
cp home/.zshrc.local.example ~/.zshrc.local
Anything in ~/.zshrc.local is sourced last and ignored by git.
Edit ~/.gitconfig.local for name, email, signing keys, etc.
dotfiles/ βββ Brewfile # Homebrew bundle: packages, casks, VS Code extensions βββ install.sh # Main installer (Homebrew or Nix/Home Manager routes) βββ bin/ β βββ dot # Lightweight helper CLI entrypoint β βββ dot-doctor # Sanity-check tool for paths, secrets, and install state βββ codex/ β βββ config.toml # Codex CLI provider/model configuration βββ home/ β βββ .gitconfig # Base Git config (includes local overrides) β βββ .gitconfig.local.example # Example for user-specific Git identity (not committed) β βββ .zshrc # Minimal Zsh entrypoint (loads modular config) β βββ .zshrc.local.example # Local-only Zsh overrides (ignored by git) βββ nix/ β βββ hosts/ β β βββ macmini.nix # Mac Mini host-specific config β β βββ mbp.nix # MacBook Pro host-specific config β βββ overlays/ β β βββ default.nix # Nix package overlays β βββ pkgs/ β β βββ bbrew.nix # Custom bbrew package definition β βββ home.nix # Main Home Manager configuration βββ scripts/ β βββ ollama-models.sh # Pull default Ollama models (gemma3, etc.) β βββ update-bbrew.sh # Fetch latest bbrew version + hashes βββ secrets/ β βββ openai_api_key.example # (Optional) single shared OpenAI key β βββ openai_api_key_codex.example # Example Codex-specific OpenAI key β βββ openai_api_key_llm.example # Example LLM-specific OpenAI key # Real secrets live in ~/.config/secrets (not committed) βββ xdg/ β βββ ghostty/ β β βββ config # Ghostty terminal configuration β βββ nano/ β β βββ nanorc # Nano editor config (XDG-compliant) β βββ zsh/ β βββ .p10k.zsh # Powerlevel10k prompt configuration β βββ zshrc.d/ β βββ 00-env.zsh # Core environment setup (XDG, PATH, cache dirs) β βββ 10-homebrew.zsh # Homebrew shell environment (brew shellenv) β βββ 20-completion.zsh # Zsh completion + caching (non-HM route) β βββ 30-history.zsh # History behavior + XDG_STATE_HOME storage β βββ 40-aliases.zsh # Shell aliases (non-HM route) β βββ 50-prompt.zsh # Powerlevel10k prompt setup β βββ 60-plugins.zsh # Zsh plugins (autosuggest, autocomplete, highlighting) β βββ 70-openai.zsh # OpenAI / LLM / Codex helpers + file-based secrets β βββ 80-hooks.zsh # Hooks (e.g. fastfetch once per session) β βββ 90-local.zsh # Local Zsh overrides (~/.zshrc.local) βββ .github/ β βββ workflows/ β βββ ci.yml # PR/push checks (nix flake check) β βββ update-bbrew.yml # Weekly auto-update for bbrew package β βββ update-locks.yml # Monthly auto-update for flake.lock βββ .editorconfig # Editor settings (indent, charset, line endings) βββ .gitignore βββ flake.lock # Nix flake lockfile (pins dependencies) βββ flake.nix # Nix flake entrypoint for Home Manager βββ Makefile # Common tasks (install, update, doctor, switch-*) βββ README.md
- Intentionally avoids Oh My Zsh (...Powerlevel10k is Zsh-native / faster)
- No output is produced before Powerlevel10k instant prompt
- Designed to be safe to re-run multiple times
Clone it, run it, forget about it. β¨