Run a Claude Code job (via claude_wrapper) on an Oban queue.

oban_claude is the thin seam between Oban and claude:

• run/2 is the engine: a string-keyed args map in, a {oban_return, result} tuple out. It calls ClaudeWrapper.query/2 and maps the typed %ClaudeWrapper.Result{} / %ClaudeWrapper.Error{} onto Oban's return values via a classifier (see ObanClaude.Outcome).
• ObanClaude.Worker is the drop-in worker (use ObanClaude.Worker) with a single ObanClaude.Worker.handle_result/2 override point.

It owns no state and runs no daemon, and takes no position on what consumes a result. Whether the agent effects its own writes (full-auto) or returns structured data for a downstream effector is encoded in the job's args (prompt + permission mode), never here, so oban_claude supports both.

Example

Build the job's args with ObanClaude.Args.new/1 (atom keys, validated) rather than a hand-written string map:

defmodule MyApp.ClaudeJob do
  use ObanClaude.Worker, queue: :claude, max_attempts: 3
end

ObanClaude.Args.new(prompt: "summarize the repo", working_dir: "/path/to/repo")
|> MyApp.ClaudeJob.new()
|> Oban.insert()

The raw string-keyed map is still accepted as the low-level escape hatch:

%{"prompt" => "summarize the repo", "working_dir" => "/path/to/repo"}
|> MyApp.ClaudeJob.new()
|> Oban.insert()

Telemetry

run/2 emits the following events via :telemetry:

[:oban_claude, :run, :stop]

Emitted after a successful ClaudeWrapper.query/2 call. This includes is_error: true results, which are returned without raising.

• Measurements:
  • :duration -- wall time of the query in native time units (convert with System.convert_time_unit/3)
  • :cost_usd -- the reported cost in USD from the result (0.0 when the result carries no cost)
• Metadata:
  • :result -- the %ClaudeWrapper.Result{} struct
  • :args -- the string-keyed args map passed to run/2
  • :job -- a slim map %{id, queue, worker, attempt, max_attempts, meta} for the Oban.Job, or nil when run/2 was called without :job

[:oban_claude, :run, :exception]

Emitted when the query returns {:error, _} -- both a typed %ClaudeWrapper.Error{} and an off-contract error term (which the classifier cancels, so it still surfaces here).

• Measurements:
  • :duration -- wall time of the query in native time units
  • :cost_usd -- the run's spend when the error carries one (a rail-stop :max_budget_exceeded / :max_turns_exceeded reason map does; 0.0 otherwise, including every off-contract term). Summing :cost_usd across both events gives a complete spend total.
• Metadata:
  • :error -- the %ClaudeWrapper.Error{} struct, or the raw error term on the off-contract path
  • :args -- the string-keyed args map passed to run/2
  • :job -- as above