diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..eee1b53
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,71 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+NixOS dotfiles repository using Nix Flakes for managing multiple machines. Configuration is in French (comments, docs).
+
+## Build & Deploy Commands
+
+```bash
+# Rebuild and switch configuration (local)
+sudo nixos-rebuild switch --flake .#<hostname>
+
+# Rebuild on remote machine
+nixos-rebuild switch --flake .#<hostname> --target-host beastie@<ip> --sudo
+
+# Bootstrap new machine with nixos-anywhere
+nixos-anywhere --flake .#generic --target-host root@<ip> \
+  --generate-hardware-config nixos-generate-config ./hosts/generic/hardware-configuration.nix
+
+# Generate custom ISO
+nixos-generate --format iso --configuration ./iso/customiso.nix -o ~/Downloads/nixos.iso
+
+# Update flake inputs
+nix flake update
+
+# Update secrets after adding new host key
+sops updatekeys secrets.yaml
+nix flake update mysecrets
+```
+
+## Architecture
+
+**Flake Inputs:**
+- `nixpkgs-stable` (25.05) and `nixpkgs-unstable` channels
+- `disko` for declarative disk partitioning
+- `sops-nix` for encrypted secrets
+- `mysecrets` - local git repo at `/home/beastie/nixos/secrets` (required dependency)
+
+**Hosts:** `generic` (ISO), `test-kvm` (stable), `home-nix` (unstable), `work-nix` (unstable)
+
+**Module Hierarchy:**
+1. `modules/core/` - Applied to ALL hosts (grub, ssh, packages, users, tty, system)
+2. `modules/optionnals/` - Selectively imported per host
+3. `modules/optionnals/hosts/<hostname>.nix` - Host-specific networking, services
+4. `modules/optionnals/desktop/` - Desktop environment modules (Hyprland, apps)
+
+## Key Patterns
+
+**Custom Options** (`modules/optionnals/options.nix`):
+- `my.laninterface`, `my.ipv4address`, `my.ipv4netmask`, `my.ipv4gateway`, `my.wolipv6address`
+
+**Special Args** passed to all modules via flake.nix:
+- `hostname` and `username` - used for host/user-specific configuration
+
+**Secrets (sops-nix):**
+- Encrypted YAML in separate `mysecrets` repo
+- Referenced via `config.sops.secrets.<name>.path` or `config.sops.templates`
+- Age encryption with SSH host keys
+
+**XDG Config Distribution:**
+- Desktop configs (hyprland, waybar, kitty, rofi) use `environment.etc."xdg/<app>".source`
+- Host-specific variants: `hyprland-${hostname}.conf`
+
+## Important Considerations
+
+- Test changes on `test-kvm` before deploying to production hosts
+- `mysecrets` flake input must exist locally at `/home/beastie/nixos/secrets`
+- Different hosts use different `stateVersion` (25.05 vs 25.11)
+- Core module changes affect ALL machines
diff --git a/modules/optionnals/desktop/code.nix b/modules/optionnals/desktop/code.nix
index a041f0e..45ac485 100644
--- a/modules/optionnals/desktop/code.nix
+++ b/modules/optionnals/desktop/code.nix
@@ -94,5 +94,6 @@ in
     pkgs.nixfmt
     pkgs.ansible
     pkgs.python313
+    pkgs.claude-code
   ];
 }