Skip to content

AGENTS.md

Latest commit

 

History

History
83 lines (63 loc) · 3.45 KB

AGENTS.md

File metadata and controls

83 lines (63 loc) · 3.45 KB

AGENTS.md

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

Build & Rebuild Commands

# Linux (NixOS/WSL)
nixos-rebuild switch --flake '.#linux' --sudo

# macOS - Work (Apple Silicon)
nix build '.#darwinConfigurations.work.system'
sudo ./result/sw/bin/darwin-rebuild switch --flake '.#work'

# macOS - Personal (Apple Silicon)
nix build '.#darwinConfigurations.personal.system'
sudo ./result/sw/bin/darwin-rebuild switch --flake '.#personal'

Validation & Development

nix flake check               # Validate configuration
nix flake check --all-systems # Check all platforms
nix build '.#darwinConfigurations.work.system'
nix build '.#darwinConfigurations.personal.system'
nix eval '.#nixosConfigurations.linux.config.system.stateVersion' # Local fallback on non-Linux hosts
nix fmt .                    # Format with nixfmt-tree
deadnix --edit .             # Remove unused code
nix develop                  # Enter dev shell with formatters/linters
nix flake update             # Update dependencies

Architecture

Multi-platform Nix flake supporting macOS (Darwin) and Linux with Home Manager integration.

System Configurations

Name Platform Use Case
work aarch64-darwin Apple Silicon work environment
personal aarch64-darwin Apple Silicon personal
linux x86_64-linux NixOS/WSL personal

Module Organization

  • modules/shared/programs/ - Cross-platform program configs (imported by both Darwin and Linux)
  • modules/shared/configuration.nix - Shared system-level entry that imports common libraries
  • modules/darwin/ - macOS system settings, homebrew, home.nix
  • modules/linux/ - Linux/WSL system settings, home.nix
  • libraries/home-manager/ - Shared Home Manager wiring via home-manager.sharedModules
  • libraries/nixpkgs/ - Overlays and allowUnfree policy
  • libraries/dev-shell/ - Development shell definition

Key Files

Task Location
Add shared program modules/shared/programs/<name>/default.nix
Darwin system settings modules/darwin/configuration.nix
Darwin environment-specific packages/brews/casks modules/darwin/environments/default.nix
Linux system settings modules/linux/configuration.nix
macOS packages & imports modules/darwin/home.nix
Linux packages & imports modules/linux/home.nix
Profile normalization flake.nix
Custom packages/overlays libraries/nixpkgs/default.nix
HM shared modules libraries/home-manager/default.nix

Conventions

  • Formatter: nixfmt-tree via nix fmt .
  • Module pattern: Each program gets programs/<name>/default.nix which aggregates feature modules
  • Unused args: Use _: for unused function arguments
  • Module flow: shared → darwin/linux → program-specific
  • Darwin environment split: manage work/personal differences in modules/darwin/environments/default.nix (packages, brews, casks, masApps, dockApps, sshIncludes, ageSecrets)
  • Profile source of truth: resolve environment-specific Darwin data once in flake.nix and pass it as profileConfig
  • Darwin package source of truth: put work-only tools (e.g. acli) in environments/default.nix and keep modules/darwin/home.nix as a thin platform wrapper over the shared HM layer

Git Hooks (lefthook)

  • pre-commit: Runs deadnix --edit . with auto-staging
⚡