dotfiles

Personal macOS configuration managed with GNU Stow.

Packages

Package	Description	Target
aerospace	AeroSpace tiling window manager	~/.config/aerospace/
karabiner	Karabiner-Elements key remapping via GokuRakuJo	~/.config/karabiner/
wezterm	WezTerm terminal emulator	~/.wezterm.lua
zed	Zed code editor	~/.config/zed/
zsh-personal	ZSH config (personal machine)	~/.zshrc
zsh-work	ZSH config (work machine)	~/.zshrc

Prerequisites

• Homebrew
• GNU Stow (brew install stow)

Setup

# 1. Clone this repo
git clone <repo-url> ~/Code/dotfiles
cd ~/Code/dotfiles

# 2. Run the installer (stows all packages)
./install.sh

Stow a specific package

./install.sh aerospace
./install.sh zsh-personal   # or zsh-work

Preview changes without applying

./install.sh --dry

Remove symlinks

./install.sh --delete
./install.sh --delete aerospace   # specific package

How it works

Each top-level directory is a stow package. The internal structure mirrors $HOME:

dotfiles/
├── aerospace/
│   └── .config/aerospace/
│       ├── aerospace.toml                   → ~/.config/aerospace/aerospace.toml
│       └── toggle-split.sh                  → ~/.config/aerospace/toggle-split.sh
├── karabiner/
│   └── .config/
│       ├── karabiner.edn                    → ~/.config/karabiner.edn (GokuRakuJo source)
│       └── karabiner/karabiner.json         → ~/.config/karabiner/karabiner.json
├── wezterm/
│   └── .wezterm.lua                         → ~/.wezterm.lua
├── zed/
│   └── .config/zed/{settings,keymap}.json   → ~/.config/zed/
└── zsh-personal/
    └── .zshrc                               → ~/.zshrc

Stow runs with --no-folding, creating file-level symlinks. This keeps directories like ~/.config/karabiner/ intact while only symlinking the files we version.

Adding a new config

# 1. Create the package directory mirroring the home path
mkdir -p new-package/.config/app/

# 2. Copy the config in
cp ~/.config/app/config.toml new-package/.config/app/

# 3. Stow it (--adopt replaces the original file with a symlink)
stow --no-folding --adopt --target=$HOME new-package

# 4. Commit
git add new-package/ && git commit -m "Add new-package config"

Karabiner key mappings

The karabiner.edn file is the GokuRakuJo source. Running goku compiles it into karabiner.json. Karabiner also rewrites its JSON on every UI settings change — since the file is symlinked, changes appear directly in the repo.

Trigger	Action
Caps Lock (held)	Activates hyper-mode layer
Caps Lock (tap)	Escape
Hyper + h j k l	Arrow keys (vim-style)
Hyper + =	Fn+F12

Home-row chords (minimal, typing-safe):

Left hand	Right hand	Modifier
f+d	j+k	Option
f+s	j+l	Option+Shift

Notes:

• Single-key home-row mod-tap mappings were removed due repeat/drop issues under fast rolling typing in Karabiner.
• These are explicit simultaneous chords only; normal home-row letters remain untouched.
• Chords send original letters if chorded keys are released without being used as modifiers.

ZSH profiles

Only one zsh-* package should be stowed at a time since they both target ~/.zshrc:

# Switch from personal to work
./install.sh --delete zsh-personal
./install.sh zsh-work