From 11cc64bd4c5132d580bf38fc66b4c587a39d8f45 Mon Sep 17 00:00:00 2001 From: Wong Ding Feng Date: Mon, 25 May 2026 12:42:32 +0800 Subject: [PATCH] add CLAUDE.md with repo philosophy: batteries-loaded macOS rice Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..8cec87d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,69 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What This Is + +A batteries-loaded macOS rice — cross-platform Nix configuration (nix-darwin + NixOS + home-manager) for user `df`. The active system is `m2n1` — an Apple Silicon Mac running nix-darwin. + +## Philosophy + +This repo strives for the **best possible macOS setup** with seamless UX: + +- **Better defaults everywhere** — keyboard, trackpad, Dock, Finder, screenshots, window management, etc. If macOS has a bad default, override it. +- **Batteries included** — tools, shell plugins, keybindings, and integrations should work out of the box. No manual post-install steps. +- **Rice it** — the setup should look and feel polished. Consistent theming, clean status bars, good typography. +- **Research before implementing** — when adding or changing something, check the internet for the best current practices, latest options, and what power users recommend. Don't guess. +- **Test it works** — after making changes, run `darwin-rebuild switch` and verify the setting actually took effect (e.g. `defaults read` for macOS prefs). The UX should be seamless. +- **Stay current** — nix-darwin, home-manager, and macOS evolve. When touching a module, check if there are newer/better options available. + +## Build Commands + +```bash +# Primary build+switch for macOS (requires sudo) +sudo darwin-rebuild build --flake ~/bankrupt/#m2n1 +sudo darwin-rebuild switch --flake ~/bankrupt/#m2n1 + +# Or via Makefile (auto-detects hostname) +make darwin-switch + +# Update flake inputs +make update + +# Format nix files +nix fmt + +# Validate flake +nix flake check +``` + +## Architecture + +``` +flake.nix # Entry point: inputs, overlays, system configs +├── common.nix # Shared nix settings (caches, overlays, GC) +├── darwin/configuration.nix # m2n1 system config (imports yabai.nix, skhd.nix) +├── nixos/configuration.nix # Template NixOS config +├── overlays/default.nix # Package overlays (emacs, unstable, custom) +└── home-manager/ + ├── home.nix # Imports all modules below + ├── common.nix # Base home-manager settings + ├── platform/ # darwin.nix / linux.nix (conditional via stdenv.isDarwin) + └── modules/ # Feature modules: git, shells, fish, tmux, kitty, neovim, doom-emacs + └── inbox/ # packages.nix (large package list), inbox.nix (dev tools) +``` + +## Key Patterns + +- **Platform conditionals**: `lib.mkIf pkgs.stdenv.isDarwin` / `lib.mkIf pkgs.stdenv.isLinux` +- **Flake inputs**: nixpkgs 25.05, home-manager release-25.05, nix-darwin darwin-25.05 +- **Determinate Nix**: `nix.enable = false` in darwin config (conflicts with nix-darwin's daemon) +- **Overlays** in `overlays/default.nix` feed into `common.nix` and are applied system-wide + +## Workflow Notes + +- To add a new package: edit `home-manager/modules/inbox/packages.nix` (user-level) or `darwin/configuration.nix` (system-level) +- To add a new tool module: create `home-manager/modules/.nix` and import it in `home-manager/home.nix` +- When build fails, read the error output carefully — common issues are hash mismatches (run `nix flake update`) or missing inputs +- **After changing `system.defaults`**: run `darwin-rebuild switch`, then verify with `defaults read `. Some settings need a logout/restart to take effect. +- **When adding a new default or tool**: search the web for current best practices before implementing. Check nix-darwin options, popular dotfile repos, and macOS power-user guides.