rgomezcasas/dotfiles

_{macOS dotfiles powered by Nix flakes, home-manager, and 80+ shell scripts}

Install  •  Workflow  •  Structure  •  Docs

Stack

Layer	Tool
System config	nix-darwin flake
User config	home-manager (symlinks, session)
GUI packages	Homebrew via nix-homebrew
Shell	Zsh + Zim (<10ms startup)
Terminal	Ghostty
Keyboard	Karabiner-Elements via Goku
Scripts	80+ bash scripts via dotly framework

Prerequisites

• macOS on Apple Silicon (aarch64-darwin)
• Nix with flakes enabled
• SSH key with access to dotfiles-private submodule

Installation

# 1. Install Nix
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

# 2. Clone with submodules
git clone --recurse-submodules git@github.com:rgomezcasas/dotfiles.git ~/.dotfiles

# 3. Build and apply the system configuration
cd ~/.dotfiles/config/nix
sudo darwin-rebuild switch --flake .#pro --impure

This single command installs all Nix packages, Homebrew formulas/casks, Mac App Store apps, applies macOS defaults, and creates all symlinks via home-manager.

Daily workflow

Command	Alias	What it does
dot system rebuild	rebuild	Rebuild system with current Nix flake
dot system update	up	Update flake inputs, diff changes, rebuild, and upgrade Zim plugins
dot	—	Browse all available scripts interactively

Adding packages

See the nix docs for step-by-step guides:

• Nix packages — CLI tools managed by Nix
• Homebrew packages — brews not available in nixpkgs
• Homebrew casks — GUI applications
• Node packages — global Node.js tools
• Mac App Store apps — apps via mas

Editing keyboard shortcuts

Edit config/macos/karabiner-goku/karabiner.edn and run goku. Never edit karabiner.json directly. See the Karabiner guide.

Structure

~/.dotfiles
├── config/
│   ├── agents/          # Claude/AI agent instructions and commands
│   ├── git/             # .gitconfig, .gitattributes, .gitignore_global
│   ├── macos/           # Karabiner, Ghostty, skhd, Raycast, LaunchAgents
│   ├── editors/          # VSCode, Cursor, IntelliJ, Vim, Claude Code configs
│   ├── nix/             # Nix flake, home-manager, packages, system config
│   │   ├── flake.nix    #   Main flake: nix-darwin + home-manager + nix-homebrew
│   │   ├── home.nix     #   Home-manager entry point
│   │   ├── packages/    #   Package declarations (nix, brew, node, app-store)
│   │   └── system/      #   System config (symlinks, macOS defaults)
│   └── shell/           # Zsh/Bash configs, aliases, exports, functions
├── docs/                # Guides (packages, scripts, keyboard, editors)
├── modules/
│   ├── dotly/           # Shell script framework (submodule)
│   ├── private/         # Credentials, GPG, private configs (submodule)
│   └── ghostty-cursor-shaders/
├── scripts/             # 80+ scripts organized by category
│   ├── system/          #   rebuild, update, volume, cron...
│   ├── github/          #   git/GitHub utilities
│   ├── claude/          #   Claude CLI wrappers
│   └── ...              #   ai, docker, image, network, utils, video...

Documentation

Guide	Path
Adding packages	docs/nix/
Creating scripts	docs/scripts/
Keyboard shortcuts	docs/karabiner/
Raycast scripts	docs/raycast/
Editor settings	docs/vscode-and-cursor/

Performance

Shell startup consistently under 10ms thanks to Zim + zsh-defer lazy loading:

λ ~ dot shell zsh test_performance
real 0.01s      user 0.00s      sys 0.00s
real 0.01s      user 0.00s      sys 0.00s
real 0.01s      user 0.00s      sys 0.00s

License

The MIT License (MIT). See LICENSE for more information.