bankrupt/CLAUDE.md

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

# 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.