feat: add --command to terminal creation commands

[austinywang]

Closes #2538

Summary

• add --command <text> support to new-split, new-pane, and new-surface
• deliver creation commands as Ghostty spawn-time initial_input, preserving command text literally and appending one Enter while keeping the normal interactive shell alive
• carry raw initial input through workspace, split, pane, surface, and Dock creation; reject non-terminal --type combinations and unsupported remote-tmux mirror routing explicitly
• retain the existing initial_command socket behavior for API clients that intentionally replace the shell with a one-shot process
• localize the shared CLI help description in English and Japanese

Tests

• keep the regression and fix in separate commits; CI run 31135031764 records the regression-only commit failing at the focused terminal-creation CLI step
• cover all four CLI creation commands with a fake socket, including one-request delivery, literal escape preservation, omission, whitespace-only input, non-terminal rejection, and absence of initial_command
• cover coordinator parsing, workspace/split/pane/surface creation, Dock creation, and remote-tmux fail-closed behavior
• validate Swift and Python syntax, localization JSON and locale coverage, test-target wiring, package/workspace policies, and git diff --check without running a local build

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Adds --command <text> to new-split, new-pane, new-surface, and new-workspace; for new-workspace, commands enter the shell at spawn instead of through the old post-create send, so the shell stays interactive. Closes Linear #2538.

Behavior

• Preserves command text literally and appends one Enter.
• Ignores blank input, requires a value, and rejects non-terminal --type combinations.
• Layout-based new-workspace creation ignores the command and skips auto-welcome when input is injected.
• Keeps initial_command behavior unchanged.
• Rejects initial_input for remote tmux mirrors and keeps cloud-adjacent splits local.
• Updates English and Japanese help, CLI/API docs, and workspace skills.

Validation

• Adds coordinator, workspace, Dock, mirror-routing, and fake-socket CLI coverage.
• Runs the CLI regression against the built binary in CI.
• Includes inherited Swift warning/import fixes and current cloud and moved-pane test updates.
• Replaces the mobile lane test's timing wait with a completion signal.
• Hardens app-host test stability: bounds WebKit page-load waits, queues the first Codex prompt, waits for Codex thread/start before answering, gates file-preview saves on isSaving, tolerates closed-socket EINVAL, and samples the wedged app host in CI, matching it even when launched with arguments.

