oh-my-customcode 0.12.2 → 0.12.3

package/README.md

@@ -21,7 +21,7 @@ Like oh-my-zsh transformed shell customization, oh-my-customcode makes personali
 
 | Feature | Description |
 |---------|-------------|
-| **Batteries Included** | 42 agents, 51 skills, 22 guides, 18 rules, 1 hook, 4 contexts - ready to use out of the box |
+| **Batteries Included** | 42 agents, 52 skills, 22 guides, 18 rules, 1 hook, 4 contexts - ready to use out of the box |
 | **Sub-Agent Model** | Supports hierarchical agent orchestration with specialized roles |
 | **Dead Simple Customization** | Create a folder + markdown file = new agent or skill |
 | **Mix and Match** | Use built-in components, create your own, or combine both |
@@ -171,7 +171,7 @@ tool-npm-expert
 tool-optimizer
 ```
 
-### Skills (51)
+### Skills (52)
 
 Canonical skill IDs (`templates/.claude/skills/*/SKILL.md`):
 
@@ -180,6 +180,7 @@ airflow-best-practices
 audit-agents
 aws-best-practices
 claude-code-bible
+codex-exec
 create-agent
 dbt-best-practices
 de-lead-routing
@@ -301,7 +302,7 @@ your-project/
     │   ├── be-fastapi-expert.md
     │   ├── mgr-creator.md
     │   └── ...
-    ├── skills/            # Skill modules (51 directories, each with SKILL.md)
+    ├── skills/            # Skill modules (52 directories, each with SKILL.md)
     │   ├── go-best-practices/
     │   ├── react-best-practices/
     │   ├── secretary-routing/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-customcode",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/skills/codex-exec/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: codex-exec
+description: Execute OpenAI Codex CLI prompts and return results
+argument-hint: "<prompt> [--json] [--output <path>] [--model <name>] [--timeout <ms>]"
+disable-model-invocation: true
+---
+
+# Codex Exec Skill
+
+Execute OpenAI Codex CLI prompts in non-interactive mode and return structured results. Enables Claude + Codex hybrid workflows.
+
+## Options
+
+```
+<prompt>          Required. The prompt to send to Codex CLI
+--json            Return structured JSON Lines output
+--output <path>   Save final message to file
+--model <name>    Model override (o3, o4-mini, etc.)
+--timeout <ms>    Execution timeout (default: 120000, max: 600000)
+--full-auto       Enable auto-approval mode (codex -a full-auto)
+--working-dir     Working directory for Codex execution
+```
+
+## Workflow
+
+```
+1. Pre-checks
+   - Verify `codex` binary is installed (which codex || npx codex --version)
+   - Verify authentication (OPENAI_API_KEY or logged in)
+2. Build command
+   - Base: codex exec --ephemeral "<prompt>"
+   - Apply options: --json, --model, --full-auto, -C <dir>
+   - Set --working-dir if specified
+3. Execute
+   - Run via Bash tool with timeout (default 2min, max 10min)
+   - Or use helper script: node .claude/skills/codex-exec/scripts/codex-wrapper.cjs
+4. Parse output
+   - Text mode: return raw stdout
+   - JSON mode: parse JSON Lines, extract final assistant message
+5. Report results
+   - Format output with execution metadata
+```
+
+## Safety Defaults
+
+- `--ephemeral`: No session persistence (conversations not saved)
+- Default mode: Normal approval (Codex prompts for confirmation)
+- Override with `--full-auto` only when explicitly requested
+
+## Output Format
+
+### Success (Text Mode)
+```
+[Codex Exec] Completed
+
+Model: o3
+Duration: 23.4s
+Working Dir: /path/to/project
+
+--- Output ---
+{codex response text}
+```
+
+### Success (JSON Mode)
+```
+[Codex Exec] Completed (JSON)
+
+Model: o3
+Duration: 23.4s
+Events: 12
+
+--- Final Message ---
+{extracted final assistant message}
+```
+
+### Failure
+```
+[Codex Exec] Failed
+
+Error: {error_message}
+Exit Code: {code}
+Suggested Fix: {suggestion}
+```
+
+## Helper Script
+
+For complex executions, use the wrapper script:
+```bash
+node .claude/skills/codex-exec/scripts/codex-wrapper.cjs --prompt "your prompt" [options]
+```
+
+The wrapper provides:
+- Environment validation (binary + auth checks)
+- Safe command construction
+- JSON Lines parsing with event extraction
+- Structured JSON output
+- Timeout handling with graceful termination
+
+## Examples
+
+```bash
+# Simple text prompt
+codex-exec "explain what this project does"
+
+# JSON output with model override
+codex-exec "list all TODO items" --json --model o4-mini
+
+# Save output to file
+codex-exec "generate a README" --output ./README.md
+
+# Full auto mode with custom timeout
+codex-exec "fix the failing tests" --full-auto --timeout 300000
+
+# Specify working directory
+codex-exec "analyze the codebase" --working-dir /path/to/project
+```
+
+## Integration
+
+Works with the orchestrator pattern:
+- Main conversation delegates Codex execution via this skill
+- Results are returned to the main conversation for further processing
+- Can be chained with other skills (e.g., dev-review after Codex generates code)

package/templates/.claude/skills/codex-exec/scripts/codex-wrapper.cjs

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+
+/**
+ * codex-wrapper.js
+ *
+ * Node.js wrapper for OpenAI Codex CLI (non-interactive execution).
+ * Executes codex in ephemeral mode with structured JSON output.
+ *
+ * Usage:
+ *   node codex-wrapper.js --prompt "your prompt" [options]
+ *
+ * Options:
+ *   --prompt <text>       Required: prompt to execute
+ *   --json                Enable JSON Lines output from codex
+ *   --output <path>       Save final message to file
+ *   --model <name>        Specify model (default: o3)
+ *   --timeout <ms>        Execution timeout in milliseconds (default: 120000, max: 600000)
+ *   --full-auto           Use full-auto approval mode (default: -a never)
+ *   --working-dir <dir>   Set working directory for execution
+ *
+ * Output (JSON to stdout):
+ *   Success: { "success": true, "output": "...", "duration_ms": 1234, ... }
+ *   Failure: { "success": false, "error": "...", "stderr": "...", ... }
+ *
+ * Exit codes:
+ *   0 = success
+ *   1 = execution error
+ *   2 = validation error (missing binary/auth)
+ */
+
+const { spawn, execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Configuration
+const DEFAULT_TIMEOUT_MS = 120000; // 2 minutes
+const MAX_TIMEOUT_MS = 600000; // 10 minutes
+const KILL_GRACE_PERIOD_MS = 5000; // 5 seconds for graceful shutdown
+
+/**
+ * Parse command line arguments
+ * @returns {Object} Parsed arguments
+ */
+function parseArgs() {
+  const args = {
+    prompt: null,
+    json: false,
+    output: null,
+    model: null,
+    timeout: DEFAULT_TIMEOUT_MS,
+    fullAuto: false,
+    workingDir: null,
+  };
+
+  for (let i = 2; i < process.argv.length; i++) {
+    const arg = process.argv[i];
+
+    switch (arg) {
+      case '--prompt':
+        if (i + 1 < process.argv.length) {
+          args.prompt = process.argv[++i];
+        }
+        break;
+      case '--json':
+        args.json = true;
+        break;
+      case '--output':
+        if (i + 1 < process.argv.length) {
+          args.output = process.argv[++i];
+        }
+        break;
+      case '--model':
+        if (i + 1 < process.argv.length) {
+          args.model = process.argv[++i];
+        }
+        break;
+      case '--timeout':
+        if (i + 1 < process.argv.length) {
+          const timeoutValue = parseInt(process.argv[++i], 10);
+          if (!isNaN(timeoutValue)) {
+            args.timeout = Math.min(timeoutValue, MAX_TIMEOUT_MS);
+          }
+        }
+        break;
+      case '--full-auto':
+        args.fullAuto = true;
+        break;
+      case '--working-dir':
+        if (i + 1 < process.argv.length) {
+          args.workingDir = process.argv[++i];
+        }
+        break;
+    }
+  }
+
+  return args;
+}
+
+/**
+ * Validate environment for codex execution
+ * @returns {Object} Validation result { valid: boolean, errors: string[] }
+ */
+function validateEnvironment() {
+  const errors = [];
+
+  // Check for codex binary
+  try {
+    execFileSync('which', ['codex'], { stdio: 'pipe' });
+  } catch (error) {
+    // Try common installation paths
+    const commonPaths = [
+      '/usr/local/bin/codex',
+      path.join(os.homedir(), '.local', 'bin', 'codex'),
+      path.join(os.homedir(), 'bin', 'codex'),
+    ];
+
+    const codexExists = commonPaths.some(p => fs.existsSync(p));
+    if (!codexExists) {
+      errors.push('codex binary not found in PATH or common locations');
+    }
+  }
+
+  // Note: OPENAI_API_KEY is optional if codex has its own stored auth (via `codex auth`)
+  if (!process.env.OPENAI_API_KEY) {
+    console.error('[codex-wrapper] Note: OPENAI_API_KEY not set, relying on codex built-in auth');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Build codex command array
+ * @param {Object} options - Command options
+ * @returns {Object} Command structure { binary: string, args: string[] }
+ */
+function buildCommand(options) {
+  const args = ['exec', '--ephemeral'];
+
+  // Approval mode (default: normal, --full-auto: automatic execution)
+  if (options.fullAuto) {
+    args.push('--full-auto');
+  }
+
+  // JSON output
+  if (options.json) {
+    args.push('--json');
+  }
+
+  // Model selection
+  if (options.model) {
+    args.push('--model', options.model);
+  }
+
+  // Working directory
+  if (options.workingDir) {
+    args.push('-C', options.workingDir);
+  }
+
+  // Add prompt as last argument
+  args.push(options.prompt);
+
+  return {
+    binary: 'codex',
+    args,
+  };
+}
+
+/**
+ * Execute codex command
+ * @param {string} binary - Binary to execute
+ * @param {string[]} args - Command arguments
+ * @param {number} timeout - Timeout in milliseconds
+ * @param {string|null} workingDir - Working directory
+ * @returns {Promise<Object>} Execution result
+ */
+function executeCodex(binary, args, timeout, workingDir = null) {
+  return new Promise((resolve) => {
+    const startTime = Date.now();
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+
+    const spawnOptions = {
+      cwd: workingDir || process.cwd(),
+      env: process.env,
+    };
+
+    const child = spawn(binary, args, spawnOptions);
+
+    // Collect output
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    // Set timeout
+    const timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      console.error('[codex-wrapper] Timeout reached, terminating process...', { file: 'stderr' });
+
+      // Graceful termination attempt
+      child.kill('SIGTERM');
+
+      // Force kill after grace period
+      setTimeout(() => {
+        if (!child.killed) {
+          console.error('[codex-wrapper] Force killing process...', { file: 'stderr' });
+          child.kill('SIGKILL');
+        }
+      }, KILL_GRACE_PERIOD_MS);
+    }, timeout);
+
+    // Handle process exit
+    child.on('close', (exitCode) => {
+      clearTimeout(timeoutHandle);
+      const durationMs = Date.now() - startTime;
+
+      resolve({
+        exitCode: exitCode !== null ? exitCode : 1,
+        stdout,
+        stderr,
+        timedOut,
+        durationMs,
+      });
+    });
+
+    // Handle spawn errors
+    child.on('error', (error) => {
+      clearTimeout(timeoutHandle);
+      const durationMs = Date.now() - startTime;
+
+      resolve({
+        exitCode: 1,
+        stdout,
+        stderr: stderr + '\nSpawn error: ' + error.message,
+        timedOut: false,
+        durationMs,
+      });
+    });
+  });
+}
+
+/**
+ * Parse JSON Lines output from codex
+ * @param {string} output - Raw output string
+ * @returns {Object} Parsed result { events: object[], finalMessage: string|null, parseErrors: string[] }
+ */
+function parseJsonLines(output) {
+  const lines = output.split('\n').filter(line => line.trim().length > 0);
+  const events = [];
+  const parseErrors = [];
+  let finalMessage = null;
+
+  for (const line of lines) {
+    try {
+      const event = JSON.parse(line);
+      events.push(event);
+
+      // Codex CLI v0.99.0 format: item.completed events with agent_message type
+      if (event.type === 'item.completed' && event.item) {
+        if (event.item.type === 'agent_message' && event.item.text) {
+          finalMessage = event.item.text;
+        }
+      }
+      // Look for assistant message in various event structures (fallback for future API changes)
+      else if (event.type === 'assistant_message' && event.content) {
+        finalMessage = event.content;
+      } else if (event.message && event.message.role === 'assistant') {
+        finalMessage = event.message.content || event.message.text;
+      } else if (event.role === 'assistant' && event.content) {
+        finalMessage = event.content;
+      }
+    } catch (error) {
+      parseErrors.push(`Failed to parse line: ${error.message}`);
+    }
+  }
+
+  return {
+    events,
+    finalMessage,
+    parseErrors,
+  };
+}
+
+/**
+ * Main execution function
+ */
+async function main() {
+  const args = parseArgs();
+
+  // Validate required arguments
+  if (!args.prompt) {
+    const result = {
+      success: false,
+      error: 'Missing required argument: --prompt',
+      exit_code: 2,
+    };
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(2);
+  }
+
+  // Validate environment
+  const validation = validateEnvironment();
+  if (!validation.valid) {
+    const result = {
+      success: false,
+      error: 'Environment validation failed',
+      validation_errors: validation.errors,
+      exit_code: 2,
+    };
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(2);
+  }
+
+  console.error(`[codex-wrapper] Executing codex with timeout: ${args.timeout}ms`);
+  if (args.workingDir) {
+    console.error(`[codex-wrapper] Working directory: ${args.workingDir}`);
+  }
+
+  // Build command
+  const command = buildCommand(args);
+  console.error(`[codex-wrapper] Command: ${command.binary} ${command.args.join(' ')}`);
+
+  // Execute
+  const execResult = await executeCodex(
+    command.binary,
+    command.args,
+    args.timeout,
+    args.workingDir
+  );
+
+  // Process result
+  let output = null;
+  let eventsCount = 0;
+
+  if (args.json && execResult.stdout) {
+    const parsed = parseJsonLines(execResult.stdout);
+    eventsCount = parsed.events.length;
+    output = parsed.finalMessage;
+
+    if (parsed.parseErrors.length > 0) {
+      console.error('[codex-wrapper] JSON parse errors:', parsed.parseErrors.join('; '));
+    }
+  } else {
+    output = execResult.stdout.trim();
+  }
+
+  // Determine success
+  const success = execResult.exitCode === 0 && !execResult.timedOut;
+
+  // Build result object
+  const result = {
+    success,
+    duration_ms: execResult.durationMs,
+    exit_code: execResult.exitCode,
+  };
+
+  if (success) {
+    result.output = output || execResult.stdout;
+    result.model = args.model || 'o3';
+    if (args.json) {
+      result.events_count = eventsCount;
+    }
+  } else {
+    if (execResult.timedOut) {
+      result.error = `Execution timed out after ${args.timeout}ms`;
+    } else {
+      result.error = 'Execution failed';
+    }
+    if (execResult.stderr) {
+      result.stderr = execResult.stderr.trim();
+    }
+  }
+
+  // Write output file if requested
+  if (args.output && output) {
+    try {
+      const outputDir = path.dirname(args.output);
+      if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+      }
+      fs.writeFileSync(args.output, output, 'utf-8');
+      console.error(`[codex-wrapper] Output written to: ${args.output}`);
+    } catch (error) {
+      console.error(`[codex-wrapper] Failed to write output file: ${error.message}`);
+      result.output_file_error = error.message;
+    }
+  }
+
+  // Output JSON result to stdout
+  console.log(JSON.stringify(result, null, 2));
+
+  process.exit(result.exit_code);
+}
+
+// Run
+main().catch(error => {
+  const result = {
+    success: false,
+    error: 'Unexpected error: ' + error.message,
+    stack: error.stack,
+    exit_code: 1,
+  };
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(1);
+});

package/templates/CLAUDE.md.en

@@ -155,6 +155,7 @@ Flow:
 | `/npm-publish` | Publish package to npm registry |
 | `/npm-version` | Manage semantic versions |
 | `/npm-audit` | Audit dependencies |
+| `/codex-exec` | Execute Codex CLI prompts |
 | `/optimize-analyze` | Analyze bundle and performance |
 | `/optimize-bundle` | Optimize bundle size |
 | `/optimize-report` | Generate optimization report |

package/templates/CLAUDE.md.ko

@@ -155,6 +155,7 @@ oh-my-customcode로 구동됩니다.
 | `/npm-publish` | npm 레지스트리에 패키지 배포 |
 | `/npm-version` | 시맨틱 버전 관리 |
 | `/npm-audit` | 의존성 감사 |
+| `/codex-exec` | Codex CLI 프롬프트 실행 |
 | `/optimize-analyze` | 번들 및 성능 분석 |
 | `/optimize-bundle` | 번들 크기 최적화 |
 | `/optimize-report` | 최적화 리포트 생성 |