Skip to content
Closed
Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
ac517e6
test: cover quick terminal settings
austinywang May 26, 2026
d16496f
feat: add quick terminal
austinywang May 26, 2026
c20a148
merge: sync with origin main
austinywang May 26, 2026
c51a006
fix: address quick terminal ci guards
austinywang May 26, 2026
f12cc86
fix: address quick terminal review feedback
austinywang May 26, 2026
10865c4
fix: harden quick terminal command results
austinywang May 26, 2026
0b9e4ec
fix: address quick terminal review follow-ups
austinywang May 26, 2026
b498950
fix: clear quick terminal restore target on focus change
austinywang May 26, 2026
f79c6cc
fix: isolate terminal port ordinal allocator
austinywang May 26, 2026
2f0f0f1
merge: sync with main
austinywang Jun 4, 2026
f07629a
docs: document quick terminal setting keys
austinywang Jun 4, 2026
6520b9b
fix: localize quick terminal search aliases
austinywang Jun 4, 2026
5af4c24
Merge remote-tracking branch 'origin/main' into issue-327-does-cmux-s…
austinywang Jun 14, 2026
af7a08d
fix: regenerate Swift file length budget
austinywang Jun 14, 2026
f34113a
Merge remote-tracking branch 'origin/main' into issue-327-does-cmux-s…
austinywang Jun 14, 2026
9c48ac0
fix: sync quick terminal after main merge
austinywang Jun 14, 2026
fa28473
fix: localize quick terminal shortcut docs
austinywang Jun 14, 2026
9ac9c55
merge: sync quick terminal with main
austinywang Jun 18, 2026
153d6d2
fix: handle quick terminal exit lifecycle
austinywang Jun 18, 2026
d30eeac
chore: refresh swift file length budget
austinywang Jun 18, 2026
eb674c3
fix: redact CLI argument errors
austinywang Jun 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,7 @@ All notable changes to cmux are documented here.
## [0.64.10] - 2026-05-23

