My Personal Dotfiles

A personal collection of dotfiles for macOS and Linux, designed for a consistent and productive development environment. This setup is modular, managed by a simple setup script, and consistently themed with Catppuccin Mocha.

Repositories

• dotfiles
• dotfiles.nvim
• dotfiles.agents
• dotfiles.home
• dotfiles.sway
• dotfiles.scripts
• dotfiles.ghostty
• dotfiles.tmux
• dotfiles.waybar
• dotfiles.zellij
• dotfiles.atuin
• dotfiles.rofi
• dotfiles.bat
• dotfiles.alacritty
• dotfiles.dunst
• dotfiles.hyprland
• dotfiles.kitty
• dotfiles.niri
• dotfiles.nvim2
• dotfiles.lf
• dotfiles.onedrive

---

Software Overview

Category	Tools
Window Manager	Sway, Hyprland, Niri
Status Bar	Waybar
Terminal	Alacritty, Kitty, Ghostty
Shell	Zsh (with Oh My Zsh, Atuin, Zoxide)
Editor	Neovim
Multiplexer	Zellij, Tmux
Git	delta, git-cliff, github-cli
Launcher	Rofi (+ rofi-calc)
Notifications	Dunst
Screenshots	grim, slurp, satty
File Manager	lf
Utilities	bat, eza, fzf, ripgrep, jq, tldr, mise
TUI	bluetui (Bluetooth)
Audio	PipeWire, WirePlumber

---

Requirements

• Core:

  • git: For cloning and managing the repository.
  • zsh & oh-my-zsh: The primary shell environment.
  • zsh-syntax-highlighting
  • zsh-autosuggestions
  • zsh-defer: Deferred execution for faster shell startup.
  • Nerd Fonts: Required for icons (this config uses FiraCode Nerd Font).

• Terminal Tools:

  • atuin: Enhanced shell history (installed via its own installer).
  • bat: A cat clone with syntax highlighting.
  • eza: A modern replacement for ls.
  • fzf: A command-line fuzzy finder.
  • delta: A viewer for git diffs.
  • neovim: The primary text editor.
  • ripgrep: A fast line-oriented search tool.
  • zoxide: A smarter cd command.
  • jq: A command-line JSON parser.
  • mise: Dev tools/runtimes manager (installed via its own installer).
  • tldr: Simplified man pages.
  • tree-sitter-cli: Required for Neovim.

• GUI (Linux/Wayland) — install only what you need for your chosen WM:

  • Sway: sway, swaylock, swaybg, swayidle, xdg-desktop-portal-wlr
  • Hyprland: hyprland, quickshell, hypridle, hyprlock
  • Niri: niri, xwayland-satellite, swaybg
  • Common: waybar, rofi, rofi-calc, dunst, libnotify
  • Screenshots: grim, slurp, satty (annotation editor), wf-recorder (screen recording)
  • Clipboard: wl-clipboard
  • Audio: pipewire, wireplumber
  • Bluetooth: bluez, bluez-utils, bluetui (TUI manager)

Arch Linux

A full package list is maintained in packages/:

• packages/official_packages.txt — pacman packages
• packages/aur_packages.txt — AUR packages

Below are the packages relevant to these dotfiles.

# Shell & core
sudo pacman -S zsh git
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
git clone https://github.com/romkatv/zsh-defer ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-defer

# Terminal tools
sudo pacman -S bat eza fzf git-delta ghostty jq neovim ripgrep tldr zoxide
cargo install --locked tree-sitter-cli

# Installed via their own installers (not pacman)
curl https://mise.run | sh
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh

# Wayland common
sudo pacman -S waybar rofi rofi-calc dunst libnotify grim slurp satty wl-clipboard wf-recorder

# Sway
sudo pacman -S sway swaylock swaybg swayidle xdg-desktop-portal-wlr

# Hyprland (install instead of / in addition to Sway)
sudo pacman -S hyprland quickshell hypridle hyprlock

# Niri (install instead of / in addition to Sway)
sudo pacman -S niri xwayland-satellite swaybg

# Audio & Bluetooth
sudo pacman -S pipewire wireplumber bluez bluez-utils bluetui

---

Installation

1. Clone the repository and its submodules:

   git clone --recurse-submodules git@github.com:cjvnjde/dotfiles.git $HOME/dotfiles
   cd $HOME/dotfiles

2. Choose which modules to enable by creating a .modules file:

   cp .modules.example .modules

   Edit .modules to keep only the modules you need. Lines starting with ! disable a previously enabled module (useful in .modules.local).

3. Run the setup script:

   bash setup.sh

---

How It Works

Module System

The setup is fully module-based. The root setup.sh does three things:

1. Reads .modules (and .modules.local) to determine which modules are enabled.
2. Discovers all module setup scripts automatically.
3. Calls independent modules' setup.sh scripts concurrently with enable or disable.

Each module owns its own setup logic — the root script has no hardcoded paths or destinations.

Parallel Execution

Run either script directly. Every independent module gets its own background job, with no worker limit or job-count configuration:

