codex: support XDG Base Directory specification

- Configuration file is now placed in XDG_CONFIG_HOME/codex/config.toml by default for versions >=0.2.0 when preferXdgDirectories is enabled.
- Falls back to ~/.codex/config.yaml for versions <0.2.0 and to ~/.codex/config.toml when preferXdgDirectories is disabled
- Sets CODEX_HOME environment variable to $XDG_CONFIG_HOME/codex when using XDG directories.
- Updated tests to verify XDG directory behavior and environment variable presence.

modules/programs/codex.nix

@@ -15,7 +15,6 @@ let
   packageVersion = if cfg.package != null then lib.getVersion cfg.package else "0.2.0";
   isTomlConfig = lib.versionAtLeast packageVersion "0.2.0";
   settingsFormat = if isTomlConfig then tomlFormat else yamlFormat;
-  configFileName = if isTomlConfig then ".codex/config.toml" else ".codex/config.yaml";
 in
 {
   meta.maintainers = [
@@ -31,7 +30,9 @@ in
       # NOTE: `yaml` type supports null, using `nullOr` for backwards compatibility period
       type = lib.types.nullOr tomlFormat.type;
       description = ''
-        Configuration written to {file}`~/.codex/config.toml` (0.2.0+) or {file}`~/.codex/config.yaml` (<0.2.0).
+        Configuration written to {file}`CODEX_HOME/config.toml` (0.2.0+)
+        or {file}`~/.codex/config.yaml` (<0.2.0). Per default {env}`CODEX_HOME`
+        defaults to ~/.codex.
         See <https://github.com/openai/codex/blob/main/codex-rs/config.md> for supported values.
       '';
       default = { };
@@ -63,16 +64,27 @@ in
     };
   };
 
-  config = mkIf cfg.enable {
-    home.packages = mkIf (cfg.package != null) [ cfg.package ];
-    home.file = {
-      "${configFileName}" = lib.mkIf (cfg.settings != { }) {
-        source = settingsFormat.generate "codex-config" cfg.settings;
-      };
-      ".codex/AGENTS.md" = lib.mkIf (cfg.custom-instructions != "") {
-        text = cfg.custom-instructions;
+  config =
+    let
+      useXdgDirectories = (config.home.preferXdgDirectories && isTomlConfig);
+      xdgConfigHome = lib.removePrefix config.home.homeDirectory config.xdg.configHome;
+      configDir = if useXdgDirectories then "${xdgConfigHome}/codex" else ".codex";
+      configFileName = if isTomlConfig then "config.toml" else "config.yaml";
+    in
+    mkIf cfg.enable {
+      home = {
+        packages = mkIf (cfg.package != null) [ cfg.package ];
+        file = {
+          "${configDir}/${configFileName}" = lib.mkIf (cfg.settings != { }) {
+            source = settingsFormat.generate "codex-config" cfg.settings;
+          };
+          "${configDir}/AGENTS.md" = lib.mkIf (cfg.custom-instructions != "") {
+            text = cfg.custom-instructions;
+          };
+        };
+        sessionVariables = mkIf useXdgDirectories {
+          CODEX_HOME = "${config.xdg.configHome}/codex";
+        };
       };
     };
-  };
-
 }

tests/modules/programs/codex/custom-instructions-prefer-xdg-directories.nix

@@ -0,0 +1,17 @@
+{
+  home.preferXdgDirectories = true;
+  programs.codex = {
+    enable = true;
+    custom-instructions = ''
+      - Always respond with emojis
+      - Only use git commands when explicitly requested
+    '';
+  };
+  nmt.script = ''
+    assertFileContains home-path/etc/profile.d/hm-session-vars.sh \
+      'export CODEX_HOME="/home/hm-user/.config/codex"'
+    assertFileExists home-files/.config/codex/AGENTS.md
+    assertFileContent home-files/.config/codex/AGENTS.md \
+      ${./AGENTS.md}
+  '';
+}

tests/modules/programs/codex/default.nix

@@ -1,7 +1,9 @@
 {
   codex-settings-toml = ./settings-toml.nix;
+  codex-settings-toml-prefer-xdg-directories = ./settings-toml-prefer-xdg-directories.nix;
   codex-settings-yaml = ./settings-yaml.nix;
   codex-empty-settings = ./empty-settings.nix;
   codex-custom-instructions = ./custom-instructions.nix;
+  codex-custom-instructions-prefer-xdg-directories = ./custom-instructions-prefer-xdg-directories.nix;
   codex-empty-custom-instructions = ./empty-custom-instructions.nix;
 }

tests/modules/programs/codex/empty-settings.nix

@@ -6,5 +6,6 @@
   nmt.script = ''
     assertPathNotExists home-files/.codex/config.toml
     assertPathNotExists home-files/.codex/config.yaml
+    assertFileNotRegex home-path/etc/profile.d/hm-session-vars.sh 'CODEX_HOME'
   '';
 }

tests/modules/programs/codex/settings-toml-prefer-xdg-directories.nix

@@ -0,0 +1,33 @@
+{ pkgs, ... }:
+let
+  codexPackage = pkgs.runCommand "codex-0.2.0" { } ''
+    mkdir -p $out/bin
+    echo '#!/bin/sh' > $out/bin/codex
+    chmod +x $out/bin/codex
+  '';
+in
+{
+  home.preferXdgDirectories = true;
+  programs.codex = {
+    enable = true;
+    package = codexPackage;
+    settings = {
+      model = "gemma3:latest";
+      model_provider = "ollama";
+      model_providers = {
+        ollama = {
+          name = "Ollama";
+          baseURL = "http://localhost:11434/v1";
+          envKey = "OLLAMA_API_KEY";
+        };
+      };
+    };
+  };
+  nmt.script = ''
+    assertFileContains home-path/etc/profile.d/hm-session-vars.sh \
+      'export CODEX_HOME="/home/hm-user/.config/codex"'
+    assertFileExists home-files/.config/codex/config.toml
+    assertFileContent home-files/.config/codex/config.toml \
+      ${./config.toml}
+  '';
+}

tests/modules/programs/codex/settings-toml.nix

@@ -26,5 +26,6 @@ in
     assertFileExists home-files/.codex/config.toml
     assertFileContent home-files/.codex/config.toml \
       ${./config.toml}
+    assertFileNotRegex home-path/etc/profile.d/hm-session-vars.sh 'CODEX_HOME'
   '';
 }