Add Codex launch arguments setting

[jamesx0416]

What Changed

• Added a Codex provider launchArgs setting to the shared settings schema and provider settings form.
• Pass configured launch args to codex app-server for provider probes and live session startup.
• Added focused coverage for schema trimming, settings form visibility, argv construction, and runtime/probe propagation.

Why

Codex instances need the same kind of configurable launch arguments Claude already exposes, so users can pass app-server CLI flags like -c model_provider="codex-lb" without changing the binary path. The field is split into argv tokens directly and never shell-executed.

UI Changes

Adds a small Launch arguments text field to Codex provider settings.

Screenshots will be added separately.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

UI changes:

Validation:

• bun fmt
• bun lint
• bun typecheck

---

---

Note

Medium Risk
Changes how Codex child processes are spawned across probes, sessions, and exec; incorrect user-supplied flags could break connectivity, though exec uses a filtered argv subset.

Overview
Adds a Launch arguments field to Codex provider settings (schema, patches, settings form) so users can pass extra CLI flags without changing the binary path. Values are trimmed and stored as a single string, then split into argv tokens for child_process.spawn (not shell execution).

codexAppServerArgs appends those tokens after app-server for provider status probes and live sessions (CodexSessionRuntime, CodexAdapter). codexExecLaunchArgs reuses only exec-safe flags (--strict-config, --config/-c, --enable/--disable) and drops app-server-only options such as --listen when invoking codex exec for git/title text generation.

Tests cover argv helpers, schema trimming, form field visibility, probe/adapter/runtime propagation, and exec argument filtering.

^{Reviewed by Cursor Bugbot for commit 518e65d. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add launchArgs setting to Codex provider configuration

• Adds a launchArgs string field to CodexSettings (default '') that lets users pass extra CLI flags to the Codex binary.
• The app-server spawn path (provider probe, session runtime) passes the full launchArgs through via a new codexAppServerArgs helper.
• The codex exec text-generation path filters launchArgs to only exec-safe flags (e.g. --strict-config, --config, --enable, --disable) via a new codexExecLaunchArgs helper, stripping app-server-only flags like --listen.
• Behavioral Change: Codex processes are now spawned with user-configured arguments; invalid or unsupported flags will be silently dropped by the filter rather than passed through.

^{Macroscope summarized 518e65d.}

Summary by CodeRabbit

• New Features
  • Added a "Launch arguments" field to Codex provider settings so users can pass custom arguments to the Codex app-server when starting sessions.
  • Input is trimmed and normalized (defaults to empty), and configured arguments are applied when launching the Codex service.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a trimmed launchArgs string to Codex provider settings, a codexAppServerArgs helper to build the app-server argv, threads launchArgs into provider probes and session runtime, uses it when spawning the app-server child process, and updates tests/fixtures to cover the new field.

Changes

Codex Launch Arguments

Layer / File(s)	Summary
CodexSettings schema with launchArgs field packages/contracts/src/settings.ts, packages/contracts/src/settings.test.ts	CodexSettings gains a launchArgs string field (default "", trimmed) and ServerSettingsPatch accepts optional providers.codex.launchArgs; tests verify trimming/normalization.
Launch arguments parsing helper apps/server/src/provider/Layers/CodexProvider.ts, apps/server/src/provider/Layers/codexLaunchArgs.test.ts	Adds exported codexAppServerArgs(launchArgs?: string) that returns ["app-server", ...tokens]; tests cover empty and whitespace-split inputs.
Provider probing with launch arguments apps/server/src/provider/Layers/CodexProvider.ts, apps/server/src/provider/Layers/ProviderRegistry.test.ts	Probe input types accept optional launchArgs; CodexClient.layerCommand uses codexAppServerArgs(input.launchArgs) and checkCodexProviderStatus forwards configured launchArgs into probe invocation; test asserts probe receives expected launchArgs.
Session runtime with launch arguments apps/server/src/provider/Layers/CodexSessionRuntime.ts, apps/server/src/provider/Layers/CodexAdapter.ts, apps/server/src/provider/Layers/CodexAdapter.test.ts	CodexSessionRuntimeOptions adds optional launchArgs; runtime imports helper and computes appServerArgs from options.launchArgs for ChildProcess.make(...); adapter passes codexConfig.launchArgs to runtime; tests verify flow into created runtime.
Test fixture and assertion updates apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts, apps/server/src/serverSettings.test.ts, apps/web/src/components/KeybindingsToast.browser.tsx, apps/web/src/components/settings/ProviderSettingsForm.test.ts, apps/server/src/provider/Layers/ProviderRegistry.test.ts, apps/server/src/provider/Layers/CodexAdapter.test.ts	Test helpers and fixtures updated to include launchArgs: "" in Codex provider configs; new/updated tests assert trimming and propagation of non-empty launchArgs values.

🎯 3 (Moderate) | ⏱️ ~20 minutes

"🐰
I nudge the args from settings deep,
Split by spaces, their secrets keep,
Through probes and runtimes, steady pace,
App-server starts with proper grace. 🥕"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a Codex launch arguments setting to the provider configuration.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description comprehensively covers all required template sections with clear explanations of changes, reasoning, and UI updates.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR adds a new user-configurable feature that passes CLI arguments to the codex subprocess. The new capability modifies runtime behavior in subprocess spawning and introduces potential security considerations with arbitrary argument passing that warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[jamesx0416]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/contracts/src/settings.ts (1)

209-213: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add "launchArgs" to the order array for consistency.

The order array should include "launchArgs" to ensure the field appears in the intended position in the settings form. ClaudeSettings (line 255) includes launchArgs in its order array, and the test expectation in ProviderSettingsForm.test.ts (line 21) assumes launchArgs appears after shadowHomePath.

♻️ Proposed fix

   },
   {
-    order: ["binaryPath", "homePath", "shadowHomePath"],
+    order: ["binaryPath", "homePath", "shadowHomePath", "launchArgs"],
   },
 );

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/contracts/src/settings.ts` around lines 209 - 213, The settings
schema object currently sets order: ["binaryPath", "homePath", "shadowHomePath"]
but omits "launchArgs", causing form ordering and tests to fail; update that
object's order array to include "launchArgs" after "shadowHomePath" so it
matches ClaudeSettings and the expectation in ProviderSettingsForm.test.ts,
ensuring the "order" array change is applied to the same settings object in
packages/contracts/src/settings.ts.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/server/src/provider/Layers/CodexSessionRuntime.ts`:
- Around line 721-724: The CodexAppServerSpawnError message currently logs a
hardcoded "${options.binaryPath} app-server" which can mismatch the actual
command; update the error construction where CodexAppServerSpawnError is thrown
(after the spawner.spawn call) to include the computed appServerArgs (from
codexAppServerArgs(options.launchArgs)) along with options.binaryPath so the
logged command reflects ChildProcess.make(options.binaryPath, appServerArgs,
...) and any flags from options.launchArgs; ensure you reference appServerArgs
and options.binaryPath in the error message so spawn failures show the real
command invoked.

