feat: add Codex CLI support with Docker Bake build system

Add OpenAI Codex CLI as an alternative agent alongside Claude Code.
Users choose their agent at CLI launch time, and the system builds
separate Docker images per agent via a stack × agent matrix.

- Add docker-bake.hcl with stack × agent matrix (shared base layer)
- Split Dockerfile into Dockerfile.base, Dockerfile.claude, Dockerfile.codex
- Update entrypoint.sh and ralph-loop.sh to branch on AGENT_CLI env var
- Add detectCodexCredentials() to CLI with API key and auth.json support
- Add agent selection prompt to CLI flow
- Make stack image resolution agent-aware
- Update CI workflow to build/publish per agent variant
- Update stream-pretty.sh to handle both Claude and Codex JSON formats

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mariomeyer

.github/workflows/release.yml

@@ -67,7 +67,7 @@ jobs:
           npm pkg fix
           npm publish --access public --provenance
 
-  # Build each platform natively per stack (no QEMU emulation)
+  # Build each platform natively per stack × agent (no QEMU emulation)
   build:
     needs: [release]
     if: |
@@ -80,6 +80,7 @@ jobs:
       fail-fast: true
       matrix:
         stack: [laravel]
+        agent: [claude, codex]
         platform: [linux/amd64, linux/arm64]
         include:
           - platform: linux/amd64
@@ -101,15 +102,28 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Build and push by digest
+      - name: Build base image
+        uses: docker/build-push-action@v6
+        with:
+          context: stacks/${{ matrix.stack }}
+          file: stacks/${{ matrix.stack }}/Dockerfile.base
+          platforms: ${{ matrix.platform }}
+          load: true
+          tags: base:local
+          cache-from: type=gha,scope=${{ matrix.stack }}-base-${{ matrix.platform }}
+          cache-to: type=gha,scope=${{ matrix.stack }}-base-${{ matrix.platform }},mode=max
+
+      - name: Build and push agent image by digest
         id: build
         uses: docker/build-push-action@v6
         with:
           context: stacks/${{ matrix.stack }}
+          file: stacks/${{ matrix.stack }}/Dockerfile.${{ matrix.agent }}
           platforms: ${{ matrix.platform }}
-          outputs: type=image,name=${{ env.REGISTRY }}/reyemtech/${{ matrix.stack }}-upgrade-agent,push-by-digest=true,name-canonical=true,push=true
-          cache-from: type=gha,scope=${{ matrix.stack }}-${{ matrix.platform }}
-          cache-to: type=gha,scope=${{ matrix.stack }}-${{ matrix.platform }},mode=max
+          build-contexts: base=docker-image://base:local
+          outputs: type=image,name=${{ env.REGISTRY }}/reyemtech/${{ matrix.stack }}-upgrade-agent-${{ matrix.agent }},push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=${{ matrix.stack }}-${{ matrix.agent }}-${{ matrix.platform }}
+          cache-to: type=gha,scope=${{ matrix.stack }}-${{ matrix.agent }}-${{ matrix.platform }},mode=max
 
       - name: Export digest
         run: |
@@ -120,12 +134,12 @@ jobs:
       - name: Upload digest
         uses: actions/upload-artifact@v4
         with:
