feat: Add Codex SDK Support with Unified Adapter Pattern

[nogataka]

Summary

This PR adds support for the Codex SDK (Python) alongside the existing Claude Agent SDK, enabling users to switch between SDKs via the AUTOFORGE_SDK environment variable.

Key Changes:

• Introduced sdk_adapter/ package with a unified interface for both SDKs
• Migrated all agent and chat session code to use the new adapter pattern
• Added MCP server support for Codex SDK via config overrides

Motivation

The Codex SDK provides an alternative AI backend that may be preferred in certain environments or for specific use cases. By abstracting the SDK layer, AutoForge becomes more flexible and vendor-agnostic.

Changes

New Package: sdk_adapter/

File	Description
types.py	Unified event types (EventType, AgentEvent, AdapterOptions)
protocols.py	SDKAdapter Protocol definition
factory.py	create_adapter() factory with SDK selection logic
claude_adapter.py	Claude SDK wrapper (migrated from existing code)
codex_adapter.py	Codex SDK wrapper with MCP support

Modified Files

File	Changes
agent.py	Migrated to unified EventType-based event processing
client.py	Now uses create_adapter() factory for SDK-agnostic client creation
registry.py	Added get_sdk_type() and get_effective_sdk_env_for_codex()
server/services/assistant_chat_session.py	Migrated to use sdk_adapter
server/services/spec_chat_session.py	Migrated to use sdk_adapter
server/services/expand_chat_session.py	Migrated to use sdk_adapter
server/services/process_manager.py	Added AUTOFORGE_SDK to subprocess environment
start_ui.py	Added AUTOFORGE_SDK to forwarded env vars

Configuration

File	Changes
.env.example	Added AUTOFORGE_SDK documentation
requirements.txt	Added codex-sdk-py>=0.0.6
requirements-prod.txt	Added codex-sdk-py>=0.0.6

Usage

# Use Claude SDK (default)
export AUTOFORGE_SDK=claude
python start_ui.py

# Use Codex SDK
export AUTOFORGE_SDK=codex
python start_ui.py

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     AutoForge Agent                         │
├─────────────────────────────────────────────────────────────┤
│                     sdk_adapter                             │
│  ┌─────────────────┐        ┌─────────────────┐            │
│  │ ClaudeAdapter   │        │ CodexAdapter    │            │
│  │                 │        │                 │            │
│  │ - Claude SDK    │        │ - Codex SDK     │            │
│  │ - PreToolUse    │        │ - MCP via TOML  │            │
│  │   hooks         │        │   config        │            │
│  └────────┬────────┘        └────────┬────────┘            │
│           │                          │                      │
│           ▼                          ▼                      │
│  ┌─────────────────┐        ┌─────────────────┐            │
│  │ claude-agent-sdk│        │ codex-sdk-py    │            │
│  └─────────────────┘        └─────────────────┘            │
└─────────────────────────────────────────────────────────────┘

SDK Feature Comparison

Feature	Claude SDK	Codex SDK
Text streaming	✅	✅
Tool calls	✅	✅
MCP servers	✅ (dict config)	✅ (TOML config)
PreToolUse hooks	✅	❌
Multimodal input	✅	⚠️ (text only)
Permission modes	✅	✅ (via ApprovalMode)

Codex SDK Limitations

1. No PreToolUse hooks: Codex SDK uses event-based architecture without pre-execution blocking
2. MCP via TOML: MCP servers are configured via --config CLI flag with TOML format
3. Multimodal: Image inputs are extracted as text-only with warning
4. Model selection: Uses Codex's default model (Claude model names not applicable)

Testing

# Verify Claude SDK still works
export AUTOFORGE_SDK=claude
python autonomous_agent_demo.py --project-dir test-project

# Test Codex SDK
export AUTOFORGE_SDK=codex
python autonomous_agent_demo.py --project-dir test-project

# Run existing tests
ruff check .
mypy .
python test_security.py

Breaking Changes

None. Default behavior unchanged (Claude SDK).

[brainit-consulting]

Summary

This PR adds support for the Codex SDK (Python) alongside the existing Claude Agent SDK, enabling users to switch between SDKs via the AUTOFORGE_SDK environment variable.

Key Changes:

