dotfiles/README.md

dotfiles

Chezmoi source tree for a Linux desktop — Hyprland (with a Niri alternative), Quickshell/Waybar, Neovim, and a Zsh/Nushell shell, themed end-to-end with the custom apex-neon (dark) / apex-aeon (light) palettes.

This README is .chezmoiignored — it documents the repo for humans and is never applied to $HOME.

Quick start

chezmoi diff          # preview pending changes
chezmoi apply         # render templates and apply to $HOME
chezmoi status        # show managed file status

After applying, reload the affected tool — hyprctl reload, restart Waybar / Quickshell, re-source Zsh, etc.

File naming (chezmoi)

Prefix / suffix	Meaning
dot_	leading . (e.g. dot_config/ → ~/.config/)
executable_	sets the executable bit
private_	restricts permissions (600/700)
symlink_	creates a symlink
.tmpl	Go template rendered at apply time
##hostname.<name>	host-specific variant

Template data model (~/.config/chezmoi/chezmoi.toml, per-machine, untracked)

Machine traits are split from structured config:

• tags — booleans only: laptop, touchscreen, pipewire, dev, bluetooth. There is no desktop tag — the desktop case is not laptop.
• compositor — "hyprland" or "niri".
• apps — optional programs present on the machine, e.g. ["steam", "spotify", "jellyfin"]. Gated with has "steam" .apps.
• data.monitors — array; each has name, optional primary, and a role ("primary"/"left"/"right") plus its workspaces.
• data.placement — app-home workspaces (id, name, monitor role, apps = window classes routed there, silent, optional layout/layoutopts/on_created_empty/requires). A role resolves to the monitor that carries it and falls back to the primary monitor when that role is absent, so single-monitor machines work with no edits. requires drops an entry unless that program is in apps.
• data.microphones — array, meaningful only when pipewire = true.

Window placement (which app opens on which workspace/monitor) is therefore data-driven: edit data.placement, never hardcode monitor names in templates. See dot_config/hypr/hyprland.d.lua/{workspaces,rules}.lua.tmpl.

Layout

• dot_config/hypr/ — Hyprland (v0.55 Lua config). Entry: hyprland.lua.tmpl; modular includes in hyprland.d.lua/.
• dot_config/niri/ — Niri compositor (alternative to Hyprland).
• dot_config/quickshell/ — Quickshell bar/popouts (QML). See its CLAUDE.md.
• dot_config/waybar/ — Waybar config/styles (used under either compositor).
• dot_config/nvim/ — Neovim (Lua + lazy.nvim).
• dot_config/zsh/, Nushell — shells and aliases.
• dot_local/bin/ — user scripts (executable_ prefixed).
• .chezmoiscripts/ — run_onchange_* hooks run on chezmoi apply.

Theming — apex

apex-aeon (dark) and apex-neon (neon) span nvim, zsh, waybar, quickshell, alacritty, kitty, ghostty, btop, fuzzel, gtk4, spicetify, swaync, wezterm, zathura, zed. Theme files are not edited by hand — they're synced from ~/Dev/Themes/apex/dist via refresh-apex-themes.

Agent docs

CLAUDE.md / AGENTS.md / GEMINI.md (root and per-tool) carry conventions and the full data-model reference for AI coding agents. They are also .chezmoiignored.