Codex E2e TestSAFE

Intercept and inspect Coding Agent API traffic from Claude Code, Codex CLI, Gemini CLI, Cursor CLI, OpenCode, Kimi/Kimi Code, Pi, and Hermes in a local trace viewer.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: codex-e2e-test
description: Run PR-grade real Codex E2E validation through claude-tap, including resume turns, multiple tool calls, optional image input, viewer verification, and screenshot evidence.
tags: testing, e2e, codex, responses-api
---

# Codex E2E Test Skill

Run real end-to-end validation that starts `claude-tap` from local source,
connects to the real Codex CLI via OAuth, captures OpenAI Responses API traces,
and produces viewer screenshots suitable for PR evidence.

Use this skill for every PR that changes capture, proxying, viewer rendering,
session/dashboard behavior, client launch logic, trace ordering, content blocks,
tools, token usage, or screenshot/demo assets. If a PR cannot run this flow,
state why in the PR and cover the same risk with another real client trace.

## Prerequisites

- `codex` CLI installed (`npm install -g @openai/codex`) and authenticated via OAuth
- Python dev dependencies: `uv sync --extra dev`
- Playwright installed: `uv run playwright install chromium`

Verify OAuth works:

```bash
codex exec "say hello" --dangerously-bypass-approvals-and-sandbox
```

If it fails with token errors, re-authenticate:

```bash
codex auth login
```

## Key Difference from Claude E2E

Codex uses the **OpenAI Responses API** (`/v1/responses`) instead of Anthropic Messages API.
With OAuth authentication, the upstream is `https://chatgpt.com/backend-api/codex`,
**not** `https://api.openai.com`.

The proxy must be told the correct target with `--tap-target`.

## Run a Real Codex E2E Trace

Prefer the resume + multimodal flow below for PR evidence. The simple commands
are only smoke tests for checking local setup.

### Simple (single tool call)

```bash
claude-tap --tap-client codex \
  --tap-target https://chatgpt.com/backend-api/codex \
  --tap-output-dir /tmp/codex-e2e \
  --tap-no-open \
  -- exec "say hello" \
  --dangerously-bypass-approvals-and-sandbox
```

### Multi-call (triggers multiple API requests)

Use a task that requires shell tool use — this forces the agent to make multiple
Responses API calls (models lookup + actual responses):

```bash
claude-tap --tap-client codex \
  --tap-target https://chatgpt.com/backend-api/codex \
  --tap-output-dir /tmp/codex-e2e \
  --tap-no-open \
  -- exec "Read pyproject.toml and tell me the project name and version" \
  --dangerously-bypass-approvals-and-sandbox
```

Expected: 4+ API calls (2x `GET /v1/models` + 2x `POST /v1/responses`).

## Resume + Multimodal Content-Block Trace

Use this flow for viewer changes that affect message rendering, content block
boundaries, tool call ordering, images, or copy/select behavior. It creates a
real Codex session, resumes it at least once, forces multiple shell tool calls
per user turn, and attaches an actual image so the trace includes multimodal
content. This is the default PR evidence flow.

### 1. Prepare an isolated workspace

```bash
mkdir -p /tmp/claude-tap-real-codex-workspace
printf 'project = "claude-tap-real-codex-e2e"\n' \
  > /tmp/claude-tap-real-codex-workspace/project.toml
```

Create or copy a small valid PNG into the workspace. If you need a deterministic
local image, generate it with Python's standard library:

```bash
python3 - <<'PY'
from pathlib import Path
import struct
import zlib

def chunk(kind: bytes, data: bytes) -> bytes:
    return struct.pack(">I", len(data)) + kind + data + struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF)

width = height = 8
rows = b"".join(b"\x00" + (b"\x2f\x80\xed\xff" * width) for _ in range(height))
png = (
    b"\x89PNG\r\n\x1a\n"
    + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0))
    + chunk(b"IDAT", zlib.compress(rows))
    + chunk(b"IEND", b"")
)
Path("/tmp/claude-tap-real-codex-workspace/input.png").write_bytes(png)
PY
```

### 2. Start a real Codex session through claude-tap

Run from the repository, but point Codex at the isolated workspace with `-C`.
The prompt should explicitly require several tool calls so the viewer has
enough messages, tool calls, and response blocks to inspect.

```bash
uv run claude-tap --tap-client codex \
  --tap-target https://chatgpt.com/backend-api/codex \
  --tap-output-dir /tmp/claude-tap-real-codex-traces \
  --tap-no-open \
  -- exec -C /tmp/claude-tap-real-codex-workspace \
  --image /tmp/claude-tap-real-codex-workspace/input.png \
  --dangerously-bypass-approvals-and-sandbox \
  "Inspect this workspace and the attached image. Use shell tools to run pwd, list files, inspect project.toml, inspect input.png, then write codex_e2e_report.txt with your findings. Keep all writes inside this workspace."
```

### 3. Resume the same Codex session with another real turn

Use the session id printed by the first Codex run when possible. Avoid relying
on `--last` on busy maintainer machines because it can resume an unrelated
recent Codex session.

```bash
uv run claude-tap --tap-client codex \
  --tap-target https://chatgpt.com/backend-api/codex \
  --tap-output-dir /tmp/claude-tap-real-codex-traces \
  --tap-no-open \
  -- exec resume <SESSION_ID_FROM_FIRST_RUN> \
  --image /tmp/claude-tap-real-codex-workspace/input.png \
  --dangerously-bypass-approvals-and-sandbox \
  "Continue the same investigation in /tmp/claude-tap-real-codex-workspace. Use shell tools to read /tmp/claude-tap-real-codex-workspace/codex_e2e_report.txt, compute the byte size of /tmp/claude-tap-real-codex-workspace/input.png, and write /tmp/claude-tap-real-codex-workspace/codex_e2e_followup.txt. Then summarize what changed since the previous turn."
```

### 4. Capture multi-position viewer screenshots

Take screenshots at multiple scroll positions, including a deeper position in
the same detail pane. Store them under `.agents/evidence/pr/<topic>/` and use
`raw.githubusercontent.com` links in the PR body.

```bash
mkdir -p .agents/evidence/pr/codex-real-e2e

uv run python - <<'PY'
from pathlib import Path
from playwright.sync_api import sync_playwright

html_files = sorted(Path("/tmp/claude-ta

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

.claude/skills

Gates applied: no_behavioural_pass.