mtrojer

Dotfiles

Personal dotfiles, deployed via GNU Stow and a repo-specific sync tool (dotfiles-sync, implemented under _dotfiles_sync/).

Zen Of This Setup

The pillars below govern every package in this repo. They exist so future-me can resist the urge to chase the next shiny compositor release, plugin framework, or distro flavor and instead keep editing actual files.

When tempted, re-read this section before touching anything.

1. Boring infra is good infra. None of the tools here are exciting in 2026. That is the point. The desktop is the substrate, not the hobby.
2. Builtins first, plugins last. A plugin or external tool only lands when a builtin genuinely cannot do the job.
3. Every line is understood. No framework magic, no hidden keymaps, no "distro" config layers. If a line is here, future-me can explain why; if not, it gets deleted.
4. Each piece earns its place. Every plugin, package, script, and service answers a one-line "why not builtin?" question. Inertia is not an answer.
5. Local scripts over upstream plugins. A small Python script in this repo beats a third-party dependency. Easier to read, easier to fix, doesn't break on upgrade.
6. Recreate, do not restore. No session snapshots. No magic state restoration. Disposable sessions force the setup to stay cheap to spin up.
7. Thin wrappers around shared lists. Decisions live in data, not in scripts. dotfiles-sync, setup-*.sh, the package lists — all wrappers around plain data.
8. Opinionated, not agnostic. Linux is Fedora + Wayland + Sway with foot as the terminal. macOS is Hammerspoon with Ghostty as the terminal. The shared layer is the CLI/editor baseline; the desktop stack is allowed to diverge per platform, and once chosen, lean into each OS's native primitives (Spaces and Mission Control on macOS, sway IPC and Wayland layer-shell on Linux; foot's server/client and Ghostty's app-bundle launch model on their respective sides) rather than faking another OS's idioms on top. Each OS is allowed to bloom in its own direction.
9. One palette, one layout language. Catppuccin Mocha is the color system; blocky/tmux geometry is the interaction grammar. Blocks are affordances, not decoration: use them for navigation, focus, modal state, or actionable problems, and keep ambient context quieter. See docs/THEME.md and docs/LAYOUT.md.
10. Config lives next to the thing it configures. Tool-specific docs go in the package folder. This root README only describes the repo shape and the rules above.

If a new toy violates more than one of these, it does not belong here — no matter how cool the blur effect is.

Quick start

git clone https://github.com/martintrojer/dotfiles ~/dotfiles
cd ~/dotfiles
./dotfiles-sync --apply
# Then follow the two manual steps it prints (Claude plugin + Codex notify hook).

Full install steps, the update flow, recipes for testing changes without clobbering your real $HOME, and cleanup steps for machines running an older version of this repo all live in docs/SETUP.md.

Repository shape

The shared layer is intentionally the CLI/editor baseline. Desktop behaviour is allowed to diverge by platform.

Where	What
Portable core (stow packages)	zsh/, nvim/, tmux/, git/, ssh/, local-bin/
Linux desktop stack (stow packages)	sway/, waybar/, fuzzel/, foot/ (terminal), kanshi/, mako/, swaylock/
Linux gaming stack (stow packages)	mangohud/, gamemode/ — gaming layer for this Windows→Linux box; see fedora/ (steam-packages.sh, docs/LACT.md, bin/) and docs/DECISIONS.md
macOS desktop stack (stow packages)	hammerspoon/, ghostty/ (terminal)
Fedora setup namespace	fedora/ (special case: nested stow packages + setup wrappers)
Universal agent sources	skills/, pi/
Claude marketplace surface	hooks/, .claude-plugin/ — ugly but intentional; this is the published plugin contract Claude consumes
Repo control plane	dotfiles-sync, _dotfiles_sync/, .stowrc
Cross-cutting docs/policy	docs/ — SETUP.md, DECISIONS.md, THEME.md, LAYOUT.md, VSCODE.md