#2222·swarms

[FEAT] Add an opt-in Codex CLI backend configurable through Agent/YAML

Author: AmIrRX0Created Sep 10, 2026Updated Sep 10, 2026

Is your feature request related to a problem? Please describe.

Swarms supports custom models through Agent(llm=...), but using a locally authenticated Codex CLI currently requires a user-written adapter. A YAML-based workflow cannot select that adapter through built-in configuration.

The use case is running Swarms agents with the developer's own existing Codex login, including supported ChatGPT account authentication, while keeping orchestration in Swarms. This should use the official Codex client and remain subject to the account's access and usage limits.

Describe the solution you'd like

Add a small, optional Codex CLI backend that can be selected from Python and the existing YAML loader. The configuration names below are illustrative, subject to maintainer feedback:

yaml
agents:
  - agent_name: LocalAssistant
    system_prompt: Answer the user's task clearly and concisely.
    llm_backend: codex
    max_loops: 1
    codex_config:
      timeout: 180

The initial scope would be text input/output and bounded agent/workflow execution:

  • Reuse the existing custom-LLM interface and official codex exec command; no direct calls to private endpoints or reading/copying login tokens.
  • Correctly forward the system prompt and message history, including the current task=None, messages=[...] call path.
  • Validate configuration and provide actionable errors for a missing CLI, missing login, timeout, non-zero exit, or empty response.
  • Document model selection, working-directory isolation, read-only sandbox defaults, and user-configuration handling.
  • Reject unsupported Swarms tool-call, image, or streaming options explicitly in the first version.
  • Keep existing LiteLLM behavior unchanged unless the backend is selected.

Describe alternatives you've considered

  • Keep a custom adapter in each application. This already works, but duplicates message conversion, subprocess handling, and configuration wiring.
  • Use an ordinary API-key provider through LiteLLM. That remains appropriate for applications using API billing.
  • Use the official Codex SDK/App Server as the transport instead of the CLI. I am open to this if it better fits the project's integration conventions.

Additional context

A local text-only prototype was tested with Swarms 15.0.2 (f9459e1), Python 3.13, and Codex CLI 0.147.0 on macOS. A real two-agent SequentialWorkflow (writer → reviewer) completed through the existing Codex login. This validates the basic integration path; configuration support and the broader compatibility/error matrix still need implementation and tests.

For a contribution, I would include focused offline tests for configuration, message forwarding, subprocess failures, and unsupported options, plus a minimal example notebook and setup documentation as requested by the contribution guidelines. No credentials would be required in CI.

Reference: Official Codex non-interactive documentation.

Would this opt-in backend be welcome? If so, I would be happy to submit a focused PR after agreeing on the configuration and preferred transport.