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
User-supplied CLI tokens change how Codex child processes are spawned for sessions, probes, and exec; mistakes could break Codex connectivity but args are not shell-executed.

Overview
Adds a Launch arguments field to Codex provider settings (schema, patch trimming, and settings UI) so users can pass extra Codex CLI flags without changing the binary path.

Configured args are tokenized on whitespace and forwarded into codex app-server for provider status probes and live session startup (CodexAdapter → CodexSessionRuntime), with helpers codexAppServerArgs / codexSessionAppServerArgs keeping the app-server subcommand first. For codex exec git/text generation, codexExecLaunchArgs forwards only exec-safe flags (e.g. --strict-config, --config/-c, --enable/--disable) and drops app-server-only options like --listen.

Includes focused tests for argv construction, probe/runtime propagation, and exec filtering. Also hoists connection catalog encode/decode in the mobile catalog store (no behavior change).

^{Reviewed by Cursor Bugbot for commit 006c9f5. 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 (trimmed, default empty) and CodexSettingsPatch in settings.ts, exposing it to clients and forms.
• Passes launchArgs through the Codex adapter and session runtime so the spawned app-server process receives additional CLI arguments.
• Introduces codexExecLaunchArgs in CodexProvider.ts to filter launch args to exec-safe flags only (e.g. --strict-config, --config), dropping app-server-only flags like --listen.
• Applies filtered launch args to codex exec commands in CodexTextGeneration.ts and propagates them through provider status checks.
• Behavioral Change: Codex processes spawned for both session and text generation now include user-configured launch args where previously none were passed.

^{Macroscope summarized 006c9f5.}

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 follows the required template and includes clear What Changed, Why, UI Changes, and Checklist sections.

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

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new configuration setting (launchArgs) that changes how Codex sessions are spawned. While well-implemented with tests, new features affecting process execution warrant human review to validate design decisions around allowed arguments and propagation.

^{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.

[macroscopeapp]

The Effect Service Conventions check found one issue with how the spawn error captures the launch command. See the inline comment.

^{Posted via Macroscope — Effect Service Conventions}