---
name: codex-sdk-research
description: Investigate the @openai/codex-sdk API by first inspecting installed .d.ts typings in node_modules, then cloning and searching the github.com/openai/codex repo for source/docs. Use for questions about Codex SDK API surface, types, response formats, threads/runs, or debugging codex-sdk behavior.
---

# Codex SDK Research

## Workflow

Follow the stages in order. Treat stage 1 as the source of truth for the *installed* API, and stage 2 for implementation details and docs.

### Stage 1: Inspect installed .d.ts in node_modules

1. Locate the installed package and version.
   - `npm ls @openai/codex-sdk`
   - `node -p "require.resolve('@openai/codex-sdk/package.json')"`
2. Open the package.json and record:
   - `version`
   - `types` / `typings`
   - `exports` entries (especially any `types` fields)
3. Find all .d.ts files under the package root and skim the entrypoint first.
   - `rg --files -g '*.d.ts' <pkg-root>`
   - Open the main .d.ts referenced by `types` or `exports`
4. Map the public API surface:
   - Identify exported classes/functions/types and their signatures.
   - Note any JSDoc comments or deprecation markers.
   - Track key types related to the question (e.g., threads, runs, response formats, schemas).
5. If something is missing or unclear, search within .d.ts files:
   - `rg -n "export|interface|type|class|enum" <pkg-root>`
   - `rg -n "Thread|Run|outputSchema|response_format|schema" <pkg-root>`

### Stage 1.5: Locate Codex session rollouts (debugging)

When debugging Codex CLI behavior, locate the session JSONL rollouts stored under the Codex home directory (`~/.codex` by default or `$CODEX_HOME` if set):
- Latest rollout file (by mtime):
  - `ls -t "${CODEX_HOME:-$HOME/.codex}"/sessions/*/*/*/rollout-*.jsonl | head -n 1`
- Grep for a conversation id (if known):
  - `rg -n "<conversation-id>" "${CODEX_HOME:-$HOME/.codex}"/sessions/*/*/*/rollout-*.jsonl`

### Stage 2: Clone repo and inspect source/docs

1. Clone the repo if it is not already present.
   - `git clone https://github.com/openai/codex ~/repos/codex`
2. If you know the installed SDK version, try to align tags/commits:
   - `git -C ~/repos/codex tag --list | rg <version>`
   - `git -C ~/repos/codex checkout <tag-or-commit>`
3. Search for implementation and docs related to the question:
   - `rg -n "codex-sdk|sdk|Thread|Run|outputSchema|response_format" ~/repos/codex`
   - Check `README`, `docs/`, and any JS/TS packages or SDK folders.
4. Use source to confirm behavior, defaults, and error handling that are not explicit in .d.ts.

## Output

- State the installed SDK version and where the typings were found.
- Summarize the relevant public API from .d.ts (signatures, types, expected inputs/outputs).
- Add implementation/doc details from the repo (if needed) and call out any version mismatch.
- If unsure, say what is missing and which file you would inspect next.