git:20260429.22f899b to git:20260429.74655e1

---

name: ask-codex

description: Use when a Claude Code agent needs to delegate a question, subtask, or review to a local Codex instance.

---

# 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:

```bash

codex --version

```

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

```bash

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

```bash

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:

```text

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

<paste function here>

```

### 3. Run Codex and capture output

```bash

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:

```bash

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

```

On Windows (PowerShell):

```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.

Artifact path convention:

```text

.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.

```bash

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.