./setup.sh
./update.sh

Setup runs tmux and ly in a separate foreground phase after all background modules succeed, because they can prompt or request sudo access. Override the space-separated list when adding interactive modules or modules that share resources:

DOTFILES_SERIAL_MODULES="tmux ly my-module" bash setup.sh

An empty DOTFILES_SERIAL_MODULES allows every module to run in the background; use it only when none require terminal input or exclusive access. Background modules receive /dev/null as stdin so non-interactive installers, including skills --yes, cannot read or change the foreground terminal through stdin. Their output streams live and may interleave. Setup waits for all workers and only runs after_setup.sh if every module succeeds.

Update pulls the main repository with --no-recurse-submodules, then each submodule job switches to main and pulls with --no-recurse-submodules. Missing submodules are initialized inside their own jobs, not in a sequential fetch pass. Parent updates finish before their nested submodules are discovered and updated. The summary reports updated, skipped, and failed counts; any failure produces a nonzero exit status. Interrupting either script terminates active background workers.

Module Types

Directory modules — most modules are entire config directories (e.g. nvim, hyprland, alacritty). They contain a setup.sh that symlinks the directory to the right place:

alacritty/setup.sh   → symlinks alacritty/ to ~/.config/alacritty
hyprland/setup.sh    → symlinks hyprland/ to ~/.config/hypr
nvim/setup.sh        → symlinks nvim/     to ~/.config/nvim

Single-file modules — configs that are just one file live in home/ and have their setup scripts in home/setup/:

home/setup/zshrc.sh    → symlinks home/.zshrc      to ~/.zshrc
home/setup/git.sh      → symlinks home/.gitconfig   to ~/.gitconfig
home/setup/wezterm.sh  → symlinks home/.wezterm.lua to ~/.wezterm.lua

Custom modules — some modules need more than a single symlink and have custom logic:

• scripts/setup.sh — creates ~/.local/scripts/ as a real directory and symlinks individual scripts into it (including ccode and clipboard-code aliases).
• agents/setup.sh — uses npx skills@latest to install only the small global skill set for Pi, Codex, Claude Code, Zed, and universal agents; project skills remain opt-in.

Available Modules

Module	Destination	Notes
nvim	~/.config/nvim
alacritty	~/.config/alacritty
kitty	~/.config/kitty
ghostty	~/.config/ghostty
zshrc	~/.zshrc	Sources ~/.zshrc_local if it exists
git	~/.gitconfig
ideavim	~/.ideavimrc
wezterm	~/.wezterm.lua
opencode	~/.config/opencode/opencode.json
scripts	~/.local/scripts/*	Individual script symlinks
agents	Global agent skill directories	Managed with npx skills@latest for Pi, Codex, Claude Code, Zed, and universal agents
atuin	~/.config/atuin
bat	~/.config/bat
zellij	~/.config/zellij
tmux	~/.config/tmux
hyprland	~/.config/hypr
ly	/etc/ly/config.ini	Requires root access

Local Overrides

Several config files support machine-specific overrides that are git-ignored:

File	Purpose
.modules.local	Override enabled modules (supports !module to disable)
~/.zshrc_local	Private aliases, env vars, machine-specific shell config

Example .modules.local — enable everything from .modules but drop Alacritty and add Kitty:

!alacritty
kitty

---

Personal Agent Skills

Keep only deliberately global skills under agents/skills/. Add reusable project skills to the opt-in library:

agents/library/<skill-name>/SKILL.md

Enable the agents module and run bash setup.sh to install the global configuration (AGENTS.md, eco-mode, and skill-authoring). Ask an agent to select only the needed packages from agents/library/ and copy them into a project's host-supported skills directory. Library additions are never installed globally by setup. See agents/README.md for selection, migration, installation, and removal behavior.

---

Adding a New Module

Directory module (e.g. ~/.config/foo):

1. Add the config directory: foo/
2. Create foo/setup.sh following any existing module as a template (e.g. alacritty/setup.sh).
3. Add foo to .modules.

Single-file module (e.g. ~/.some_rc):

1. Add the file to home/ (e.g. home/.some_rc).
2. Create home/setup/some_rc.sh following home/setup/git.sh as a template.
3. Add some_rc to .modules.

The root setup.sh discovers modules automatically — no registration step needed.

---

Management

• Re-run after changes:

  bash ~/dotfiles/setup.sh

  The script is idempotent — running it again with no changes produces no output beyond info logs.

• Update from remote:

  cd ~/dotfiles && bash update.sh
  bash setup.sh

  update.sh switches each non-ignored submodule to main and pulls normally; it does not hard-reset local work. Missing main branches, checkout conflicts, and pull failures are reported as errors.

• Conflicts: Most modules back up an existing destination to <path>.bak before linking. The agents module delegates same-name skill handling to the skills CLI; unrelated skill names remain untouched.

• Submodules: Most modules are git submodules. Changes to module setup scripts need to be committed inside the submodule first, then the parent repo pointer updated.