iot-rocket · iot-rocket · Aug 30, 2025 · Aug 30, 2025
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -15,6 +15,7 @@ jobs:
         features:
           - adr-tools
           - chrome
+          - codex
           - color
           - hello
           - imagemagick
@@ -43,6 +44,7 @@ jobs:
           - adr-tools
           - chrome
           - claude-code
+          - codex
           - color
           - hello
           - imagemagick

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -32,6 +32,7 @@ This is Tobias Maier's Dev Container Features collection - a repository for crea
 - `adr-tools` - Architecture Decision Records tools
 - `chrome` - Google Chrome installation
 - `claude-code` - Claude Code CLI for AI-powered development assistance
+- `codex` - OpenAI Codex CLI for local AI-powered coding assistance
 - `imagemagick` - ImageMagick image processing tools
 - `mc` - MinIO Client for object storage
 - `mcp-language-server` - MCP Language Server for semantic code navigation

diff --git a/README.md b/README.md
@@ -9,6 +9,7 @@ A collection of custom [Dev Container Features](https://containers.dev/implement
 | [adr-tools](https://github.com/tmaier/devcontainer-features/tree/main/src/adr-tools) | Architecture Decision Records management tools | `ghcr.io/tmaier/devcontainer-features/adr-tools` |
 | [chrome](https://github.com/tmaier/devcontainer-features/tree/main/src/chrome) | Google Chrome with container-optimized wrapper script | `ghcr.io/tmaier/devcontainer-features/chrome` |
 | [claude-code](https://github.com/tmaier/devcontainer-features/tree/main/src/claude-code) | Claude Code CLI for AI-powered development assistance | `ghcr.io/tmaier/devcontainer-features/claude-code` |
+| [codex](https://github.com/tmaier/devcontainer-features/tree/main/src/codex) | OpenAI Codex CLI for local AI-powered coding assistance | `ghcr.io/tmaier/devcontainer-features/codex` |
 | [imagemagick](https://github.com/tmaier/devcontainer-features/tree/main/src/imagemagick) | ImageMagick image processing library with PDF support | `ghcr.io/tmaier/devcontainer-features/imagemagick` |
 | [mc](https://github.com/tmaier/devcontainer-features/tree/main/src/mc) | MinIO Client for object storage operations | `ghcr.io/tmaier/devcontainer-features/mc` |
 | [mcp-language-server](https://github.com/tmaier/devcontainer-features/tree/main/src/mcp-language-server) | MCP Language Server for semantic code navigation | `ghcr.io/tmaier/devcontainer-features/mcp-language-server` |

diff --git a/src/codex/NOTES.md b/src/codex/NOTES.md
@@ -0,0 +1,31 @@
+# Codex CLI Feature
+
+This feature installs [Codex CLI](https://github.com/openai/codex), OpenAI's local coding agent for AI-powered development assistance.
+
+## Requirements
+
+- Node.js
+
+## Manual config for `devcontainer.json`
+
+Mount the local `~/.codex/` directory into the Dev Container.
+Add the following mount to the `devcontainer.json` file.
+Replace `vscode` with the actual name of your user (see `remoteUser` property)
+
+```json
+  "mounts": [
+    {
+      "source": "${localEnv:HOME}/.codex",
+      "target": "/home/vscode/.codex",
+      "type": "bind"
+    }
+  ],
+```
+
+## Usage
+
+After installation, run `codex` in your project directory to get started.
+
+You'll need to sign in with a ChatGPT account (Plus, Pro, Team, Edu, or Enterprise plans recommended for best experience).
+
+For detailed documentation, see the [Codex CLI documentation](https://github.com/openai/codex).
diff --git a/src/codex/README.md b/src/codex/README.md
@@ -0,0 +1,60 @@
+# Codex CLI (codex)
+
+Installs OpenAI Codex CLI for local AI-powered coding assistance
+
+## Example Usage
+
+```json
+"features": {
+    "ghcr.io/tmaier/devcontainer-features/codex:1": {}
+}
+```
+
+## Options
+
+| Options Id | Description | Type | Default Value |
+|-----|-----|-----|-----|
+
+
+## Customizations
+
+### VS Code Extensions
+
+- `openai.chatgpt`
+
+# Codex CLI Feature
+
+This feature installs [Codex CLI](https://github.com/openai/codex), OpenAI's local coding agent for AI-powered development assistance.
+
+## Requirements
+
+- Node.js
+
+## Manual config for `devcontainer.json`
+
+Mount the local `~/.codex/` directory into the Dev Container.
+Add the following mount to the `devcontainer.json` file.
+Replace `vscode` with the actual name of your user (see `remoteUser` property)
+
+```json
+  "mounts": [
+    {
+      "source": "${localEnv:HOME}/.codex",
+      "target": "/home/vscode/.codex",
+      "type": "bind"
+    }
+  ],
+```
+
+## Usage
+
+After installation, run `codex` in your project directory to get started.
+
+You'll need to sign in with a ChatGPT account (Plus, Pro, Team, Edu, or Enterprise plans recommended for best experience).
+
+For detailed documentation, see the [Codex CLI documentation](https://github.com/openai/codex).
+
+
+---
+
+_Note: This file was auto-generated from the [devcontainer-feature.json](https://github.com/tmaier/devcontainer-features/blob/main/src/codex/devcontainer-feature.json).  Add additional notes to a `NOTES.md`._
diff --git a/src/codex/devcontainer-feature.json b/src/codex/devcontainer-feature.json
@@ -0,0 +1,18 @@
+{
+  "id": "codex",
+  "version": "1.0.0",
+  "name": "Codex CLI",
+  "description": "Installs OpenAI Codex CLI for local AI-powered coding assistance",
+  "options": {},
+  "installsAfter": [
+    "ghcr.io/devcontainers/features/node"
+  ],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "openai.chatgpt"
+      ]
+    }
+  },
+  "postStartCommand": "if command -v codex &>/dev/null; then codex --version || true; fi"
+}
diff --git a/src/codex/install.sh b/src/codex/install.sh
@@ -0,0 +1,44 @@
+#!/bin/bash
+set -e
+
+echo "Installing Codex CLI..."
+
+# Check if Node.js is available
+if ! command -v node &> /dev/null; then
+    echo "Error: Node.js is required but not found. Please ensure the Node.js feature is installed."
+    exit 1
+fi
+
+# Check Node.js version (requires 18+)
+NODE_VERSION=$(node --version | sed 's/v//')
+MAJOR_VERSION=$(echo $NODE_VERSION | cut -d. -f1)
+
+if [ "$MAJOR_VERSION" -lt 18 ]; then
+    echo "Error: Node.js 18+ is required, but found version $NODE_VERSION"
+    exit 1
+fi
+
+# Check if npm is available
+if ! command -v npm &> /dev/null; then
+    echo "Error: npm is required but not found."
+    exit 1
+fi
+
+# Install Codex CLI - prefer remote user installation if available
+if [ -n "$_REMOTE_USER" ] && [ "$_REMOTE_USER" != "root" ]; then
+    echo "Installing Codex CLI as user: $_REMOTE_USER"
+    NPM_PATH=$(which npm)
+    BIN_DIR=$(dirname "$NPM_PATH")
+    su "$_REMOTE_USER" -c "PATH=$BIN_DIR:\$PATH $NPM_PATH install -g @openai/codex"
+else
+    echo "Installing Codex CLI globally as root"
+    npm install -g @openai/codex
+fi
+
+# Verify installation
+if ! command -v codex &> /dev/null; then
+    echo "Error: Codex CLI installation failed"
+    exit 1
+fi
+
+echo "Codex CLI installed successfully!"
diff --git a/test/codex/codex_with_custom_user.sh b/test/codex/codex_with_custom_user.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# This test file will be executed against the 'codex_with_custom_user' scenario
+# to verify that Codex CLI is properly installed with a custom remote user.
+
+set -e
+
+# Optional: Import test library bundled with the devcontainer CLI
+source dev-container-features-test-lib
+
+# Feature-specific tests - simple smoke test
+# The 'check' command comes from the dev-container-features-test-lib.
+check "node is available" which node
+check "npm is available" which npm
+check "codex command available" which codex
+check "codex shows version" bash -c "codex --version"
+
+# Report results
+# If any of the checks above exited with a non-zero exit code, the test will fail.
+reportResults
diff --git a/test/codex/codex_with_node_feature.sh b/test/codex/codex_with_node_feature.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# This test file will be executed against the 'codex_with_node_feature' scenario
+# to verify that Codex CLI is properly installed with Node.js feature dependency.
+
+set -e
+
+# Optional: Import test library bundled with the devcontainer CLI
+source dev-container-features-test-lib
+
+# Feature-specific tests - simple smoke test
+# The 'check' command comes from the dev-container-features-test-lib.
+check "node is available" which node
+check "npm is available" which npm
+check "codex command available" which codex
+check "codex shows version" bash -c "codex --version"
+
+# Report results
+# If any of the checks above exited with a non-zero exit code, the test will fail.
+reportResults
diff --git a/test/codex/codex_with_node_image.sh b/test/codex/codex_with_node_image.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# This test file will be executed against the 'codex_with_node_image' scenario
+# to verify that Codex CLI is properly installed on a Node.js base image.
+
+set -e
+
+# Optional: Import test library bundled with the devcontainer CLI
+source dev-container-features-test-lib
+
+# Feature-specific tests - simple smoke test
+# The 'check' command comes from the dev-container-features-test-lib.
+check "node is available" which node
+check "npm is available" which npm
+check "codex command available" which codex
+check "codex shows version" bash -c "codex --version"
+
+# Report results
+# If any of the checks above exited with a non-zero exit code, the test will fail.
+reportResults
diff --git a/test/codex/scenarios.json b/test/codex/scenarios.json
@@ -0,0 +1,27 @@
+{
+    "codex_with_node_feature": {
+        "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+        "features": {
+            "ghcr.io/devcontainers/features/node:1": {
+                "version": "lts"
+            },
+            "codex": {}
+        }
+    },
+    "codex_with_node_image": {
+        "image": "mcr.microsoft.com/devcontainers/javascript-node:1-20-bullseye",
+        "features": {
+            "codex": {}
+        }
+    },
+    "codex_with_custom_user": {
+        "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+        "remoteUser": "vscode",
+        "features": {
+            "ghcr.io/devcontainers/features/node:1": {
+                "version": "lts"
+            },
+            "codex": {}
+        }
+    }
+}