Ask Codex

Purpose

Use the local Codex CLI as an external worker or advisor from inside a Claude Code session. Hand off a focused task, collect the output, and save a reviewable Markdown artifact before acting on the result.

When to Use

• Need a Codex second opinion on a design decision or code change.
• Want to delegate a self-contained subtask to Codex and inspect the result.
• Exploring a problem from a different model's perspective.
• Do not use when codex CLI is missing or unauthenticated.
• Do not use for tasks that require interactive back-and-forth — Codex output is captured once.

Requirements

• codex CLI available in PATH and authenticated.
• Verify with:

codex --version

If codex is missing, stop and ask the user to install it. Installation reference:

npm install -g @openai/codex

Inputs

• A specific, scoped prompt or task description.
• Optional: file paths or code snippets to include inline in the prompt.
• Optional: artifact output directory (defaults to .apx/artifacts/).

Workflow

1. Check the CLI is available

codex --version

If this fails, stop. Do not proceed without codex in PATH.

2. Compose a focused prompt

Keep it narrow. Codex works best with:

• A single question or task.
• Concrete context (file names, function names, error messages).
• A defined output shape ("respond with a patch", "list edge cases", "answer yes/no and explain").

Example prompt:

Review this TypeScript function for correctness. Return a bullet list of issues found.

<paste function here>

3. Run Codex and capture output

codex "Review this TypeScript function for correctness. Return a bullet list of issues found.\n\n$(cat src/cli/commands/validate.ts)"

Redirect output to an artifact file:

codex "Your prompt here" > .apx/artifacts/codex-review-$(date -u +%Y%m%dT%H%M%SZ).md

On Windows (PowerShell):

codex "Your prompt here" | Out-File .apx/artifacts/codex-review-$(Get-Date -Format 'yyyyMMddTHHmmssZ').md

4. Read and evaluate the artifact

Open the artifact before acting on any recommendation. Codex output is a suggestion, not a directive. Apply judgment before implementing.

5. Report

In the response to the user, include:

• The prompt sent to Codex.
• The artifact path.
• A summary of relevant findings.
• Any recommendation you are or are not acting on, with rationale.

Output

Artifact path convention:

.apx/artifacts/codex-<slug>-<timestamp>.md

Artifact should contain:

• The original task or question.
• The exact prompt sent to Codex.
• Raw Codex output.
• Your concise summary.
• Action items or explicit "no action" decision.

Failure Modes

• Missing CLI: stop, ask user to install codex, do not improvise.
• Empty output: report it; do not fabricate a result.
• Off-topic output: note it in the artifact, do not use it.
• Auth failure: report the stderr; check codex --version and reauthenticate.
• Prompt too broad: narrow the scope before retrying.

apx Integration

apx check ask-codex verifies whether codex is present in PATH.

Prefer the flat APX command after reading this skill:

apx ask-codex "Review this function for edge cases"
apx ask-codex "Return OK only" --json

Nested APX form remains supported:

apx ask codex "Review this function for edge cases"

APX passes the prompt as a positional argument (codex "prompt", not codex -p "prompt"). This matches the Codex CLI's invocation convention. Verify the output mode with codex --help if the captured stdout is empty — some Codex versions open a TUI by default and may require a flag such as --full-auto or -q for non-interactive output. If that applies, invoke codex directly per the workflow above and redirect output manually.

Verification

apx check ask-codex
apx ask-codex "Return OK only" --json

Confirm JSON includes provider, artifactPath, promptLength, and raw output in stdout. Open the artifact before applying advice.