• Introduced sdk_adapter/ package with a unified interface for both SDKs
• Migrated all agent and chat session code to use the new adapter pattern
• Added MCP server support for Codex SDK via config overrides

Motivation

The Codex SDK provides an alternative AI backend that may be preferred in certain environments or for specific use cases. By abstracting the SDK layer, AutoForge becomes more flexible and vendor-agnostic.

Changes

New Package: sdk_adapter/

File Description
types.py Unified event types (EventType, AgentEvent, AdapterOptions)
protocols.py SDKAdapter Protocol definition
factory.py create_adapter() factory with SDK selection logic
claude_adapter.py Claude SDK wrapper (migrated from existing code)
codex_adapter.py Codex SDK wrapper with MCP support

Modified Files

File Changes
agent.py Migrated to unified EventType-based event processing
client.py Now uses create_adapter() factory for SDK-agnostic client creation
registry.py Added get_sdk_type() and get_effective_sdk_env_for_codex()
server/services/assistant_chat_session.py Migrated to use sdk_adapter
server/services/spec_chat_session.py Migrated to use sdk_adapter
server/services/expand_chat_session.py Migrated to use sdk_adapter
server/services/process_manager.py Added AUTOFORGE_SDK to subprocess environment
start_ui.py Added AUTOFORGE_SDK to forwarded env vars

Configuration

File Changes
.env.example Added AUTOFORGE_SDK documentation
requirements.txt Added codex-sdk-py>=0.0.6
requirements-prod.txt Added codex-sdk-py>=0.0.6

Usage

# Use Claude SDK (default)
export AUTOFORGE_SDK=claude
python start_ui.py

# Use Codex SDK
export AUTOFORGE_SDK=codex
python start_ui.py

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     AutoForge Agent                         │
├─────────────────────────────────────────────────────────────┤
│                     sdk_adapter                             │
│  ┌─────────────────┐        ┌─────────────────┐            │
│  │ ClaudeAdapter   │        │ CodexAdapter    │            │
│  │                 │        │                 │            │
│  │ - Claude SDK    │        │ - Codex SDK     │            │
│  │ - PreToolUse    │        │ - MCP via TOML  │            │
│  │   hooks         │        │   config        │            │
│  └────────┬────────┘        └────────┬────────┘            │
│           │                          │                      │
│           ▼                          ▼                      │
│  ┌─────────────────┐        ┌─────────────────┐            │
│  │ claude-agent-sdk│        │ codex-sdk-py    │            │
│  └─────────────────┘        └─────────────────┘            │
└─────────────────────────────────────────────────────────────┘

SDK Feature Comparison

Feature Claude SDK Codex SDK
Text streaming ✅ ✅
Tool calls ✅ ✅
MCP servers ✅ (dict config) ✅ (TOML config)
PreToolUse hooks ✅ ❌
Multimodal input ✅ ⚠️ (text only)
Permission modes ✅ ✅ (via ApprovalMode)

Codex SDK Limitations

1. No PreToolUse hooks: Codex SDK uses event-based architecture without pre-execution blocking
2. MCP via TOML: MCP servers are configured via --config CLI flag with TOML format
3. Multimodal: Image inputs are extracted as text-only with warning
4. Model selection: Uses Codex's default model (Claude model names not applicable)

Testing

# Verify Claude SDK still works
export AUTOFORGE_SDK=claude
python autonomous_agent_demo.py --project-dir test-project

# Test Codex SDK
export AUTOFORGE_SDK=codex
python autonomous_agent_demo.py --project-dir test-project

# Run existing tests
ruff check .
mypy .
python test_security.py

Breaking Changes

None. Default behavior unchanged (Claude SDK).

Very Cool! Thanks! (Can you confirm that this ultimately means people can use AutoForge with either their Claude Code Subscription and / or their Codex subscription? (NOT API - too expensive). We should let users use them in tandem even with graceful failover between them when a user's rate limit is reached and or waiting to reset.

[nogataka]

Yes, your understanding is correct.

AutoForge can be used with either a Claude Code subscription and/or a Codex subscription, without relying on the API (which would be prohibitively expensive). Users should be able to use both in tandem, with graceful failover between them—so if one hits a rate limit or is waiting for a reset, AutoForge can automatically switch to the other to maintain continuity.

[nogataka]

@leonvanzyl
what do you think about this feature? Would you be able to merge it?