feat: add Codex agent support

[carmandale]

Summary

Adds support for Codex as an agent in Ralph TUI.

Changes

• Added CodexAgentPlugin in src/plugins/agents/builtin/codex.ts
• Registered Codex in the built-in agents registry
• Full CLI integration with:
  • codex exec for non-interactive execution
  • Model selection via -m/--model
  • Sandbox mode configuration (read-only, workspace-write, danger-full-access)
  • --dangerously-bypass-approvals-and-sandbox for autonomous operation
  • JSONL output parsing for structured responses and subagent tracing

Testing

• bun run typecheck passes
• bun run lint passes
• bun run build passes
• ralph-tui plugins agents shows Codex plugin

Usage

ralph-tui run --agent codex --model o3

Closes #98

Summary by CodeRabbit

• New Features
  • Added an OpenAI Codex agent plugin with configurable model selection, sandbox modes and approval-bypass options.
  • Built-in registration of the Codex agent so it’s available alongside existing agents.
  • Introduced structured JSONL parsing and streaming support for Codex outputs to improve result handling and integrations.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

@carmandale is attempting to deploy a commit to the plgeek Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Walkthrough

A new CodexAgentPlugin adds OpenAI Codex integration: exec-mode invocation, binary detection, model and sandbox configuration, streaming JSONL parsing utilities, setup/validation hooks, and a factory export. The plugin is registered and re-exported from the built-in agents registry.

Changes

Cohort / File(s)	Change Summary
New Codex Agent Plugin src/plugins/agents/builtin/codex.ts	Adds CodexAgentPlugin and types (CodexJsonlMessage, JsonlParseResult), implements initialization, detection (PATH + --version), setup questions/validation, arg builder (exec flags, unique --add-dir collection), stdin passthrough, JSONL parsing (line, multi-line, streaming parser), factory createCodexAgent, and default export.
Built-in Registry Integration src/plugins/agents/builtin/index.ts	Imports and registers the Codex agent factory, adds createCodexAgent to exports, and re-exports CodexJsonlMessage and CodexAgentPlugin.

Sequence Diagram

sequenceDiagram
    actor User
    participant Plugin as CodexAgentPlugin
    participant CLI as Codex CLI
    participant Parser as JSONL Parser

    User->>Plugin: initialize(config)
    Plugin->>Plugin: set options (model, sandbox, outputMode)
    User->>Plugin: detect()
    Plugin->>CLI: run `codex --version`
    CLI-->>Plugin: version string
    Plugin-->>User: executable path + version
    User->>Plugin: buildArgs(prompt, files)
    Plugin->>Plugin: collect unique dirs, build exec args
    User->>Plugin: getStdinInput(prompt)
    Plugin-->>CLI: execute with stdin and args
    CLI-->>Plugin: streaming JSONL output
    Plugin->>Parser: parseJsonlOutput / streaming parser
    Parser-->>Plugin: messages + fallback lines
    Plugin-->>User: structured results

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 I hopped to a binary, sniffed version and name,
I gathered my dirs and fed Codex the game.
JSONL whispers came streaming and bright,
Sandbox set snug, execs ran just right.
Hooray — new agent hopping into the night! 🥕✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: add Codex agent support' accurately reflects the main change, which is implementing and integrating Codex as a new agent plugin.
Linked Issues check	✅ Passed	The pull request fully implements the core requirements from issue #98: Codex is integrated as a plugin using the existing architecture, registered in Ralph TUI for agent selection, and provides model selection and configuration options for autonomous coding tasks.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to adding Codex agent support; the new plugin implementation and integration into the built-in agents registry align with issue #98 requirements.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/plugins/agents/builtin/codex.ts`:
- Around line 88-94: The field bypassApprovals currently defaults to true which
enables dangerous auto-bypass behavior; change the default to false and require
an explicit opt-in via configuration or CLI flag before enabling it (update the
class property bypassApprovals and any places that set or read it, e.g., the
other occurrence referenced as bypass approvals at the later usage around line
~261), and ensure sandboxMode remains explicit and conservative (keep
'workspace-write' or tighten to 'read-only' as appropriate) so that bypassing
approvals/sandbox can only be activated when a clear config/CLI switch is
provided and validated.

[subsy]

Thanks for this @carmandale

Im in the process of refactoring some of the code to improve the prompt templates, package them with tracker plugins and restructure the agent plugin paths. We also now have true built in sandboxing
Im going to get all that stuff live in a 0.2.0 release and then will need this PR to be refactored. It will also need tests to pass CI, and documentation.
You're welcome to take that on, or I can pick it up - lmk

[carmandale]

Addressed CodeRabbit Feedback

Fixed the bypassApprovals security concern:

1. Changed default from true to false - Users must now explicitly opt-in to autonomous mode
2. Updated setup question - Added warning emoji and clearer prompt
3. Improved help text - Clarifies security implications

Commit: 7def788

The safer default ensures that --dangerously-bypass-approvals-and-sandbox is not automatically enabled. Users who need autonomous operation can still enable it via config or the setup wizard.

[codecov]

Codecov Report

❌ Patch coverage is 8.13953% with 395 lines in your changes missing coverage. Please review.
✅ Project coverage is 33.76%. Comparing base (cdf556b) to head (7def788).
⚠️ Report is 338 commits behind head on main.

Files with missing lines	Patch %	Lines
src/plugins/agents/builtin/codex.ts	7.51%	394 Missing ⚠️
src/plugins/agents/builtin/index.ts	75.00%	1 Missing ⚠️

❌ Your patch status has failed because the patch coverage (8.13%) is below the target coverage (50.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #118      +/-   ##
==========================================
+ Coverage   26.35%   33.76%   +7.41%     
==========================================
  Files          69       77       +8     
  Lines       16516    19184    +2668     
==========================================
+ Hits         4352     6478    +2126     
- Misses      12164    12706     +542     

Files with missing lines	Coverage Δ
src/plugins/agents/builtin/index.ts	56.25% <75.00%> (-43.75%)	⬇️
src/plugins/agents/builtin/codex.ts	7.51% <7.51%> (ø)

... and 44 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[subsy]

Closing as this is implemented in a different PR. Appreciate the contribution though!