diff --git a/modules/programs/codex.nix b/modules/programs/codex.nix
index d64910ebc..da4246722 100644
--- a/modules/programs/codex.nix
+++ b/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";
+        };
       };
     };
-  };
-
 }
diff --git a/tests/modules/programs/codex/custom-instructions-prefer-xdg-directories.nix b/tests/modules/programs/codex/custom-instructions-prefer-xdg-directories.nix
new file mode 100644
index 000000000..81fa7df08
--- /dev/null
+++ b/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}
+  '';
+}
diff --git a/tests/modules/programs/codex/default.nix b/tests/modules/programs/codex/default.nix
index 356e80163..e09892d08 100644
--- a/tests/modules/programs/codex/default.nix
+++ b/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;
 }
diff --git a/tests/modules/programs/codex/empty-settings.nix b/tests/modules/programs/codex/empty-settings.nix
index fd974e46e..c46da46b5 100644
--- a/tests/modules/programs/codex/empty-settings.nix
+++ b/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'
   '';
 }
diff --git a/tests/modules/programs/codex/settings-toml-prefer-xdg-directories.nix b/tests/modules/programs/codex/settings-toml-prefer-xdg-directories.nix
new file mode 100644
index 000000000..191aed8d7
--- /dev/null
+++ b/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}
+  '';
+}
diff --git a/tests/modules/programs/codex/settings-toml.nix b/tests/modules/programs/codex/settings-toml.nix
index a113fab3c..c38885870 100644
--- a/tests/modules/programs/codex/settings-toml.nix
+++ b/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'
   '';
 }