-          name: digests-${{ matrix.stack }}-${{ matrix.runner }}
+          name: digests-${{ matrix.stack }}-${{ matrix.agent }}-${{ matrix.runner }}
           path: /tmp/digests/*
           if-no-files-found: error
           retention-days: 1
 
-  # Merge per-platform images into a single multi-arch manifest per stack
+  # Merge per-platform images into a single multi-arch manifest per stack × agent
   publish:
     needs: [release, build]
     runs-on: ubuntu-latest
@@ -135,6 +149,7 @@ jobs:
     strategy:
       matrix:
         stack: [laravel]
+        agent: [claude, codex]
     steps:
       - uses: actions/checkout@v4
         with:
@@ -165,7 +180,7 @@ jobs:
         id: meta
         uses: docker/metadata-action@v5
         with:
-          images: ${{ env.REGISTRY }}/reyemtech/${{ matrix.stack }}-upgrade-agent
+          images: ${{ env.REGISTRY }}/reyemtech/${{ matrix.stack }}-upgrade-agent-${{ matrix.agent }}
           tags: |
             type=raw,value=latest
             type=semver,pattern={{version}},value=${{ steps.version.outputs.tag }}
@@ -177,16 +192,16 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           path: /tmp/digests
-          pattern: digests-${{ matrix.stack }}-*
+          pattern: digests-${{ matrix.stack }}-${{ matrix.agent }}-*
           merge-multiple: true
 
       - name: Create manifest list and push
         working-directory: /tmp/digests
         run: |
           docker buildx imagetools create \
             $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
-            $(printf '${{ env.REGISTRY }}/reyemtech/${{ matrix.stack }}-upgrade-agent@sha256:%s ' *)
+            $(printf '${{ env.REGISTRY }}/reyemtech/${{ matrix.stack }}-upgrade-agent-${{ matrix.agent }}@sha256:%s ' *)
 
       - name: Inspect image
         run: |
-          docker buildx imagetools inspect ${{ env.REGISTRY }}/reyemtech/${{ matrix.stack }}-upgrade-agent:${{ steps.meta.outputs.version }}
+          docker buildx imagetools inspect ${{ env.REGISTRY }}/reyemtech/${{ matrix.stack }}-upgrade-agent-${{ matrix.agent }}:${{ steps.meta.outputs.version }}

cli/src/credentials.js

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, access } from 'node:fs/promises';
 import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -113,3 +113,75 @@ export async function detectClaudeCredentials({ promptIfMissing = true } = {}) {
 
   return result;
 }
+
+/**
+ * Auto-detect Codex credentials.
+ * Priority: saved config > env vars > ~/.codex/auth.json > prompt
+ * @param {{ promptIfMissing?: boolean }} options
+ * @returns {{ type: 'apikey' | 'oauth', value: string, source: string } | null}
+ */
+export async function detectCodexCredentials({ promptIfMissing = true } = {}) {
+  // 1. Saved config (~/.stack-upgrade/config.json)
+  const saved = getConfig('codexCredentials');
+  if (saved?.value) {
+    return {
+      type: saved.type,
+      value: saved.value,
+      source: '~/.stack-upgrade/config.json',
+    };
+  }
+
+  // 2. OPENAI_API_KEY env var
+  if (process.env.OPENAI_API_KEY) {
+    return {
+      type: 'apikey',
+      value: process.env.OPENAI_API_KEY,
+      source: 'OPENAI_API_KEY env var',
+    };
+  }
+
+  // 3. ~/.codex/auth.json
+  try {
+    const authPath = join(homedir(), '.codex', 'auth.json');
+    await access(authPath);
+    const raw = await readFile(authPath, 'utf-8');
+    const b64 = Buffer.from(raw).toString('base64');
+    return {
+      type: 'oauth',
+      value: b64,
+      source: '~/.codex/auth.json',
+    };
+  } catch {
+    // File doesn't exist — continue
+  }
+
+  // 4. Prompt user (or return null if not allowed)
+  if (!promptIfMissing) return null;
+
+  const method = await p.select({
+    message: 'Codex credentials not found. How do you want to authenticate?',
+    options: [
+      { value: 'apikey', label: 'Paste OpenAI API key' },
+      { value: 'authjson', label: 'Paste auth.json content (base64)' },
+    ],
+  });
+  if (p.isCancel(method)) process.exit(0);
+
+  let result;
+
+  if (method === 'apikey') {
+    const value = await p.password({ message: 'Paste your OpenAI API key:' });
+    if (p.isCancel(value)) process.exit(0);
+    result = { type: 'apikey', value, source: 'manual input' };
+  } else {
+    const value = await p.password({ message: 'Paste your auth.json content (base64-encoded):' });
+    if (p.isCancel(value)) process.exit(0);
+    result = { type: 'oauth', value, source: 'manual input' };
+  }
+
+  // Save to config for next time
+  saveConfig({ codexCredentials: { type: result.type, value: result.value } });
+  p.log.success('Credentials saved to ~/.stack-upgrade/config.json');
+
+  return result;
+}

cli/src/docker.js