^{Written for commit 7708bd9. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Added --command support for creating terminal splits, panes, surfaces, and workspaces.
  • Preserved complex command text and sends it to the new terminal with an Enter keystroke.
  • Added localized help text for the initial command option.

• Bug Fixes

  • Ignored empty or whitespace-only commands.
  • Rejected commands for unsupported non-terminal types.
  • Applied commands during workspace creation without an extra follow-up request.

• Tests

  • Added regression coverage for CLI and macOS terminal creation workflows.

---

Note

Medium Risk
Touches terminal spawn, workspace creation, and v2 control-socket creation paths used by CLI automation; behavior change for new-workspace --command (spawn vs post-create send) could affect scripts.

Overview
Adds --command to new-split, new-pane, new-surface, and layout-free new-workspace, sending literal text plus one Enter as initial_input at terminal spawn so the interactive shell stays alive. new-workspace no longer follows creation with surface.send_text; layout-based workspace creation still ignores --command. Socket RPCs pane.create, surface.split, and surface.create accept the same initial_input param, with invalid_params when it is paired with a non-terminal type; remote tmux mirror routing treats initial_input as unsupported like other local-only options.

CLI parsing moves into CMUXCLI+TerminalCreation.swift (dedicated --command parsing, blank-input omission, terminal-only validation). Help copy is localized (EN/JA).

CI adds a focused CLI regression (tests/test_cli_creation_initial_command.py), enables XCTest per-case timeouts on app-host batches, and samples wedged app hosts on batch deadline. Tests cover coordinator parsing, workspace/Dock creation, and harden flaky WebKit/Codex app-host cases with bounded waits and thread-start synchronization.

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

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The CLI accepts --command for terminal creation. Nonblank commands become initial_command and initial_input, with a trailing carriage return. Creation paths forward the input to terminal panels, while unsupported remote-mirror and non-terminal requests reject it. Tests and macOS CI validate the behavior.

Changes

Initial terminal input creation

Layer / File(s)	Summary
CLI command contract CLI/cmux.swift, Resources/Localizable.xcstrings	Creation commands parse and validate --command. Nonblank values become initial terminal input. Workspace creation no longer sends a separate surface.send_text request. Help and usage text describe the option.
RPC input contract Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/...	Pane, split, and surface creation inputs preserve nonblank raw initial_input values and omit blank values.
Terminal creation propagation Sources/DockSplitStore.swift, Sources/TabManager.swift, Sources/TerminalController+*.swift, Sources/Workspace.swift	Workspace, Dock, split, and surface creation paths forward initialInput to terminal panels. Remote-mirror paths reject it as unsupported.
Creation regression validation Packages/macOS/CmuxControlSocket/Tests/CmuxControlSocketTests/*, cmuxTests/*, tests/test_cli_creation_initial_command.py, .github/workflows/ci.yml	Tests verify input preservation, omission, command handling, non-terminal rejection, request counts, and macOS CLI execution.
Supporting test updates cmuxTests/SessionPersistenceResumeBindingTests.swift, tests/test_omp_extension_install.py, web/tests/*	Existing persistence and extension expectations are updated. Hosted Subrouter tests use current process environment values per isolated test.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant ControlCommandCoordinator
  participant TerminalController
  participant TerminalPanel
  CLI->>ControlCommandCoordinator: Send creation request with initial_command and initial_input
  ControlCommandCoordinator->>TerminalController: Pass validated creation inputs
  TerminalController->>TerminalPanel: Create terminal with initialInput

Loading

Possibly related PRs

• manaflow-ai/cmux#8691: Both modify Dock terminal creation paths.
• manaflow-ai/cmux#8783: Both modify Codex resume routing and related expectations.
• manaflow-ai/cmux#9433: Both modify workspace creation command handling.

Suggested reviewers: lawrencecchen, azooz2003-bit

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (2 errors, 2 warnings)

Check name	Status	Explanation	Resolution
Cmux User-Facing Error Privacy	❌ Error	The new remote-tmux API error now exposes the internal socket field initial_input in its message and unsupported body.	Map internal option names to safe product terms such as --command, or omit them from user-visible errors and retain raw names only in sanitized diagnostics.
Cmux Full Internationalization	❌ Error	CLI adds localized help and error keys, but both catalog entries contain only en and ja while Resources/Localizable.xcstrings supports 20 locale codes.	Add translated, non-placeholder values for the 18 missing catalog locales to both cli.terminalCreation keys: ar, bs, da, de, es, fr, it, km, ko, nb, pl, pt-BR, ru, th, tr, uk, zh-Hans, and zh-Hant.
Out of Scope Changes check	⚠️ Warning	Several changes are unrelated to #2538, including web test mocks, session persistence expectations, and OMP hook persistence updates.	Remove the unrelated web, session persistence, and OMP hook changes, or move them to separate pull requests.
Docstring Coverage	⚠️ Warning	Docstring coverage is 24.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (21 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The implementation satisfies #2538 by adding --command support with spawn-time input, literal text preservation, and interactive-shell behavior.
Cmux Swift Actor Isolation	✅ Passed	Production changes add only String? value plumbing; coordinator models are Sendable in a Swift 6 package without default MainActor isolation, and app stores/call paths are explicitly @MainActor.
Cmux Swift Blocking Runtime	✅ Passed	The PR diff adds no Swift semaphores, waits, sleeps, delayed dispatch, polling, main-queue sync, or locks; production changes only propagate initialInput, and synchronization-related additions are...
Cmux Browser Automation Off-Main	✅ Passed	The PR does not change browser.* automation or worker routing; policy files are unchanged, and new initialInput is passed only on terminal branches while browser branches remain separate.
Cmux Expensive Synchronous Load	✅ Passed	The PR adds no expensive synchronous loads in production Swift; all 5 existing loader references are unchanged, and new code only forwards initialInput.
Cmux Cache Substitution Correctness	✅ Passed	The production diff adds initial_input plumbing and CLI request handling; it replaces no fresh persistence/history/undo/snapshot read, and it contains no modified production TypeScript or JavaScript.
Cmux No Hacky Sleeps	✅ Passed	The diff adds no prohibited delay to production non-Swift runtime code; non-Swift changes are CI YAML, localization, or test-only Python/TypeScript scaffolding.
Cmux Algorithmic Complexity	✅ Passed	The production diff adds no nested scans, sorting, filtering, joins, or batch rescans; it adds one CLI-argument scan and linear string trimming, not scalable user-record processing.
Cmux Swift Concurrency	✅ Passed	Swift additions only thread initialInput; no new Dispatch, Combine, completion-handler, or fire-and-forget Task patterns. The added @MainActor annotation is test-only.
Cmux Swift @Concurrent	✅ Passed	The Swift diff adds no async/await or @concurrent functions; it adds only a synchronous pure nonisolated helper and an intentionally @MainActor test.
Cmux Swift Package Boundaries	✅ Passed	The diff keeps parsing and public creation inputs in CmuxControlSocket, while app changes only thread initialInput through AppKit/Workspace/Ghostty lifecycle code; CLI logic is in the separate cmux...
Cmux Swiftpm Lockfiles	✅ Passed	The PR adds only a CI regression step for dependency-related files; it changes no Package.swift, Package.resolved, .gitignore, or Xcode package references.
Cmux Swift Logging	✅ Passed	The Swift diff adds no print, debugPrint, dump, NSLog, Logger, or ad hoc file/stream diagnostics; existing CLI output and unchanged logs are outside this check.
Cmux Swiftui State Layout	✅ Passed	The Swift diff adds only initialInput plumbing and tests; it introduces no SwiftUI state, GeometryReader, lazy-row store references, or render-time state mutation. Existing legacy state is untouche...
Cmux Architecture Rethink	✅ Passed	The Swift diff only threads immutable initialInput values through existing creation paths into the unchanged TerminalPanel/TerminalSurface owner; it adds no timing, blocking, observer, lock, pollin...
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	No changed Swift additions contain NSWindow, NSPanel, NSWindowController, Window, or WindowGroup code; the only NSWindow test fixture is allowed, and scripts/lint_auxiliary_window_close_shortcuts.p...
Cmux Source Artifacts	✅ Passed	All 29 changed paths are hand-written source, tests, CI config, or localization; the only added file is a Python regression test, and no artifact-directory or binary paths appear in the diff.
Cmux No Test Or Debug Seam In Production Source	✅ Passed	The production Swift diff adds only runtime initialInput plumbing and parsing; it adds no DEBUG/test guard, debug/test-named member, or test-only accessor, and production callers use the new values.
Cmux No Ambient Global State	✅ Passed	Production Swift additions are private methods on CMUXCLI or an instance method on ControlCommandCoordinator; the diff adds no top-level mutable state, static namespace, or singleton.
Title check	✅ Passed	The title clearly summarizes the primary change: adding --command support to terminal creation commands.
Description check	✅ Passed	The description provides detailed change context and testing coverage, but omits the template's Demo Video, Review Trigger, and Checklist sections.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat-2538-command-flag-pane-surface

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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
`@Packages/macOS/CmuxControlSocket/Tests/CmuxControlSocketTests/ControlCommandCoordinatorSurfaceTests.swift`:
- Around line 16-50: Update capturedInitialCommand to return both a
dispatch/capture flag and the captured initialCommand value, distinguishing
omitted input from an unhandled request. In the tests covering omitted commands,
first assert that the appropriate fake input was received, then assert that its
initialCommand is nil; keep the existing method-specific coordinator dispatch
handling intact.

🪄 Autofix

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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d165398b-a3f2-41c5-823f-9cb93c2e6829

📥 Commits

Reviewing files that changed from the base of the PR and between 4cf7cc3 and ae12ff3.

📒 Files selected for processing (4)

• .github/workflows/ci.yml
• Packages/macOS/CmuxControlSocket/Tests/CmuxControlSocketTests/ControlCommandCoordinatorSurfaceTests.swift
• Packages/macOS/CmuxControlSocket/Tests/CmuxControlSocketTests/FakeSurfaceControlCommandContext.swift
• tests/test_cli_creation_initial_command.py

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[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)

CLI/cmux.swift (1)

7857-7931: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Silently dropping --command when --layout is also passed.

applyInitialCommandOption(commandOpt, to: &params) runs only when layoutOpt == nil (line 7904). If a user passes both --layout and --command, the command text is silently discarded instead of producing an error or a warning. The command-line help documents that layout surfaces define their own commands, but a user who does not read the full help text gets no feedback that --command had no effect.

Add an explicit error when both flags are supplied together, so the CLI fails fast instead of silently ignoring user input.

Proposed fix

+        if layoutOpt != nil, let commandOpt, !commandOpt.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            throw CLIError(message: "\(commandName): --command is not supported with --layout; define commands per surface in the layout JSON instead")
+        }
         if layoutOpt == nil {
             applyInitialCommandOption(commandOpt, to: &params)
         }

🤖 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 `@CLI/cmux.swift` around lines 7857 - 7931, Add a validation in the
workspace-create option handling before the conditional
applyInitialCommandOption call: when both commandOpt and layoutOpt are supplied,
throw a localized CLIError stating that --command cannot be used with --layout.
Preserve applying --command for layout-free requests and continue processing
valid layout requests unchanged.

🤖 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 `@Resources/Localizable.xcstrings`:
- Around line 53602-53617: Add translated stringUnit entries for the new
cli.terminalCreation.help.initialCommandDescription key for every locale already
supported in Resources/Localizable.xcstrings, preserving the existing en and ja
translations and matching the catalog’s established locale structure.

---

Outside diff comments:
In `@CLI/cmux.swift`:
- Around line 7857-7931: Add a validation in the workspace-create option
handling before the conditional applyInitialCommandOption call: when both
commandOpt and layoutOpt are supplied, throw a localized CLIError stating that
--command cannot be used with --layout. Preserve applying --command for
layout-free requests and continue processing valid layout requests unchanged.

🪄 Autofix

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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: eb267cdf-7087-4a27-8991-153b207d5824

📥 Commits

Reviewing files that changed from the base of the PR and between f2715d7 and d14aca9.

📒 Files selected for processing (3)

• CLI/cmux.swift
• Packages/macOS/CmuxControlSocket/Tests/CmuxControlSocketTests/ControlCommandCoordinatorSurfaceTests.swift
• Resources/Localizable.xcstrings

[austinywang]

CodeRabbit outside-diff note on new-workspace --layout --command: no change. Ignoring the top-level command for layout-backed workspaces is pre-existing, documented behavior, and this PR deliberately preserves existing new-workspace --command semantics while changing its non-layout delivery from surface.send_text to workspace.create.initial_command. Turning that combination into a new error would be an unrelated compatibility change.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[austinywang]

@coderabbitai review

[coderabbitai]

Rate Limit Exceeded

@austinywang have exceeded the limit for the number of chat messages per hour. Please wait 1 minutes and 59 seconds before sending another message.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[austinywang]

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