---

Outside diff comments:
In `@packages/contracts/src/settings.ts`:
- Around line 209-213: The settings schema object currently sets order:
["binaryPath", "homePath", "shadowHomePath"] but omits "launchArgs", causing
form ordering and tests to fail; update that object's order array to include
"launchArgs" after "shadowHomePath" so it matches ClaudeSettings and the
expectation in ProviderSettingsForm.test.ts, ensuring the "order" array change
is applied to the same settings object in packages/contracts/src/settings.ts.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: b83f8476-9f14-45be-9c09-5bab8a90c3d4

📥 Commits

Reviewing files that changed from the base of the PR and between b3e8c03 and 0d0a277.

📒 Files selected for processing (12)

• apps/server/src/provider/Layers/CodexAdapter.test.ts
• apps/server/src/provider/Layers/CodexAdapter.ts
• apps/server/src/provider/Layers/CodexProvider.ts
• apps/server/src/provider/Layers/CodexSessionRuntime.ts
• apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
• apps/server/src/provider/Layers/ProviderRegistry.test.ts
• apps/server/src/provider/Layers/codexLaunchArgs.test.ts
• apps/server/src/serverSettings.test.ts
• apps/web/src/components/KeybindingsToast.browser.tsx
• apps/web/src/components/settings/ProviderSettingsForm.test.ts
• packages/contracts/src/settings.test.ts
• packages/contracts/src/settings.ts

[jamesx0416]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[jamesx0416]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[juliusmarminge]

@macroscope-app run

[macroscopeapp]

Code review triggered. Results will be posted as check runs when complete.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8939411. Configure here.}