CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

Master dotfiles repo for a Hyprland desktop on Arch Linux. It has two halves:

src/ — a small interactive TypeScript CLI (install/update/remove) that manages packages and dotfiles.
packages/ — the actual dotfiles, laid out as GNU Stow packages (one top-level dir per app, mirroring $HOME, e.g. packages/waybar/.config/waybar/config).

The CLI is the only orchestration layer; it shells out to the real stow, pacman, and yay binaries rather than reimplementing symlinking or package management.

Commands

npm install
npm start install   # interactive: choose packages, installs them, backs up conflicting files, symlinks into $HOME
npm start update     # pacman -Syu + yay -Syu, then re-links (stow --restow) any new files
npm start remove     # removes symlinks (stow -D), restores the most recent backup (does NOT uninstall packages)
npx tsc --noEmit     # typecheck (no test suite or lint script exists)

There is no build step — tsx runs the TypeScript directly.

Architecture

src/packages.ts — the package model. Each entry has a tier (required installs with no prompt; recommended is offered via checkbox), an optional group for mutually-exclusive alternatives (e.g. waybar vs ags both have group: "bar", only one gets picked via a select prompt), and an optional dir when the Stow directory name differs from the package name (e.g. package rofi-wayland → dir rofi). toDirs() converts chosen package names to their Stow directory names.
src/stow.ts — all filesystem/process side effects live here: bootstrapping yay and oh-my-zsh/zinit if missing, installing packages via yay, backing up real (non-symlink) files that would collide with a Stow target into ~/.dotfiles-backup/<timestamp>/, and wrapping stow/--restow/-D (always invoked with an explicit -d <PACKAGES_DIR> so behavior doesn't depend on cwd). Also reads/writes ~/.config/dotfiles/state.json, which records which package dirs were chosen at install time — update and remove act on this list rather than re-prompting.
src/install.ts, src/update.ts, src/remove.ts — the three subcommands, each a thin sequence of calls into stow.ts, using @clack/prompts for interactive selection in install.ts.
src/cli.ts — dispatches install|update|remove via Node's built-in node:util.parseArgs.

Adding a new app

Add a directory under packages/ mirroring its $HOME layout (e.g. packages/foo/.config/foo/config), then add a matching entry to src/packages.ts (dir if the Stow directory name differs from the package name, group if it's a mutually-exclusive alternative to another package).

Backup/restore

Backups are stored under ~/.dotfiles-backup/<timestamp>/, mirroring the relative path of whatever real file was moved aside before stowing. remove restores only the most recent backup automatically; restoring an older one is a manual cp -a ~/.dotfiles-backup/<timestamp>/. ~/.

3.1 KiB Raw Blame History