@@ -35,7 +35,7 @@ function pullImage(image) {
  * Launch a single Docker container for an upgrade.
  * @returns {{ containerName: string, outputDir: string }}
  */
-function startContainer({ repoUrl, targetVersion, push, suffix, ghToken, claudeCreds, image, stack, envKey }) {
+function startContainer({ repoUrl, targetVersion, push, suffix, ghToken, agentCreds, agentChoice, image, stack, envKey }) {
   const containerName = deriveName(repoUrl, stack, targetVersion, suffix);
   const repoShort = repoUrl.replace(/.*[:/]/, '').replace(/\.git$/, '');
   const outputDir = resolve(process.cwd(), 'output', repoShort);
@@ -51,10 +51,18 @@ function startContainer({ repoUrl, targetVersion, push, suffix, ghToken, claudeC
 
   if (suffix) env.BRANCH_SUFFIX = suffix;
 
-  if (claudeCreds.type === 'oauth') {
-    env.CLAUDE_CODE_OAUTH_TOKEN = claudeCreds.value;
-  } else {
-    env.ANTHROPIC_API_KEY = claudeCreds.value;
+  if (agentChoice === 'claude') {
+    if (agentCreds.type === 'oauth') {
+      env.CLAUDE_CODE_OAUTH_TOKEN = agentCreds.value;
+    } else {
+      env.ANTHROPIC_API_KEY = agentCreds.value;
+    }
+  } else if (agentChoice === 'codex') {
+    if (agentCreds.type === 'apikey') {
+      env.OPENAI_API_KEY = agentCreds.value;
+    } else {
+      env.CODEX_AUTH_JSON_B64 = agentCreds.value;
+    }
   }
 
   for (const [key, val] of Object.entries(env)) {

cli/src/index.js

@@ -3,7 +3,7 @@
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { getGhToken, getGhUser, discoverRepos, selectRepos } from './github.js';
-import { detectClaudeCredentials } from './credentials.js';
+import { detectClaudeCredentials, detectCodexCredentials } from './credentials.js';
 import { askRunTarget, askTargetVersion, askPush, askSuffix } from './prompts.js';
 import { hasDocker, launchDocker } from './docker.js';
 import { hasKubectl, launchKubernetes } from './kubectl.js';
@@ -20,7 +20,6 @@ async function main() {
   let ghToken = getGhToken();
   if (!ghToken) ghToken = getConfig('ghToken') || null;
   const ghUser = ghToken ? getGhUser() : null;
-  const claudeAutoDetect = await detectClaudeCredentials({ promptIfMissing: false });
 
   if (ghUser) {
     p.log.message(`${pc.green('\u2713')} GitHub CLI authenticated (${ghUser})`);
@@ -30,13 +29,34 @@ async function main() {
 
   preSpinner.stop('Prerequisites checked');
 
-  // Claude credentials — prompt after spinner if not auto-detected
-  let claudeCreds;
-  if (claudeAutoDetect) {
-    p.log.message(`${pc.green('\u2713')} Claude credentials found (${claudeAutoDetect.source})`);
-    claudeCreds = claudeAutoDetect;
+  // --- Agent selection ---
+  const agentChoice = await p.select({
+    message: 'Which AI agent?',
+    options: [
+      { value: 'claude', label: 'Claude Code', hint: 'Anthropic' },
+      { value: 'codex', label: 'Codex CLI', hint: 'OpenAI' },
+    ],
+  });
+  if (p.isCancel(agentChoice)) process.exit(0);
+
+  // Detect credentials for the selected agent
+  let agentCreds;
+  if (agentChoice === 'claude') {
+    const autoDetect = await detectClaudeCredentials({ promptIfMissing: false });
+    if (autoDetect) {
+      p.log.message(`${pc.green('\u2713')} Claude credentials found (${autoDetect.source})`);
+      agentCreds = autoDetect;
+    } else {
+      agentCreds = await detectClaudeCredentials({ promptIfMissing: true });
+    }
   } else {
-    claudeCreds = await detectClaudeCredentials({ promptIfMissing: true });
+    const autoDetect = await detectCodexCredentials({ promptIfMissing: false });
+    if (autoDetect) {
+      p.log.message(`${pc.green('\u2713')} Codex credentials found (${autoDetect.source})`);
+      agentCreds = autoDetect;
+    } else {
+      agentCreds = await detectCodexCredentials({ promptIfMissing: true });
+    }
   }
 
   // Save GH token if we got one from `gh auth`
@@ -104,8 +124,9 @@ async function main() {
       push,
       suffix: suffix || '',
       ghToken,
-      claudeCreds,
-      image: stack.image,
+      agentCreds,
+      agentChoice,
+      image: stack.image(agentChoice),
       stack: repo.stack,
       stackName: stack.name,
       envKey: stack.envKey,

cli/src/kubectl.js

@@ -123,7 +123,7 @@ async function selectNamespace() {
 /**
  * Ensure the upgrade-agent secret exists in the namespace.
  */
-function ensureSecret(namespace, ghToken, claudeCreds) {
+function ensureSecret(namespace, ghToken, agentCreds, agentChoice) {
   try {
     execFileSync('kubectl', ['delete', 'secret', SECRET_NAME, '-n', namespace], { stdio: 'ignore' });
   } catch {
@@ -141,14 +141,22 @@ function ensureSecret(namespace, ghToken, claudeCreds) {
     args.push(`--from-literal=GH_TOKEN=${ghToken}`);
   }
 
-  if (claudeCreds.type === 'oauth') {
-    args.push(`--from-literal=CLAUDE_CODE_OAUTH_TOKEN=${claudeCreds.value}`);
-  } else {
-    args.push(`--from-literal=ANTHROPIC_API_KEY=${claudeCreds.value}`);
+  if (agentChoice === 'claude') {
+    if (agentCreds.type === 'oauth') {
+      args.push(`--from-literal=CLAUDE_CODE_OAUTH_TOKEN=${agentCreds.value}`);
+    } else {
+      args.push(`--from-literal=ANTHROPIC_API_KEY=${agentCreds.value}`);
+    }
+  } else if (agentChoice === 'codex') {
+    if (agentCreds.type === 'apikey') {
+      args.push(`--from-literal=OPENAI_API_KEY=${agentCreds.value}`);
+    } else {
+      args.push(`--from-literal=CODEX_AUTH_JSON_B64=${agentCreds.value}`);
+    }
   }
 
   execFileSync('kubectl', args, { stdio: 'ignore' });
-  p.log.success(`Secret created (Claude: ${claudeCreds.type}, GitHub: ${ghToken ? 'yes' : 'no'})`);
+  p.log.success(`Secret created (${agentChoice}: ${agentCreds.type}, GitHub: ${ghToken ? 'yes' : 'no'})`);
 }
 
 /**
@@ -166,7 +174,7 @@ function startPod({ namespace, repoUrl, targetVersion, push, suffix, ghToken, cl
   if (suffix) envVars.push({ name: 'BRANCH_SUFFIX', value: suffix });
 
   // Secret-backed env vars
-  const secretEnvs = ['GH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY'];
+  const secretEnvs = ['GH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'CODEX_AUTH_JSON_B64'];
   for (const key of secretEnvs) {
     envVars.push({
       name: key,
@@ -211,8 +219,8 @@ export async function launchKubernetes(upgrades) {
   const namespace = await selectNamespace();
 
   // Ensure secret (uses first upgrade's creds — they're shared)
-  const { ghToken, claudeCreds } = upgrades[0];
-  ensureSecret(namespace, ghToken, claudeCreds);
+  const { ghToken, agentCreds, agentChoice } = upgrades[0];
+  ensureSecret(namespace, ghToken, agentCreds, agentChoice);
 
   // Launch all pods
   const launched = [];

cli/src/stacks.js

@@ -1,7 +1,7 @@
 export const STACKS = {
   laravel: {
     name: 'Laravel',
-    image: 'ghcr.io/reyemtech/laravel-upgrade-agent:latest',
+    image: (agent) => `ghcr.io/reyemtech/laravel-upgrade-agent-${agent}:latest`,
     detect: (composer) => composer?.require?.['laravel/framework'],
     versionLabel: 'Target Laravel version',
     branchPrefix: 'upgrade/laravel',

docker-bake.hcl

@@ -0,0 +1,32 @@
+variable "REGISTRY" { default = "ghcr.io/reyemtech" }
+variable "VERSION"  { default = "latest" }
+
+group "default" {
+  targets = ["upgrade-agent"]
+}
+
+target "upgrade-agent" {
+  name = "${item.stack}-upgrade-agent-${item.agent}"
+  matrix = {
+    item = [
+      { stack = "laravel", agent = "claude" },
+      { stack = "laravel", agent = "codex" },
+    ]
+  }
+  context    = "stacks/${item.stack}"
+  dockerfile = "Dockerfile.${item.agent}"
+  contexts = {
+    base = "target:base-${item.stack}"
+  }
+  tags = [
+    "${REGISTRY}/${item.stack}-upgrade-agent-${item.agent}:${VERSION}",
+    "${REGISTRY}/${item.stack}-upgrade-agent-${item.agent}:latest",
+  ]
+  platforms = ["linux/amd64", "linux/arm64"]
+}
+
+target "base-laravel" {
+  context    = "stacks/laravel"
+  dockerfile = "Dockerfile.base"
+  tags       = []  # Not pushed — used as build dependency only
+}