Skip to main content

​
useCodex Hook

Runs the same execution pipeline as <Codex>, but returns state for custom rendering. The source of truth is the Smithers DB (agents table). 
import { useCodex } from "smithers-orchestrator";

function CodexPanel() {
  const { status, result, error, model } = useCodex({
    model: "o4-mini",
    children: "Implement the missing tests.",
  });

  return (
    <panel>
      <text>Model: {model}</text>
      <text>Status: {status}</text>
      {error && <text>Error: {error.message}</text>}
      {result && <text>Output: {result.output}</text>}
    </panel>
  );
}

​
API

function useCodex(props: CodexProps): UseCodexResult

interface UseCodexResult {
  status: "pending" | "running" | "complete" | "error"
  agentId: string | null
  executionId: string | null
  model: string
  result: AgentResult | null
  error: Error | null
  tailLog: TailLogEntry[]
}

​
Props

PropTypeDefaultDescription
childrenReactNode—The prompt to send to Codex
model'o3' | 'o4-mini' | 'gpt-4o' | 'gpt-4' | string'o4-mini'Codex model to use
sandboxMode'read-only' | 'workspace-write' | 'danger-full-access'—Sandbox mode for command execution
approvalPolicy'untrusted' | 'on-failure' | 'on-request' | 'never'—Approval policy for commands
fullAutoboolean—Enable full-auto mode (sets -a on-request --sandbox workspace-write)
bypassSandboxboolean—Bypass all approvals and sandbox (EXTREMELY DANGEROUS)
cwdstring—Working directory for the agent
skipGitRepoCheckboolean—Skip git repository check
addDirsstring[]—Additional directories that should be writable
imagesstring[]—Images to attach to the prompt
profilestring—Configuration profile from config.toml
configOverridesRecord<string, unknown>—Configuration overrides (key=value pairs)
timeoutnumber—Timeout in milliseconds
schemaz.ZodType—Zod schema for structured output validation
schemaRetriesnumber2Maximum retries for schema validation failures
validate(result: AgentResult) => boolean | Promise<boolean>—Validate result before accepting
retryOnValidationFailureboolean—Retry if validation fails
maxRetriesnumber—Maximum retry attempts
stopConditionsStopCondition[]—Conditions that will stop the agent
middlewareSmithersMiddleware[]—Middleware applied to this execution
tailLogCountnumber10Number of tail log entries to display during execution
tailLogLinesnumber10Number of lines to show per tail log entry
jsonOutputboolean—Enable JSON output mode
reportingEnabledboolean—Enable database reporting for this agent
onFinished(result: AgentResult) => void—Called when agent finishes successfully
onError(error: Error) => void—Called when agent encounters an error
onProgress(message: string) => void—Called for progress updates
onStreamPart(part: SmithersStreamPart) => void—Called for typed stream events (when enabled)

​
Notes

  • Requires SmithersProvider context.
  • Respects ExecutionScope and executionEnabled.
  • tailLog is in-memory; status/result come from the DB.

​
Authentication

Uses the codex CLI authentication. Either:
  • Subscription: Run codex login once (uses ChatGPT Plus/Pro/Team credits)
  • API Key: Set OPENAI_API_KEY environment variable
See Codex Authentication for details.

Codex Component

JSX wrapper around the same execution

Agents API

DB schema and methods