### Added
- Quick Terminal panel with a configurable position/size, Option-Command-backtick shortcut, command palette action, and `cmux quick-terminal` CLI controls.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
- Copy on Select setting copies the active terminal selection to the clipboard as soon as the mouse is released ([#4011](https://github.com/manaflow-ai/cmux/pull/4011)) -- thanks @kallioaleksi for the report!
- CmuxExtensionKit sidebar prototypes showcase the upcoming extension API for custom workspace sidebars ([#4309](https://github.com/manaflow-ai/cmux/pull/4309))
- Ghostty Settings command palette action opens the embedded Ghostty configuration directly ([#4654](https://github.com/manaflow-ai/cmux/pull/4654))
Expand Down
91 changes: 91 additions & 0 deletions CLI/cmux.swift
Original file line number Diff line number Diff line change
Expand Up @@ -3079,6 +3079,20 @@ struct CMUXCLI {
)
return
}
if command == "quick-terminal" {
let client = try connectClient(
socketPath: resolvedSocketPath,
explicitPassword: socketPasswordArg,
launchIfNeeded: true
)
defer { client.close() }
try runQuickTerminal(
commandArgs: commandArgs,
client: client,
jsonOutput: jsonOutput
)
return
}
if command == "open" { try runOpenCommand(commandArgs: commandArgs, socketPath: resolvedSocketPath, explicitPassword: socketPasswordArg, jsonOutput: jsonOutput, idFormat: try resolvedIDFormat(jsonOutput: jsonOutput, raw: idFormatArg)); return }
if command == "diff" { try runDiffCommand(commandArgs: commandArgs, socketPath: resolvedSocketPath, explicitPassword: socketPasswordArg, jsonOutput: jsonOutput, idFormat: try resolvedIDFormat(jsonOutput: jsonOutput, raw: idFormatArg)); return }
if command == "restore-session" {
Expand Down Expand Up @@ -5283,6 +5297,64 @@ struct CMUXCLI {
CLIExecutableLocator.enclosingAppBundle()?.bundleURL.path ?? "cmux"
}

private func runQuickTerminal(
commandArgs: [String],
client: SocketClient,
jsonOutput: Bool
) throws {
let normalizedArgs = Array(commandArgs.drop(while: { $0 == "--" }))
let subcommand = normalizedArgs.first?.lowercased() ?? "toggle"
let remaining = Array(normalizedArgs.dropFirst()).filter { $0 != "--" }

let method: String
switch subcommand {
case "toggle":
method = "quick_terminal.toggle"
case "show":
method = "quick_terminal.show"
case "hide":
method = "quick_terminal.hide"
case "status":
method = "quick_terminal.status"
default:
throw CLIError(message: "quick-terminal requires one of: toggle, show, hide, status")
}
if !remaining.isEmpty {
let suffix = remaining.count == 1 ? "" : "s"
throw CLIError(message: "quick-terminal \(subcommand): unexpected \(remaining.count) argument\(suffix)")
}

let payload = try client.sendV2(method: method)
if jsonOutput {
print(jsonString(payload))
return
}

if subcommand == "status" {
print(formatQuickTerminalStatusPayload(payload))
} else {
print("OK")
}
}

private func formatQuickTerminalStatusPayload(_ payload: [String: Any]) -> String {
let available = (payload["available"] as? Bool) ?? false
let visible = (payload["visible"] as? Bool) ?? false
let position = (payload["position"] as? String) ?? "unknown"
let autoHide = (payload["auto_hide"] as? Bool) ?? false
let primarySizeRatio = (payload["primary_size_ratio"] as? Double) ?? 0
let secondarySizeRatio = (payload["secondary_size_ratio"] as? Double) ?? 0

return """
available: \(available ? "yes" : "no")
visible: \(visible ? "yes" : "no")
position: \(position)
auto_hide: \(autoHide ? "yes" : "no")
primary_size_ratio: \(String(format: "%.2f", primarySizeRatio))
secondary_size_ratio: \(String(format: "%.2f", secondarySizeRatio))
"""
}

private func runFeedback(
commandArgs: [String],
socketPath: String,
Expand Down Expand Up @@ -12886,6 +12958,23 @@ struct CMUXCLI {

Open the Settings window to Keyboard Shortcuts.
"""
case "quick-terminal":
return """
Usage: cmux quick-terminal [toggle|show|hide|status]

Control the floating quick terminal panel.

Subcommands:
toggle Toggle quick terminal visibility (default)
show Show quick terminal
hide Hide quick terminal
status Print quick terminal status

Examples:
cmux quick-terminal
cmux quick-terminal show
cmux --json quick-terminal status
"""
case "disable-browser":
return """
Usage: cmux disable-browser [--json]
Expand Down Expand Up @@ -31677,6 +31766,7 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
settings [open [target]|path|docs|<target>]
config <doctor|check|validate|path|paths|docs|documentation|reload>
shortcuts
quick-terminal [toggle|show|hide|status]
disable-browser | enable-browser | browser-status
agent-hibernation <on|off>
restore-session
Expand Down Expand Up @@ -31771,6 +31861,7 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
clear-log [--workspace <id|ref|index>] [--window <id|ref|index>]
list-log [--workspace <id|ref|index>] [--window <id|ref|index>] [--limit <n>]
sidebar-state [--workspace <id|ref|index>] [--window <id|ref|index>]
quick-terminal [toggle|show|hide|status]
set-app-focus <active|inactive|clear>
simulate-app-active
simulate-sidebar-drag --window <id|ref|index> --from <ws> --to <ws> [--duration-ms <n>] [--steps <n>]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,30 @@ public struct TerminalCatalogSection: SettingCatalogSection {
userDefaultsKey: "terminal.focusTextBoxOnNewTerminals"
)

public let quickTerminalPosition = DefaultsKey<String>(
id: "terminal.quickTerminalPosition",
defaultValue: "top",
userDefaultsKey: "quickTerminal.position"
)

public let quickTerminalPrimarySizeRatio = DefaultsKey<Double>(
id: "terminal.quickTerminalPrimarySizeRatio",
defaultValue: 0.38,
userDefaultsKey: "quickTerminal.primarySizeRatio"
)

public let quickTerminalSecondarySizeRatio = DefaultsKey<Double>(
id: "terminal.quickTerminalSecondarySizeRatio",
defaultValue: 1.0,
userDefaultsKey: "quickTerminal.secondarySizeRatio"
)

public let quickTerminalAutoHide = DefaultsKey<Bool>(
id: "terminal.quickTerminalAutoHide",
defaultValue: true,
userDefaultsKey: "quickTerminal.autoHide"
)

public let textBoxMaxLines = DefaultsKey<Int>(
id: "terminal.textBoxMaxLines",
defaultValue: 10,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,10 @@ extension Array where Element == CuratedSettingEntry {
.init(section: .terminal, id: "scrollbar", title: "Show Terminal Scroll Bar", synonyms: "terminal.showScrollBar scrollback scrollbar scroll bar right edge alternate screen tui"),
.init(section: .terminal, id: "copy-on-select", title: "Copy on Selection", synonyms: "terminal.copyOnSelect copy on selection select clipboard mouse double click triple click iterm"),
.init(section: .terminal, id: "agent-auto-resume", title: "Resume Agent Sessions on Reopen", synonyms: "terminal.autoResumeAgentSessions auto resume restore reopen relaunch quit sessions agents claude code codex opencode rovo dev rovodev toggle"),
.init(section: .terminal, id: "quick-terminal-position", title: "Quick Terminal Position", synonyms: "terminal.quickTerminalPosition quick terminal dropdown quake position top bottom left right center"),
.init(section: .terminal, id: "quick-terminal-primary-size", title: "Quick Terminal Primary Size", synonyms: "terminal.quickTerminalPrimarySizeRatio quick terminal dropdown quake primary size height width"),
.init(section: .terminal, id: "quick-terminal-secondary-size", title: "Quick Terminal Secondary Size", synonyms: "terminal.quickTerminalSecondarySizeRatio quick terminal dropdown quake secondary size height width"),
.init(section: .terminal, id: "quick-terminal-auto-hide", title: "Quick Terminal Auto-Hide", synonyms: "terminal.quickTerminalAutoHide quick terminal dropdown quake auto hide blur focus"),
.init(section: .terminal, id: "agent-hibernation", title: "Agent Hibernation", synonyms: "terminal.agentHibernation.enabled idle hibernate suspend background agents claude code codex opencode live terminals"),
.init(section: .terminal, id: "agent-hibernation-idle", title: "Hibernate After Idle Seconds", synonyms: "terminal.agentHibernation.idleSeconds idle seconds timeout delay hibernate suspend"),
.init(section: .terminal, id: "agent-hibernation-max", title: "Max Live Agent Terminals", synonyms: "terminal.agentHibernation.maxLiveTerminals max live agent terminals limit count hibernate"),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ public struct TerminalSection: View {
@State private var fontSaveTask: Task<Void, Never>?
@State private var scrollBar: DefaultsValueModel<Bool>
@State private var copyOnSelect: DefaultsValueModel<Bool>
@State private var quickTerminalPosition: DefaultsValueModel<String>
@State private var quickTerminalPrimarySizeRatio: DefaultsValueModel<Double>
@State private var quickTerminalSecondarySizeRatio: DefaultsValueModel<Double>
@State private var quickTerminalAutoHide: DefaultsValueModel<Bool>
@State private var autoResume: DefaultsValueModel<Bool>
@State private var hibernation: DefaultsValueModel<Bool>
@State private var idleSeconds: DefaultsValueModel<Double>
Expand All @@ -33,6 +37,10 @@ public struct TerminalSection: View {
_surfaceTabBarFont = State(initialValue: hostActions.surfaceTabBarFontSize())
_scrollBar = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.showScrollBar))
_copyOnSelect = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.copyOnSelect))
_quickTerminalPosition = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.quickTerminalPosition))
_quickTerminalPrimarySizeRatio = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.quickTerminalPrimarySizeRatio))
_quickTerminalSecondarySizeRatio = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.quickTerminalSecondarySizeRatio))
_quickTerminalAutoHide = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.quickTerminalAutoHide))
_autoResume = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.autoResumeAgentSessions))
_hibernation = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.agentHibernationEnabled))
_idleSeconds = State(initialValue: DefaultsValueModel(store: defaultsStore, key: catalog.terminal.agentHibernationIdleSeconds))
Expand All @@ -58,6 +66,36 @@ public struct TerminalSection: View {
}
}

