dotfiles/CLAUDE.md

CLAUDE.md

Purpose

This repository defines a complete Wayland desktop environment built around Niri, with a focus on:

• Simplicity
• Reproducibility
• Fast startup
• Low cognitive overhead
• Clean separation of concerns

Claude should act as a systems engineer, not just a script generator.

---

Core Principles

1. Single Source of Truth

• All configuration lives in ~/.config via symlinks
• No duplication across tools
• Shared values (theme, fonts, gaps, etc.) should be centralized

2. Idempotent Setup

• install.sh must be safe to re-run
• No destructive operations without explicit flags
• Detect and skip existing correct state

3. Composability

• Each tool (waybar, mako, wofi, etc.) is independent
• No hidden coupling unless explicitly documented

4. Declarative > Imperative

• Prefer static config over runtime scripts
• Avoid background daemons unless required

---

Expected Claude Behavior

When modifying this repo, Claude should:

Configuration Changes

• Keep configs minimal and readable
• Avoid introducing magic or implicit behavior
• Prefer explicit keybindings and comments

Adding Features

• Justify why the feature exists
• Ensure it fits Wayland + Niri workflow
• Avoid X11 dependencies unless unavoidable

Refactoring

• Reduce duplication across configs
• Extract shared values (colors, fonts, spacing)
• Keep file structure intuitive

---

Directory Expectations

dotfiles/
├── config/
│   ├── niri/
│   ├── waybar/
│   ├── alacritty/
│   ├── fish/
│   ├── starship/
│   ├── wofi/
│   ├── mako/
│   ├── gtklock/
│   └── ...
├── install.sh
├── packages.txt
└── README.md

---

Tooling Rules

Niri

• All keybindings must be defined here
• Window rules must be deterministic
• Avoid runtime scripting where possible

Waybar

• Keep modules minimal
• Prefer JSON config over scripts
• Avoid polling when event-based is possible

Fish + Starship

• Fast startup is critical
• No blocking operations
• Avoid heavy plugins

Wofi

• Keep styling consistent with GTK theme
• Avoid unnecessary wrappers

Mako

• Notifications should be minimal and non-intrusive
• Timeout defaults should be short

---

Theming

Theme: Tomorrow Night

Ensure consistency across:

• GTK (Materia-dark)
• Icons (Papirus)
• Terminal (Alacritty)
• Waybar
• Wofi

Claude should:

• Reuse the same color palette everywhere
• Avoid hardcoding colors in multiple places

---

Install Script Expectations

install.sh must:

1. Symlink configs into ~/.config
2. Install packages from packages.txt
3. Detect distro (Arch-based assumed unless specified)
4. Fail fast on errors
5. Print clear status messages

---

Anti-Patterns (DO NOT DO)

• ❌ Duplicate configs across tools
• ❌ Add large frameworks or dependencies
• ❌ Introduce race conditions in startup
• ❌ Use sleep-based timing hacks
• ❌ Hardcode machine-specific paths

---

Safe Enhancements

Claude may suggest:

• Shared theme variables
• Config generation (if simple and transparent)
• Modular config structure
• Performance improvements (startup, memory)

---

Testing Expectations

After changes:

• Niri starts without errors
• Waybar loads correctly
• No missing fonts/icons
• No broken keybindings
• No noticeable startup delay

---

Output Style

When generating code:

• Provide complete files (not fragments)
• Keep formatting clean
• Avoid unnecessary comments
• Prefer clarity over cleverness

---

Summary

This is a minimal, fast, reproducible Wayland environment.

Claude’s role is to:

• Maintain clarity
• Prevent bloat
• Improve consistency
• Keep everything predictable