codex_skill

Overview

This skill executes the Codex CLI to perform code analysis, refactoring, and automated code changes with structured JSON responses and file references using @ syntax. It enforces safe invocation patterns (HEREDOC, foreground Bash) and returns only the final agent message plus a session ID for resumable workflows. The tool supports single-file tasks, multi-file refactors, and parallel task orchestration with dependency handling.

How this skill works

Invoke the Codex CLI via a foreground Bash tool call using HEREDOC (<<'EOF') so code, quotes, and special characters pass unchanged. The wrapper accepts @file references, optional working_dir, and --parallel input blocks, streams progress, and emits a final agent_message followed by SESSION_ID. A fixed timeout (2 hours) is enforced, with environment variable override for ad-hoc runs; failures produce concise ERROR lines. Parallel mode reads tasks from stdin and uses metadata blocks to topologically order and run tasks concurrently.

When to use it

• Deep code analysis that spans many files or requires model reasoning
• Large-scale refactoring where changes must be coordinated across modules
• Automated code generation or patching that needs safe file references (@syntax)
• Multi-stage workflows that benefit from parallel tasks with explicit dependencies
• Resumable sessions where you want to continue a previous Codex conversation using SESSION_ID

Best practices

• Always run automated invocations through the Bash tool in the foreground with HEREDOC: codex-wrapper - [workdir] <<'EOF' ... EOF
• Keep timeout parameter fixed at 7200000 when using the Bash tool; use CODEX_TIMEOUT only for controlled overrides
• Avoid backgrounding runs or BashOutput streaming loops; split long work into smaller foreground tasks
• Use --parallel with the delimiter format and include workdir and id metadata inside each task block
• Log and document fallbacks: if Codex fails twice or is unavailable, record CODEX_FALLBACK and retry Codex on the next task

Example use cases

• Refactor utility functions across a repository: codex-wrapper - <<'EOF' refactor @src/utils ... EOF
• Security audit: codex-wrapper - <<'EOF' analyze @. and find SQL injection and XSS risks EOF
• Chained workflow: codex-wrapper --parallel <<'EOF' with analyze, implement, test tasks and dependencies
• Resume work: use SESSION_ID from previous output to continue conversation with codex-wrapper resume <SESSION_ID> - <<'EOF' ... EOF
• Parallel task scheduling: run independent build, frontend, and test tasks with dependencies in a single --parallel call