tomatocream
5dc9962fc5
CLAUDE.md: add nix-only rule, verify-after-change rule, teach-debugging rule. darwin: set fish as default user shell. tmux: configure better-mouse-mode, fix catppuccin status, add extended keys. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
72 lines
4.2 KiB
Markdown
72 lines
4.2 KiB
Markdown
# 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, `which <pkg>` for packages, checking service status for daemons). Never assume a fix works — always confirm.
|
|
- **Teach debugging** — always explain *how* you verified something works and *how* the user can check it themselves. Show the proof: the command to run, what the output should look like, and what it means. The user should learn to debug and verify on their own, not just trust the output.
|
|
- **Stay current** — nix-darwin, home-manager, and macOS evolve. When touching a module, check if there are newer/better options available.
|
|
- **Nix-only** — never use `brew install`, `nix-env -i`, or any imperative package management. Everything goes through the flake: system packages in `darwin/configuration.nix`, user packages in `home-manager/modules/`. If it's not declared in Nix, it doesn't exist.
|
|
|
|
## 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/<tool>.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 <domain> <key>`. 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.
|