| 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
- Locate the installed package and version.
npm ls @openai/codex-sdknode -p "require.resolve('@openai/codex-sdk/package.json')"
- Open the package.json and record:
versiontypes / typingsexports entries (especially any types fields)
- 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
- 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).
- 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
- Clone the repo if it is not already present.
git clone https://github.com/openai/codex ~/repos/codex
- 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>
- 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.
- 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.
