Dotfiles (macOS) – Yabai + skhd + Sketchybar + Kitty + Starship + Neovim

Modern, Hyprland-inspired macOS setup with a tiling WM, menu bar, fast terminal, themed prompt, and a batteries-included Neovim config.

What’s included

• Window manager: yabai + skhd
• Bar: sketchybar (spaces with Greek icons, app title, wifi/volume/battery/clock)
• Terminal: Kitty (Catppuccin theme, Nerd Font)
• Prompt: Starship (Catppuccin colors)
• Editor: Neovim with lazy.nvim, LSP, Treesitter, Telescope, gitsigns, lualine

Quick start

1. Install Xcode Command Line Tools (the script will prompt if missing) and Homebrew.
2. Clone this repo, then:

bash ./install.sh

Dry-run to preview actions:

./install.sh --dry-run

Notes:

• Approve Accessibility for yabai, skhd, and sketchybar in System Settings → Privacy & Security → Accessibility.
• Set your terminal font to “JetBrainsMono Nerd Font”.
• If you want full yabai features, follow the SIP guidance in the official docs: Disabling System Integrity Protection.

Keybindings (skhd)

• Focus windows: Alt+H/J/K/L
• Swap windows: Shift+Alt+H/J/K/L
• Move window to prev/next space (and follow): Ctrl+Alt+H/L
• Focus space 1..9: Cmd+Alt+1..9
• Send window to space 1..9 (and follow): Shift+Cmd+1..9
• Focus displays: Ctrl+Alt+P/N
• Send window to other display: Ctrl+Cmd+P/N
• Toggle split orientation: Alt+Space
• Float/unfloat and center: Alt+T
• Fullscreen: Alt+F
• Launch Kitty: Alt+Return
• Launch VS Code: Alt+E
• Raycast: Alt+R
• Lock screen: Ctrl+Cmd+L

Bar (sketchybar)

• Spaces labeled with Greek icons: α β γ δ ε ζ η θ ι
• Active space highlighted (white icon)
• Front app next to spaces with additional padding
• Right-side modules: wifi (icon-only), volume (event-driven, mute-aware), battery (charging bolt, low-battery red), clock

Files:

• ~/.config/sketchybar/sketchybarrc
• ~/.config/sketchybar/scripts/*.sh

Terminal (Kitty) + Prompt (Starship)

• Kitty config: ~/.config/kitty/kitty.conf (Catppuccin colors, Nerd Font)
• Starship prompt: ~/.config/starship.toml (enabled from ~/.zshrc)

Kitty shortcuts:

• Tabs: Ctrl+J/K (left/right)
• Splits focus: Ctrl+Shift+H/J/K/L
• Create split: Ctrl+Shift+\ (horizontal), Ctrl+Shift+- (vertical)
• Move split: Ctrl+Shift+Alt+H/J/K/L
• Close split: Ctrl+Shift+W
• Rename tab: Ctrl+Shift+R

Neovim

Auto Light/Dark theme

• A small LaunchAgent watches macOS appearance and runs ~/scripts/apply_theme.sh.

• The script writes the current mode to ~/.theme and triggers a sketchybar theme_change event (falls back to --reload).

• Kitty live-switching is supported if you provide:

  • ~/.config/kitty/theme-light.conf
  • ~/.config/kitty/theme-dark.conf

• Add more actions by creating an executable ~/scripts/on_theme_change.sh which will receive light or dark as its first arg.

• Config: ~/.config/nvim/init.lua (lazy.nvim, LSP, Treesitter, Telescope, gitsigns, lualine, Catppuccin)

• Common keys:

  • Space+ff: find files
  • Space+fg: live grep
  • Space+fb: buffers
  • Space+fh: help

CI and local checks

• GitHub Actions workflow: .github/workflows/ci.yml

  • Lints shell scripts (shellcheck, shfmt)
  • Validates Karabiner JSON (jq)
  • Checks Neovim Lua format (stylua)
  • Installer dry-run

• Run locally:

bash scripts/check.sh

Troubleshooting

• Repeated Accessibility prompts for skhd/yabai:

  1. Stop service: skhd --stop-service (and/or yabai --stop-service)
  2. Kill lingering process: pkill -x skhd / pkill -x yabai
  3. Remove and re-add in System Settings → Accessibility (add /opt/homebrew/bin/skhd and /opt/homebrew/bin/yabai)
  4. Start service: skhd --start-service, yabai --start-service

• Space icons not updating: ensure yabai is running (yabai --start-service) and has Accessibility. Switching spaces should trigger updates.

• Volume not updating: the background watcher volume_watcher.sh triggers volume_change events. If needed, restart sketchybar: sketchybar --reload.

Layout and files

Tracked highlights:

• ~/.yabairc, ~/.skhdrc, ~/.zshrc, ~/.gitconfig, ~/.ghci
• ~/.config/sketchybar/**, ~/.config/kitty/kitty.conf, ~/.config/starship.toml, ~/.config/karabiner/karabiner.json, ~/.config/nvim/**
• Brewfile, install.sh, .github/**, scripts/check.sh

Ignored by default: noisy/sensitive app data under ~/.config/** (Raycast, Joplin, gh, Copilot, etc.).