# `Codex`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.18.0/lib/codex.ex#L1)

Public entry point for the Codex SDK.

Provides helpers to start new threads or resume existing ones.

## Realtime Voice

For real-time voice interactions using WebSockets:

    # Define an agent
    agent = Codex.Realtime.agent(
      name: "VoiceAssistant",
      instructions: "You are a helpful voice assistant."
    )

    # Create and run a session
    {:ok, session} = Codex.Realtime.run(agent)

    # Send audio and subscribe to events
    Codex.Realtime.send_audio(session, audio_bytes)
    Codex.Realtime.subscribe(session, self())

    receive do
      {:session_event, event} -> handle_event(event)
    end

See `Codex.Realtime` for full documentation.

## Voice Pipeline

For non-realtime voice processing (STT -> Workflow -> TTS):

    workflow = Codex.Voice.simple_workflow(fn text ->
      ["You said: #{text}"]
    end)

    {:ok, result} = Codex.Voice.run(audio, workflow: workflow)

See `Codex.Voice` for full documentation.

# `start_opts`

```elixir
@type start_opts() :: map() | keyword() | Codex.Options.t()
```

# `thread_opts`

```elixir
@type thread_opts() :: map() | keyword() | Codex.Thread.Options.t()
```

# `list_sessions`

```elixir
@spec list_sessions(keyword()) ::
  {:ok, [Codex.Sessions.session_entry()]} | {:error, term()}
```

Lists session files persisted by the Codex CLI.

Returns entries parsed from `$CODEX_HOME/sessions` by default.

# `realtime_agent`

```elixir
@spec realtime_agent(keyword()) :: Codex.Realtime.Agent.t()
```

Create a realtime agent.

Delegates to `Codex.Realtime.agent/1`.

## Example

    agent = Codex.realtime_agent(
      name: "VoiceBot",
      instructions: "You are a helpful voice bot.",
      tools: [my_tool]
    )

# `realtime_run`

```elixir
@spec realtime_run(
  Codex.Realtime.Agent.t(),
  keyword()
) :: {:ok, pid()} | {:error, term()}
```

Create and start a realtime session with an agent.

Delegates to `Codex.Realtime.run/2`.

## Example

    agent = Codex.realtime_agent(name: "Assistant", instructions: "Be helpful.")
    {:ok, session} = Codex.realtime_run(agent)

# `resume_thread`

```elixir
@spec resume_thread(String.t() | :last, start_opts(), thread_opts()) ::
  {:ok, Codex.Thread.t()} | {:error, term()}
```

Resumes an existing thread with the given `thread_id`.

Pass `:last` to resume the most recent recorded session (equivalent to
`codex exec resume --last`).

# `start_thread`

```elixir
@spec start_thread(start_opts(), thread_opts()) ::
  {:ok, Codex.Thread.t()} | {:error, term()}
```

Starts a new Codex thread returning a `%Codex.Thread{}` struct.

# `voice_audio_input`

```elixir
@spec voice_audio_input(
  binary(),
  keyword()
) :: Codex.Voice.Input.AudioInput.t()
```

Create an audio input from binary data.

Delegates to `Codex.Voice.audio_input/2`.

## Example

    audio = Codex.voice_audio_input(File.read!("recording.pcm"))

# `voice_run`

```elixir
@spec voice_run(
  Codex.Voice.Input.AudioInput.t() | Codex.Voice.Input.StreamedAudioInput.t(),
  keyword()
) :: {:ok, Codex.Voice.Result.t()}
```

Create and run a voice pipeline.

Delegates to `Codex.Voice.run/2`.

## Example

    workflow = Codex.Voice.simple_workflow(fn text -> ["Echo: #{text}"] end)
    {:ok, result} = Codex.voice_run(audio, workflow: workflow)

---

*Consult [api-reference.md](api-reference.md) for complete listing*