# oban_codex v0.1.0 - Table of Contents

> Run Codex jobs on an Oban queue, with validated args, result helpers, telemetry, and an optional long-lived agent lifecycle.

## Pages

- [oban_codex](readme.md)
- [Changelog](changelog.md)

- Guides
  - [Getting started](getting_started.md)
  - [Agent worker patterns](agent_worker_patterns.md)
  - [Agent lifecycle](agent_lifecycle.md)

## Modules

- [ObanCodex](ObanCodex.md): Run Codex CLI work on an Oban queue.
- [ObanCodex.Args](ObanCodex.Args.md): Build a Codex job's string-keyed, JSON-safe Oban args.
- [ObanCodex.Error](ObanCodex.Error.md): A normalized execution error from the Codex wrapper.
- [ObanCodex.Outcome](ObanCodex.Outcome.md): Default mapping from Codex execution outcomes to Oban verdicts.
- [ObanCodex.Query](ObanCodex.Query.md): Translate validated ObanCodex options into fresh or resumed Codex commands.
- [ObanCodex.Testing](ObanCodex.Testing.md): Build deterministic Codex outcomes for worker tests without invoking the CLI.
- [ObanCodex.Worker](ObanCodex.Worker.md): Define an Oban worker that runs a Codex job.

- Agent lifecycle
  - [ObanCodex.Agent](ObanCodex.Agent.md): A facade over long-lived agent processes whose turns run as Oban jobs.
  - [ObanCodex.Agent.Instance](ObanCodex.Agent.Instance.md): One agent as one `:gen_statem` process, its asynchronous turns run as Oban
jobs. Part of the experimental agent layer (see `ObanCodex.Agent`).
  - [ObanCodex.Agent.Job](ObanCodex.Agent.Job.md): The default Oban worker for agent turns: runs Codex, then routes the
outcome back to the owning `ObanCodex.Agent.Instance`.
  - [ObanCodex.Agent.Supervisor](ObanCodex.Agent.Supervisor.md): The supervision root for the agent lifecycle spike: a `Registry` (tracking
`agent_id -> current state`) plus a `DynamicSupervisor` that owns the
`ObanCodex.Agent.Instance` processes.
  - [ObanCodex.Agent.Tick](ObanCodex.Agent.Tick.md): The adapter between `Oban.Plugins.Cron` (which schedules at the worker
layer) and the agent state machine (which owns turn enqueueing): a scheduled
tick delivers a *prompt* to an agent through the facade, never a Codex job
behind the machine's back.

## Mix Tasks

- [mix oban_codex](Mix.Tasks.ObanCodex.md): Run Codex from the CLI: `mix oban_codex <run|doctor|args>`.
- [mix oban_codex.install](Mix.Tasks.ObanCodex.Install.md): Scaffold a runnable SQLite-backed oban_codex setup.

