Packages

codex_sdk

0.4.1
0.17.0 0.16.1 0.16.0 0.14.0 0.13.0 0.12.0 0.11.0 0.10.1 0.10.0 0.9.0 0.8.0 0.7.2 0.7.1 0.7.0 0.6.0 0.5.0 0.4.5 0.4.4 0.4.3 0.4.2 0.4.1 0.4.0 0.3.0 0.2.5 0.2.4 0.2.3 0.2.2 0.2.1 0.2.0 0.1.0

Idiomatic Elixir SDK for OpenAI's Codex agent. Provides a complete, production-ready interface with streaming support, comprehensive event handling, and robust testing utilities.

HexDocs

Current section

Files

Jump to
Readme
30 Versions
6 Dependencies
Dependants
Files
Activity
codex_sdk docs 20251202 gap_analysis 001-thread-option-cli-parity.md
Raw

docs/20251202/gap_analysis/001-thread-option-cli-parity.md 

# ADR 001: Thread option parity with codex CLI



- Status: Proposed

- Date: 2025-12-02



## Context

- The TypeScript SDK forwards per-thread execution controls to the `codex exec` CLI, including sandbox mode, working directory, additional directories, Git repo checks, network/web-search toggles, approval policy, and per-thread model/reasoning overrides (codex/sdk/typescript/src/exec.ts:16-97, codex/sdk/typescript/src/threadOptions.ts:7-17).

- The Elixir thread options struct only carries metadata, labels, auto-run, and approval hook hints (lib/codex/thread/options.ex:6-66).

- The Elixir exec argument builder never emits the corresponding CLI flags/config entries beyond model + schema/attachments (lib/codex/exec.ex:187-255).



## Problem

- Callers of the Elixir SDK cannot opt into CLI capabilities that Python/TypeScript expose (sandbox selection, working directory overrides, network/web search enablement, Git check suppression, additional directories, approval policy, per-thread model + reasoning effort). This diverges from upstream behavior and prevents parity validation against Python fixtures.



## Decision

- Add the missing fields to `Codex.Thread.Options` with validation mirroring the CLI enum values.

- Extend `Codex.Exec.build_args/1` to emit `--sandbox`, `--cd`, `--add-dir`, `--skip-git-repo-check`, `--config sandbox_workspace_write.network_access`, `--config features.web_search_request`, `--config approval_policy`, and per-thread `--model`/`--config model_reasoning_effort` overrides.

- Thread/build helpers should merge per-thread defaults with global `Codex.Options` to preserve existing behavior while allowing overrides.



## Actions

- Update unit/integration tests to cover the new flags and ensure contract coverage against harvested Python fixtures once regenerated.

- Document the new thread option fields in the public API reference and examples.