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.