feat(api): add CodexClient wrapper with defaults; tests and README usage

Author: gersmann

README.md

@@ -30,6 +30,15 @@ Options:
 - Full auto: `run_exec("scaffold a cli", full_auto=True)`
 - Run in another dir: `run_exec("...", cd="/path/to/project")`
 
+Using a client with defaults:
+
+```
+from codex import CodexClient
+
+client = CodexClient(model="gpt-4.1", full_auto=True)
+print(client.run("explain this repo"))
+```
+
 ### Install uv
 
 - macOS (Homebrew): `brew install uv`

codex/__init__.py

@@ -7,13 +7,21 @@
     output = run_exec("explain this codebase to me")
 """
 
-from .api import CodexError, CodexNotFoundError, CodexProcessError, find_binary, run_exec
+from .api import (
+    CodexClient,
+    CodexError,
+    CodexNotFoundError,
+    CodexProcessError,
+    find_binary,
+    run_exec,
+)
 
 __all__ = [
     "__version__",
     "CodexError",
     "CodexNotFoundError",
     "CodexProcessError",
+    "CodexClient",
     "find_binary",
     "run_exec",
 ]

codex/api.py

@@ -99,3 +99,67 @@ def run_exec(
         )
     return stdout
 
+
+@dataclass(slots=True)
+class CodexClient:
+    """Lightweight, synchronous client for the Codex CLI.
+
+    Provides defaults for repeated invocations and convenience helpers.
+    """
+
+    executable: str = "codex"
+    model: Optional[str] = None
+    full_auto: bool = False
+    cd: Optional[str] = None
+    env: Optional[Mapping[str, str]] = None
+    extra_args: Optional[Sequence[str]] = None
+
+    def ensure_available(self) -> str:
+        """Return the resolved binary path or raise CodexNotFoundError."""
+        return find_binary(self.executable)
+
+    def run(
+        self,
+        prompt: str,
+        *,
+        model: Optional[str] = None,
+        full_auto: Optional[bool] = None,
+        cd: Optional[str] = None,
+        timeout: Optional[float] = None,
+        env: Optional[Mapping[str, str]] = None,
+        extra_args: Optional[Iterable[str]] = None,
+    ) -> str:
+        """Execute `codex exec` and return stdout.
+
+        Explicit arguments override the client's defaults.
+        """
+        eff_model = model if model is not None else self.model
+        eff_full_auto = full_auto if full_auto is not None else self.full_auto
+        eff_cd = cd if cd is not None else self.cd
+
+        # Merge environment overlays; run_exec will merge with os.environ
+        merged_env: Optional[Mapping[str, str]]
+        if self.env and env:
+            tmp = dict(self.env)
+            tmp.update(env)
+            merged_env = tmp
+        else:
+            merged_env = env or self.env
+
+        # Compose extra args
+        eff_extra: list[str] = []
+        if self.extra_args:
+            eff_extra.extend(self.extra_args)
+        if extra_args:
+            eff_extra.extend(list(extra_args))
+
+        return run_exec(
+            prompt,
+            model=eff_model,
+            full_auto=eff_full_auto,
+            cd=eff_cd,
+            timeout=timeout,
+            env=merged_env,
+            executable=self.executable,
+            extra_args=eff_extra,
+        )

tests/test_client.py

@@ -0,0 +1,38 @@
+import os
+import stat
+from pathlib import Path
+
+import pytest
+
+from codex import CodexClient, CodexNotFoundError
+
+
+def test_client_missing_binary():
+    client = CodexClient(executable="codex-does-not-exist-xyz")
+    with pytest.raises(CodexNotFoundError):
+        client.ensure_available()
+    with pytest.raises(CodexNotFoundError):
+        client.run("hello")
+
+
+def test_client_runs_with_defaults(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    # Dummy codex that echoes args and succeeds
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    codex_path = bin_dir / "codex"
+    codex_path.write_text("""#!/bin/sh\necho \"[dummy] $@\"\n""")
+    codex_path.chmod(codex_path.stat().st_mode | stat.S_IXUSR)
+
+    monkeypatch.setenv("PATH", f"{bin_dir}{os.pathsep}" + os.environ.get("PATH", ""))
+
+    client = CodexClient(model="test-model", full_auto=True, extra_args=["--ask-for-approval"])
+    out = client.run("hello world")
+
+    # Ensure key flags and prompt are passed along; order-insensitive
+    assert "[dummy]" in out
+    assert "exec" in out
+    assert "hello world" in out
+    assert "--full-auto" in out
+    assert "-m test-model" in out
+    assert "--ask-for-approval" in out
+