codex: init

modules/modules.nix

@@ -92,6 +92,7 @@ let
       ./programs/chromium.nix
       ./programs/clock-rs.nix
       ./programs/cmus.nix
+      ./programs/codex.nix
       ./programs/command-not-found/command-not-found.nix
       ./programs/comodoro.nix
       ./programs/darcs.nix

modules/programs/codex.nix

@@ -0,0 +1,67 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+let
+  inherit (lib) mkIf;
+
+  cfg = config.programs.codex;
+
+  settingsFormat = pkgs.formats.yaml { };
+in
+{
+  meta.maintainers = [
+    lib.hm.maintainers.delafthi
+  ];
+
+  options.programs.codex = {
+    enable = lib.mkEnableOption "Lightweight coding agent that runs in your terminal";
+
+    package = lib.mkPackageOption pkgs "codex" { nullable = true; };
+
+    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.
+      '';
+      default = { };
+      defaultText = lib.literalExpression "{ }";
+      example = lib.literalExpression ''
+        {
+          model = "gemma3:latest";
+          provider = "ollama";
+          providers = {
+            ollama = {
+              name = "Ollama";
+              baseURL = "http://localhost:11434/v1";
+              envKey = "OLLAMA_API_KEY";
+            };
+          };
+        }
+      '';
+    };
+    custom-instructions = lib.mkOption {
+      type = lib.types.lines;
+      description = "Define custom guidance for the agents; this value is written to {file}~/.codex/AGENTS.md";
+      default = "";
+      example = lib.literalExpression ''
+        '''
+          - Always respond with emojis
+          - Only use git commands when explicitly requested
+        '''
+      '';
+    };
+  };
+
+  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;
+    };
+  };
+
+}

tests/darwinScrublist.nix

@@ -29,6 +29,7 @@ let
     "cava"
     "clock-rs"
     "cmus"
+    "codex"
     "comodoro"
     "darcs"
     "delta"

tests/default.nix

@@ -190,6 +190,7 @@ import nmtSrc {
       ./modules/programs/cava
       ./modules/programs/clock-rs
       ./modules/programs/cmus
+      ./modules/programs/codex
       ./modules/programs/comodoro
       ./modules/programs/darcs
       ./modules/programs/dircolors

tests/modules/programs/codex/custom-instructions.md

@@ -0,0 +1,2 @@
+- Always respond with emojis
+- Only use git commands when explicitly requested

tests/modules/programs/codex/custom-instructions.nix

@@ -0,0 +1,14 @@
+{
+  programs.codex = {
+    enable = true;
+    custom-instructions = ''
+      - Always respond with emojis
+      - Only use git commands when explicitly requested
+    '';
+  };
+  nmt.script = ''
+    assertFileExists home-files/.codex/AGENTS.md
+    assertFileContent home-files/.codex/AGENTS.md \
+      ${./custom-instructions.md}
+  '';
+}

tests/modules/programs/codex/default.nix

@@ -0,0 +1,4 @@
+{
+  codex-settings = ./settings.nix;
+  codex-custom-instructions = ./custom-instructions.nix;
+}

tests/modules/programs/codex/settings.nix

@@ -0,0 +1,21 @@
+{
+  programs.codex = {
+    enable = true;
+    settings = {
+      model = "gemma3:latest";
+      provider = "ollama";
+      providers = {
+        ollama = {
+          name = "Ollama";
+          baseURL = "http://localhost:11434/v1";
+          envKey = "OLLAMA_API_KEY";
+        };
+      };
+    };
+  };
+  nmt.script = ''
+    assertFileExists home-files/.codex/config.yaml
+    assertFileContent home-files/.codex/config.yaml \
+      ${./settings.yml}
+  '';
+}

tests/modules/programs/codex/settings.yml

@@ -0,0 +1,7 @@
+model: gemma3:latest
+provider: ollama
+providers:
+  ollama:
+    baseURL: http://localhost:11434/v1
+    envKey: OLLAMA_API_KEY
+    name: Ollama