My personal macOS dotfiles organized by packages with automated installation.

sudo softwareupdate -i -a
xcode-select --install

Default location is ~/.dotfiles. Clone and run:

git clone https://github.com/kalupas226/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh

Skip prompts before running official remote installer scripts:

./install.sh --skip-confirmation

• Homebrew - Package manager for macOS
• mise - Development environment manager
• CLI tools - bat, eza, fzf, ripgrep, starship, neovim, etc.
• GUI applications - ChatGPT, CleanShot, Wezterm, VSCode, Raycast, etc.
• Fonts - Hack Nerd Font
• Node.js - Pinned via mise
• Dotfiles - Automatically symlinked to your home directory

Restart your terminal or run source ~/.zshrc to load the new configuration.

Some tools require a one-time manual step after install.sh:

• tmux plugins (TPM): open tmux and run prefix + I to install plugins (e.g. vim-tmux-navigator)
• Neovim plugins (lazy.nvim): open Neovim and run :Lazy sync
• Homebrew apps/tools: some packages need first-run setup, permissions (e.g. macOS Security & Privacy), or in-app configuration—check each tool as needed
• AeroSpace:
  • Grant Accessibility permission in System Settings → Privacy & Security → Accessibility
  • Run defaults write com.apple.spaces spans-displays -bool true && killall SystemUIServer (required for multi-monitor support)
  • Reload config: alt-shift-; → esc
• Claude Code plugins: reinstall plugins from the marketplace (/plugins in Claude Code)
• pfw (Point-Free Way CLI): follow the setup instructions at https://github.com/pointfreeco/pfw
• Logi Tune: install manually (not managed by Homebrew in this repo). Reference: https://www.logitech.com/assets/66219/5/brio-500.pdf
• macOS settings: set these in System Settings (paths can vary by macOS version)
  • Mission Control: Desktop & Dock → disable "Automatically rearrange Spaces based on most recent use"
  • Trackpad: Trackpad → enable "Tap to click"
  • Trackpad: Accessibility → Pointer Control → Trackpad Options... → enable dragging and choose "Three Finger Drag"

• Install/link everything (runs install.sh under the hood):
  mise run dotfiles:install
• Check for updates (brew/mise/npm/sheldon):
  mise run dotfiles:check-updates

Tasks are defined in packages/mise/.config/mise/config.toml.

Custom location: set DOTFILES_DIR before running tasks, e.g.
DOTFILES_DIR=/path/to/dotfiles mise run dotfiles:install

• Node: pinned via mise in packages/mise/.config/mise/config.toml
• npm CLIs: prefer project-local devDependencies or npm dlx/npx; only keep truly global needs in packages/npm/global-packages.txt and install.sh will install them
• Updates check (one-shot, no writes): mise run dotfiles:check-updates
  • Homebrew (brew update --quiet + brew outdated)
  • mise tools (mise outdated)
  • sheldon plugins (pinned rev vs latest tags)
• AI agent worktrees:
  • Requires tmux; after ./install.sh, use gwt from ~/.local/bin/gwt
  • Requires the selected agent CLI on PATH (codex, claude, or copilot); gwt add and gwt open validate it before opening the task window
  • New project sessions start with window 1 named <repo>@root for repo-level shell work and as the parent-worktree hub for creating more task worktrees
  • task names are restricted to letters, numbers, ., _, and - (for example tmux-status); names like feat/tmux-status are rejected
  • gwt add <task> --agent <codex|claude|copilot> creates a new .worktrees/<task> plus a tmux window in the project session
  • gwt open <task> reopens an existing task window for a task recorded in gwt metadata and works across tmux sessions
  • gwt open --force <task> bypasses stale branch-metadata checks after warning; use it only for recovery when the recorded branch no longer matches the registered worktree branch
  • gwt ls shows task / agent / status / dirty / worktree / stale
  • stale=yes means the recorded metadata no longer matches reality (for example the worktree is missing or no longer registered on the recorded branch)
  • gwt rm <task> closes the task window and removes the worktree for a gwt-managed task; it refuses dirty worktrees, leaves the parent <repo>@root window/session alone, and local branches are left alone
  • gwt rm --force <task> also discards uncommitted changes in that worktree; use it only for recovery
  • gwt treats .worktrees/.gwt/tasks/*.tsv as the source of truth for managed tasks; if that metadata is missing, the task no longer appears in gwt ls and must be inspected or cleaned up with raw git worktree commands
  • Useful recovery commands for orphaned worktrees: git worktree list, git worktree remove .worktrees/<task>, and git branch -d <branch> when you also want to drop the branch
  • tmux window names are refreshed automatically as task [agent:●|◌|·] for busy, idle, and inactive states
• If brew bundle or mise install fails mid-run, fix the cause then rerun mise run dotfiles:install.
  • If you don't use mise tasks, run ./scripts/check-updates.sh

This repository uses a package-based organization:

packages/
├── aerospace/  # AeroSpace window manager configuration
├── bin/        # User-facing CLI helpers installed into ~/.local/bin
├── claude/     # Claude Code settings and configurations
├── git/        # Git configuration
├── karabiner/  # Karabiner-Elements configuration
├── lazygit/    # Lazygit configuration
├── mise/       # Development environment manager configuration
├── npm/        # npm CLI defaults
├── nvim/       # Neovim configuration
├── sheldon/    # Shell plugin manager configuration
├── starship/   # Starship prompt configuration
├── tmux/       # Terminal multiplexer configuration
├── wezterm/    # Terminal emulator configuration
└── zsh/        # Zsh shell configuration

Each package contains dotfiles in their expected directory structure. The installation script automatically creates symlinks from package files to their target locations in your home directory.

• packages/mise/.config/mise/config.toml - tool pins and mise tasks (dotfiles:install, dotfiles:check-updates)
• Brewfile - Homebrew package definitions
• install.sh - Main installation script with custom symlinking logic
• scripts/ - repository maintenance scripts (install/check/update helpers such as check-updates.sh, lib/ui.sh)
• packages/bin/.local/bin/gwt - tmux + git worktree launcher for AI-agent tasks
• packages/bin/.local/bin/ - user-facing CLI helpers; prefer this location for agent/task utilities instead of scripts/
• packages/ - Individual application configurations
• KEYBINDINGS.md - cheat sheet for custom macOS/terminal/Neovim keybindings