dotfiles

Private, safe, cross-platform personal dotfiles for macOS and EndeavourOS / Arch Linux, managed with GNU Stow.

macOS is the primary environment; Arch is supported from the start. Configs are version-controlled in stow/common/ and only ever symlinked into $HOME by a deliberate, manual Stow step — never automatically.

Status

Claude Code operating layer:    complete
GNU Stow scaffold:              created
Managed packages:               see stow/common/
Home directory:                 stowed — all stow/common/ packages symlinked into $HOME

stow/common/ is the source of truth for which packages exist. All of its packages are stowed: live symlinks point from $HOME into the repo. Stow is still always a deliberate, manual step.

What's included

Each package is self-contained and carries its own README. stow/macos/ and stow/arch/ are reserved for platform-specific packages and are currently empty.

Package	What it manages	Details	Guide
alacritty	Alacritty terminal — window, font, keybinds, Catppuccin Macchiato theme	README	guide
bat	bat pager — style, wrap, paging, Catppuccin Macchiato theme	README	guide
claude	Claude Code status line — OS · model · path · git · context % segments, mirrors the Catppuccin Macchiato prompt	README	guide
eza	eza ls replacement — Catppuccin Macchiato (Blue) color theme	README	guide
git	Portable Git config — settings, aliases, global ignore (no secrets)	README	guide
herdr	Herdr agent multiplexer — theme, terminal, UI, toast	README	guide
nvim	Neovim config — Catppuccin Macchiato (Lua), managed plugins	README	—
omp	Oh My Posh prompt — segments + Catppuccin Macchiato palette	README	—
zsh	Layered Zsh config — path, history, plugins, tools, prompt, per-OS layers, go-task completion	README	guide

Documentation

Setup guides are written for a human operator, not for agents.

• Packages setup — install the tools every package depends on (git, stow, go-task, …).
• GNU Stow usage — dry-run workflow, install steps, conflict handling, adding packages.
• Per-package setup guides — alacritty · bat · claude · eza · git · herdr · zsh.
• Shell dependencies · Zsh migration notes.

Installing a package

Stow is always a manual, reviewed step. Dry-run first, install only after reviewing the output.

# Step 1 — dry run, review what would be linked
stow --dir=stow/common --target="$HOME" --simulate <package>

⚠️ MANUAL STEP — run only after approving the dry-run output

stow --dir=stow/common --target="$HOME" <package>

If the dry run reports a conflict, stop and resolve it manually. Never use --adopt — it overwrites existing files. See the Stow usage guide for full detail.

Safety

• All stow/common/ packages are stowed; symlinks point from $HOME into the repo. Each was installed via a deliberate, reviewed Stow step.
• Stow and symlink operations happen only with explicit per-session approval and a reviewed plan.
• No secrets, credentials, or private hostnames are committed.
• Local-only and sensitive values live in unstowed .example templates that you copy and fill in.
• Every significant change follows: PRD → Architecture → Review → Plan → Review → Build → Review → Commit.

For Claude Code

Read AGENTS.md first — it is the main operating contract. It defines agent roles, the PRD-first workflow, safety / privacy / cross-platform rules, the documentation workflow, and commit rules.

Do not implement dotfiles, run Stow, create symlinks, or modify $HOME without explicit user approval and an approved plan.

Repository structure

.claude/          Claude Code agents, rules, and skills
stow/
  common/         Packages that work on both platforms (source of truth)
  macos/          macOS-specific packages (empty)
  arch/           Arch / EndeavourOS-specific packages (empty)
docs/
  guides/         Human setup guides, one per package
  architecture/   Structure decisions and tradeoffs
  decisions/      ADR-style decision records
  plans/          Ordered implementation plans
  prd/            Product requirements documents
  reviews/        Review reports
  claude/         Agent guides and workflow documentation
AGENTS.md         Main operating contract — read this first
CLAUDE.md         Claude Code entry point

CI

GitHub Actions runs on every push and pull request, performing non-destructive hygiene checks only: verifies expected files/directories exist, checks Markdown is present, runs bash -n on shell scripts, and scans for obvious secret patterns. It never runs Stow, creates symlinks, modifies $HOME, uses secrets, or deploys anything.

License

See LICENSE.