private var quickTerminalPositionBinding: Binding<String> {
Binding(
get: {
QuickTerminalPositionOption(rawValue: quickTerminalPosition.current)?.rawValue
?? QuickTerminalPositionOption.top.rawValue
},
set: { newValue in
quickTerminalPosition.set(
QuickTerminalPositionOption(rawValue: newValue)?.rawValue
?? QuickTerminalPositionOption.top.rawValue
)
}
)
}

private func quickTerminalRatioBinding(_ model: DefaultsValueModel<Double>) -> Binding<Double> {
Binding(
get: { clampedQuickTerminalRatio(model.current) },
set: { model.set(clampedQuickTerminalRatio($0)) }
)
}

private func clampedQuickTerminalRatio(_ value: Double) -> Double {
min(max(value, 0.2), 1.0)
}

private func quickTerminalRatioPercentLabel(_ ratio: Double) -> String {
"\(Int((clampedQuickTerminalRatio(ratio) * 100).rounded()))%"
}

@ViewBuilder
private var resumeCommandsCard: some View {
SettingsCard {
Expand Down Expand Up @@ -155,6 +193,86 @@ public struct TerminalSection: View {
.accessibilityIdentifier("SettingsTerminalCopyOnSelectToggle")
}
SettingsCardDivider()
SettingsCardRow(
configurationReview: .json("terminal.quickTerminalPosition"),
String(localized: "settings.quickTerminal.position", defaultValue: "Quick Terminal Position"),
subtitle: String(localized: "settings.quickTerminal.position.subtitle", defaultValue: "Choose where the quick terminal slides in."),
controlWidth: 196
) {
Picker("", selection: quickTerminalPositionBinding) {
ForEach(QuickTerminalPositionOption.allCases) { option in
Text(verbatim: option.localizedName)
.tag(option.rawValue)
}
}
.labelsHidden()
.pickerStyle(.menu)
.accessibilityIdentifier("SettingsQuickTerminalPositionPicker")
.accessibilityLabel(
String(localized: "settings.quickTerminal.position", defaultValue: "Quick Terminal Position")
)
}
SettingsCardDivider()
SettingsCardRow(
configurationReview: .json("terminal.quickTerminalPrimarySizeRatio"),
String(localized: "settings.quickTerminal.primarySize", defaultValue: "Quick Terminal Primary Size"),
subtitle: String(localized: "settings.quickTerminal.primarySize.subtitle", defaultValue: "Size along the slide-in axis."),
controlWidth: 196
) {
HStack(spacing: 8) {
Slider(
value: quickTerminalRatioBinding(quickTerminalPrimarySizeRatio),
in: 0.2...1.0
)
.frame(width: 132)

Text(verbatim: quickTerminalRatioPercentLabel(quickTerminalPrimarySizeRatio.current))
.font(.system(size: 11, weight: .medium))
.foregroundStyle(.secondary)
.monospacedDigit()
.frame(width: 42, alignment: .trailing)
}
.accessibilityIdentifier("SettingsQuickTerminalPrimarySizeSlider")
}
SettingsCardDivider()
SettingsCardRow(
configurationReview: .json("terminal.quickTerminalSecondarySizeRatio"),
String(localized: "settings.quickTerminal.secondarySize", defaultValue: "Quick Terminal Secondary Size"),
subtitle: String(localized: "settings.quickTerminal.secondarySize.subtitle", defaultValue: "Size across the opposite axis."),
controlWidth: 196
) {
HStack(spacing: 8) {
Slider(
value: quickTerminalRatioBinding(quickTerminalSecondarySizeRatio),
in: 0.2...1.0
)
.frame(width: 132)

Text(verbatim: quickTerminalRatioPercentLabel(quickTerminalSecondarySizeRatio.current))
.font(.system(size: 11, weight: .medium))
.foregroundStyle(.secondary)
.monospacedDigit()
.frame(width: 42, alignment: .trailing)
}
.accessibilityIdentifier("SettingsQuickTerminalSecondarySizeSlider")
}
SettingsCardDivider()
SettingsCardRow(
configurationReview: .json("terminal.quickTerminalAutoHide"),
String(localized: "settings.quickTerminal.autoHide", defaultValue: "Quick Terminal Auto-Hide"),
subtitle: quickTerminalAutoHide.current
? String(localized: "settings.quickTerminal.autoHide.subtitleOn", defaultValue: "Hide automatically when it loses focus.")
: String(localized: "settings.quickTerminal.autoHide.subtitleOff", defaultValue: "Keep visible when focus moves away.")
) {
Toggle("", isOn: Binding(get: { quickTerminalAutoHide.current }, set: { quickTerminalAutoHide.set($0) }))
.labelsHidden()
.controlSize(.small)
.accessibilityIdentifier("SettingsQuickTerminalAutoHideToggle")
.accessibilityLabel(
String(localized: "settings.quickTerminal.autoHide", defaultValue: "Quick Terminal Auto-Hide")
)
}
SettingsCardDivider()
SettingsCardRow(
configurationReview: .json("terminal.autoResumeAgentSessions"),
String(localized: "settings.terminal.agentAutoResume", defaultValue: "Resume Agent Sessions on Reopen"),
Expand Down Expand Up @@ -214,3 +332,28 @@ public struct TerminalSection: View {
}

}

private enum QuickTerminalPositionOption: String, CaseIterable, Identifiable {
case top
case bottom
case left
case right
case center

var id: String { rawValue }

var localizedName: String {
switch self {
case .top:
return String(localized: "settings.quickTerminal.position.top", defaultValue: "Top")
case .bottom:
return String(localized: "settings.quickTerminal.position.bottom", defaultValue: "Bottom")
case .left:
return String(localized: "settings.quickTerminal.position.left", defaultValue: "Left")
case .right:
return String(localized: "settings.quickTerminal.position.right", defaultValue: "Right")
case .center:
return String(localized: "settings.quickTerminal.position.center", defaultValue: "Center")
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,10 @@ struct SettingsRowAnchorResolutionTests {
"terminal.agentHibernation.maxLiveTerminals",
"terminal.autoResumeAgentSessions",
"terminal.copyOnSelect",
"terminal.quickTerminalAutoHide",
"terminal.quickTerminalPosition",
"terminal.quickTerminalPrimarySizeRatio",
"terminal.quickTerminalSecondarySizeRatio",
"terminal.resumeCommands",
"terminal.focusTextBoxOnNewTerminals",
"terminal.showScrollBar",
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -220,6 +220,7 @@ Command palette navigation shortcuts, including ⌃ P, are also customizable and

| Shortcut | Action |
|----------|--------|
| ⌥ ⌘ ` | Toggle quick terminal (system-wide) |
| ⌘ K | Clear scrollback |
| ⌘ C | Copy (with selection) |
| ⌘ V | Paste |
Expand Down
Loading
Loading