diff --git a/modules/programs/codex.nix b/modules/programs/codex.nix
index a8b8d6061..260ed580f 100644
--- a/modules/programs/codex.nix
+++ b/modules/programs/codex.nix
@@ -9,7 +9,13 @@ let
 
   cfg = config.programs.codex;
 
-  settingsFormat = pkgs.formats.yaml { };
+  tomlFormat = pkgs.formats.toml { };
+  yamlFormat = pkgs.formats.yaml { };
+
+  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 = [
@@ -24,16 +30,16 @@ in
     settings = lib.mkOption {
       inherit (settingsFormat) type;
       description = ''
-        Configuration written to {file}`~/.codex/config.yaml`.
-        See <https://github.com/openai/codex#configuration-guide> for supported values.
+        Configuration written to {file}`~/.codex/config.toml` (0.2.0+) or {file}`~/.codex/config.yaml` (<0.2.0).
+        See <https://github.com/openai/codex/blob/main/codex-rs/config.md> for supported values.
       '';
       default = { };
       defaultText = lib.literalExpression "{ }";
       example = lib.literalExpression ''
         {
           model = "gemma3:latest";
-          provider = "ollama";
-          providers = {
+          model_provider = "ollama";
+          model_providers = {
             ollama = {
               name = "Ollama";
               baseURL = "http://localhost:11434/v1";
@@ -59,8 +65,12 @@ in
   config = mkIf cfg.enable {
     home.packages = mkIf (cfg.package != null) [ cfg.package ];
     home.file = {
-      ".codex/config.yaml".source = settingsFormat.generate "codex-config" cfg.settings;
-      ".codex/AGENTS.md".text = cfg.custom-instructions;
+      "${configFileName}" = lib.mkIf (cfg.settings != { }) {
+        source = settingsFormat.generate "codex-config" cfg.settings;
+      };
+      ".codex/AGENTS.md" = lib.mkIf (cfg.custom-instructions != "") {
+        text = cfg.custom-instructions;
+      };
     };
   };
 
diff --git a/tests/modules/programs/codex/custom-instructions.md b/tests/modules/programs/codex/AGENTS.md
similarity index 100%
rename from tests/modules/programs/codex/custom-instructions.md
rename to tests/modules/programs/codex/AGENTS.md
diff --git a/tests/modules/programs/codex/config.toml b/tests/modules/programs/codex/config.toml
new file mode 100644
index 000000000..abf9c7b47
--- /dev/null
+++ b/tests/modules/programs/codex/config.toml
@@ -0,0 +1,7 @@
+model = "gemma3:latest"
+model_provider = "ollama"
+
+[model_providers.ollama]
+baseURL = "http://localhost:11434/v1"
+envKey = "OLLAMA_API_KEY"
+name = "Ollama"
diff --git a/tests/modules/programs/codex/settings.yml b/tests/modules/programs/codex/config.yaml
similarity index 100%
rename from tests/modules/programs/codex/settings.yml
rename to tests/modules/programs/codex/config.yaml
diff --git a/tests/modules/programs/codex/custom-instructions.nix b/tests/modules/programs/codex/custom-instructions.nix
index 149c489da..46b6a7e5d 100644
--- a/tests/modules/programs/codex/custom-instructions.nix
+++ b/tests/modules/programs/codex/custom-instructions.nix
@@ -9,6 +9,6 @@
   nmt.script = ''
     assertFileExists home-files/.codex/AGENTS.md
     assertFileContent home-files/.codex/AGENTS.md \
-      ${./custom-instructions.md}
+      ${./AGENTS.md}
   '';
 }
diff --git a/tests/modules/programs/codex/default.nix b/tests/modules/programs/codex/default.nix
index 4e26d2914..356e80163 100644
--- a/tests/modules/programs/codex/default.nix
+++ b/tests/modules/programs/codex/default.nix
@@ -1,4 +1,7 @@
 {
-  codex-settings = ./settings.nix;
+  codex-settings-toml = ./settings-toml.nix;
+  codex-settings-yaml = ./settings-yaml.nix;
+  codex-empty-settings = ./empty-settings.nix;
   codex-custom-instructions = ./custom-instructions.nix;
+  codex-empty-custom-instructions = ./empty-custom-instructions.nix;
 }
diff --git a/tests/modules/programs/codex/empty-custom-instructions.nix b/tests/modules/programs/codex/empty-custom-instructions.nix
new file mode 100644
index 000000000..272ce1fb2
--- /dev/null
+++ b/tests/modules/programs/codex/empty-custom-instructions.nix
@@ -0,0 +1,9 @@
+{
+  programs.codex = {
+    enable = true;
+    custom-instructions = "";
+  };
+  nmt.script = ''
+    assertPathNotExists home-files/.codex/AGENTS.md
+  '';
+}
diff --git a/tests/modules/programs/codex/empty-settings.nix b/tests/modules/programs/codex/empty-settings.nix
new file mode 100644
index 000000000..fd974e46e
--- /dev/null
+++ b/tests/modules/programs/codex/empty-settings.nix
@@ -0,0 +1,10 @@
+{
+  programs.codex = {
+    enable = true;
+    settings = { };
+  };
+  nmt.script = ''
+    assertPathNotExists home-files/.codex/config.toml
+    assertPathNotExists home-files/.codex/config.yaml
+  '';
+}
diff --git a/tests/modules/programs/codex/settings-toml.nix b/tests/modules/programs/codex/settings-toml.nix
new file mode 100644
index 000000000..a113fab3c
--- /dev/null
+++ b/tests/modules/programs/codex/settings-toml.nix
@@ -0,0 +1,30 @@
+{ 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
+{
+  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 = ''
+    assertFileExists home-files/.codex/config.toml
+    assertFileContent home-files/.codex/config.toml \
+      ${./config.toml}
+  '';
+}
diff --git a/tests/modules/programs/codex/settings.nix b/tests/modules/programs/codex/settings-yaml.nix
similarity index 65%
rename from tests/modules/programs/codex/settings.nix
rename to tests/modules/programs/codex/settings-yaml.nix
index 23695230c..32bbc622c 100644
--- a/tests/modules/programs/codex/settings.nix
+++ b/tests/modules/programs/codex/settings-yaml.nix
@@ -1,6 +1,15 @@
+{ pkgs, ... }:
+let
+  codexPackage = pkgs.runCommand "codex-0.1.2504301751" { } ''
+    mkdir -p $out/bin
+    echo '#!/bin/sh' > $out/bin/codex
+    chmod +x $out/bin/codex
+  '';
+in
 {
   programs.codex = {
     enable = true;
+    package = codexPackage;
     settings = {
       model = "gemma3:latest";
       provider = "ollama";
@@ -16,6 +25,6 @@
   nmt.script = ''
     assertFileExists home-files/.codex/config.yaml
     assertFileContent home-files/.codex/config.yaml \
-      ${./settings.yml}
+      ${./config.yaml}
   '';
 }