pitch: allow codex in other stages rather than only external reviews

[vwdss]

I know ralphex is intentionally Claude-first and opinionated tool. And I’m not proposing to change that philosophy or default behavior. This is a proposal to make provider choice more flexible per phase, while keeping Claude as the default primary path. If this direction makes sense to you, I’m ready to invest more time polishing it for production quality; if not, I can keep it as a local customization or a public fork (if you allow it). I already have an initial working prototype (which shows that this works without any regression) and wanted to check whether this is worth pushing further upstream.

Why I think this is worth considering now:

• Codex CLI has become much more capable - subagents were recently added, structured output with --json flag.
• Codex 5.3 model is very comparable to Opus (opinions vary which is better) at a much better price.
• Provider flexibility improves resilience (provider limits/outages) without forcing users to change habits.
• It enables mixed pipelines (use each tool where it performs best) while preserving current UX for existing users.
• It creates room for experimentation without making the project too "generic". If Codex is lagging behind with features, its funtionality could be always degraded, keeping this project Claude-first.
• Codex support burden could be put on community, by stating that only default path (Claude centric) is guaranteed and verified.

Architecture overview of what’s already implemented:

• Role-based provider routing: task, review, external, eval, plan, and finalize are treated as explicit workflow roles, each configurable to a provider.
• Unified execution contract: both Claude and Codex run through the same normalized runtime event/result model (streaming text, progress, lifecycle signals, final output, errors), so orchestration logic stays stable.
• Codex adapter maturity: added robust JSON event parsing (with tolerance for noise/retry events).
• Runner decoupling: orchestration no longer assumes fixed “Claude phases vs Codex phase”; it resolves provider per role at runtime.
• Provider-aware prompts/options: prompt selection and agent/model options are provider-aware where needed, while retaining compatibility with existing prompt/agent setups.
• Backward compatibility layer: default mapping remains unchanged, legacy config keys are still read, and existing phase/progress naming remains compatible for UI/log parsing.
• Dependency checks become role-aware: only required tools for active roles are enforced.
• Coverage: test matrix expanded for legacy behavior, mixed-provider pipelines, failure modes, and web/progress compatibility.

If you’re open to it, I can continue with cleanup/polish work and narrow it to whatever scope you’d be comfortable merging. Otherwise I would keep it separate.

[umputun]

thx for the detailed write-up.

this is already achievable with existing configuration, without changes to ralphex core.

for Claude phases (tasks, reviews, plan creation, finalize) - claude_command is configurable. any CLI tool that produces Claude-compatible stream-json output works as a drop-in replacement. this was confirmed with Cursor CLI in #61 - just set claude_command and claude_args, done. if a provider doesn't natively emit compatible output, a wrapper script can translate it - this works for Codex, Gemini, or any other tool.

for external review phase - already supports codex, custom, or none via external_review_tool. the custom option (#59) lets you wrap any AI tool as a script.

for per-phase configuration - --config-dir (#97) allows different config directories per invocation, so you can use different providers for different workflow phases.

the combination of these three covers the use cases described. adding provider-specific adapters to core was considered and rejected in #59 - maintaining parsing, streaming, signal detection, and error handling per provider creates a support burden that doesn't justify the convenience gain over wrapper scripts.

pls use discussions for pitches/ideas like this, issues are for bugs and actionable feature requests.

[vwdss]

Thanks,
I will try this approach and will write the feedback later.

P.S. I did not know discussions feature is a thing in GitHub, so yeah, I would use it next time.

[umputun]

Follow-up on this — added a working codex wrapper script and documentation in #133.

What's included:

• scripts/codex-as-claude.sh — translates codex JSONL events to Claude stream-json format via jq, so codex can be used as a drop-in replacement for Claude in task/review phases
• docs/custom-providers.md — detailed guide covering the wrapper, how to write your own for other providers (Gemini CLI, ollama, OpenRouter), signal detection, and troubleshooting
• README/CLAUDE.md updates

Config to use it:

claude_command = /path/to/scripts/codex-as-claude.sh
claude_args =

Environment variables: CODEX_MODEL (model selection), CODEX_SANDBOX (sandbox mode), CODEX_VERBOSE (include command execution output).

Tested end-to-end — tasks, all review phases, and finalize completed successfully. The wrapper filters out command execution noise by default (codex reads many files on startup), only passing through agent messages.

The custom-providers doc also includes minimal templates for writing wrappers for other tools, so this should cover the use case without needing core routing changes.

[vwdss]

I tried this approach. It works good enough for my use case. I managed to write my own adapter before you added yours. Guide helped me to finalize it.

One note though: I find reasoning messages from codex useful, rather than skippable. They do not contain much text in the output, but provide logical glue to agent_message outputs.

{"type":"item.completed","item":{"id":"item_0","type":"reasoning","text":"**Preparing git log summary**"}}
{"type":"item.completed","item":{"id":"item_1","type":"agent_message","text":"I’ll inspect the last 3 commits and summarize what changed in each one using their messages and diff stats."}}
{"type":"item.completed","item":{"id":"item_10","type":"reasoning","text":"**Checking commit message details**"}}
{"type":"item.completed","item":{"id":"item_11","type":"agent_message","text":"I pulled the added/removed test names; next I’ll check commit metadata to capture any explicit rationale from the commit messages."}}

Thanks!