claude-code: respect preferXdgDirectories

docs/release-notes/rl-2611.md

@@ -361,3 +361,10 @@ changes are only active if the `home.stateVersion` option is set to
   - `programs.zellij.settings`
   - `programs.zellij.themes`
   - `programs.zellij.layouts`
+
+- The default value of [](#opt-programs.claude-code.configDir) changes
+  from `~/.claude` to `${config.xdg.configHome}/claude` when
+  [](#opt-home.preferXdgDirectories) is enabled. Existing Claude Code data in
+  `~/.claude` is not migrated automatically. Move it to the new directory
+  before upgrading, or preserve the previous location by setting
+  `programs.claude-code.configDir = "${config.home.homeDirectory}/.claude"`.

modules/misc/news/2026/10/2026-10-10_15-42-25.nix

@@ -0,0 +1,20 @@
+{ config, ... }:
+{
+  time = "2026-10-10T22:42:25+00:00";
+  condition =
+    config.programs.claude-code.enable
+    && config.home.preferXdgDirectories
+    && config.programs.claude-code.configDir == "${config.xdg.configHome}/claude";
+  message = ''
+    `programs.claude-code.configDir` now defaults to
+    `''${config.xdg.configHome}/claude` when
+    `home.preferXdgDirectories` is true and `home.stateVersion` is at
+    least 26.11.
+
+    Existing Claude Code data in `~/.claude` is not migrated automatically.
+    Move it to the new directory, or preserve the previous behavior with:
+
+      programs.claude-code.configDir =
+        "''${config.home.homeDirectory}/.claude";
+  '';
+}

modules/programs/claude-code/options.nix

@@ -75,17 +75,52 @@ in
 
     configDir = mkOption {
       type = lib.types.str;
-      default = "${config.home.homeDirectory}/.claude";
-      defaultText = literalExpression ''"''${config.home.homeDirectory}/.claude"'';
+      inherit
+        (lib.hm.deprecations.mkStateVersionOptionDefault {
+          inherit (config.home) stateVersion;
+          since = "26.11";
+          optionPath = [
+            "programs"
+            "claude-code"
+            "configDir"
+          ];
+          legacy = {
+            value = "${config.home.homeDirectory}/.claude";
+            text = ''"''${config.home.homeDirectory}/.claude"'';
+          };
+          current = {
+            value =
+              if config.home.preferXdgDirectories then
+                "${config.xdg.configHome}/claude"
+              else
+                "${config.home.homeDirectory}/.claude";
+            text = ''"''${config.xdg.configHome}/claude"'';
+          };
+          extraWarning = ''
+            To keep existing Claude Code data, move `~/.claude` to
+            `$XDG_CONFIG_HOME/claude` before adopting the new default.
+          '';
+        })
+        default
+        ;
+      defaultText = literalExpression ''
+        if config.home.preferXdgDirectories && lib.versionAtLeast config.home.stateVersion "26.11" then
+          "''${config.xdg.configHome}/claude"
+        else
+          "''${config.home.homeDirectory}/.claude"
+      '';
       example = literalExpression ''"''${config.xdg.configHome}/claude"'';
       description = ''
         Directory holding Claude Code's configuration files.
 
         Defaults to {file}`~/.claude`, matching the upstream
-        {command}`claude` CLI default. The {env}`CLAUDE_CONFIG_DIR`
-        environment variable is exported automatically whenever the
-        directory differs from this default so the CLI reads
-        configuration from the same location.
+        {command}`claude` CLI default, or
+        {file}`''${config.xdg.configHome}/claude` when
+        {option}`home.preferXdgDirectories` is enabled and
+        {option}`home.stateVersion` is at least 26.11. The
+        {env}`CLAUDE_CONFIG_DIR` environment variable is exported
+        automatically whenever the directory differs from the upstream
+        default so the CLI reads configuration from the same location.
       '';
     };
 

tests/modules/programs/claude-code/default.nix

@@ -4,6 +4,8 @@
   claude-code-mutable-settings = ./mutable-settings.nix;
   claude-code-basic = ./basic.nix;
   claude-code-config-dir = ./config-dir.nix;
+  claude-code-prefer-xdg-directories = ./prefer-xdg-directories.nix;
+  claude-code-prefer-xdg-directories-legacy = ./prefer-xdg-directories-legacy.nix;
   claude-code-full-config = ./full-config.nix;
   claude-code-lsp = ./lsp.nix;
   claude-code-mcp = ./mcp.nix;

tests/modules/programs/claude-code/prefer-xdg-directories-legacy.nix

@@ -0,0 +1,21 @@
+{
+  home.stateVersion = "26.05";
+  home.preferXdgDirectories = true;
+
+  programs.claude-code = {
+    enable = true;
+    settings.theme = "dark";
+    context = "# Legacy context";
+  };
+
+  nmt.script = ''
+    assertPathNotExists home-files/.config/claude
+
+    assertFileExists home-files/.claude/settings.json
+    assertFileExists home-files/.claude/CLAUDE.md
+
+    assertFileExists home-path/etc/profile.d/hm-session-vars.sh
+    assertFileNotRegex home-path/etc/profile.d/hm-session-vars.sh \
+      'CLAUDE_CONFIG_DIR'
+  '';
+}

tests/modules/programs/claude-code/prefer-xdg-directories.nix

@@ -0,0 +1,21 @@
+{
+  home.stateVersion = "26.11";
+  home.preferXdgDirectories = true;
+
+  programs.claude-code = {
+    enable = true;
+    settings.theme = "dark";
+    context = "# XDG context";
+  };
+
+  nmt.script = ''
+    assertPathNotExists home-files/.claude
+
+    assertFileExists home-files/.config/claude/settings.json
+    assertFileExists home-files/.config/claude/CLAUDE.md
+
+    assertFileExists home-path/etc/profile.d/hm-session-vars.sh
+    assertFileRegex home-path/etc/profile.d/hm-session-vars.sh \
+      'export CLAUDE_CONFIG_DIR="/home/hm-user/.config/claude"'
+  '';
+}