Allow narrower sidebar widths via configurable minimum

[austinywang]

Fixes #6784

Problem

The left (workspace) sidebar couldn't be dragged narrower than the hard-coded 216pt floor (minimumSidebarWidth in Sources/SessionPersistence.swift), and there was no config key to override it. As the reporter notes, nearly half the sidebar is dead space at that width.

Solution

Expose the minimum as a first-class setting, mirroring the existing RightSidebarWidthSettings ("Dock Max Width") pattern so all layers share one source of truth.

• New policy LeftSidebarWidthSettings (in CmuxSettings): cmux.json key sidebar.leftMinWidth, UserDefaults key sidebarMinimumWidth (unchanged → back-compatible), default 216, configurable range 100…260 (floor lowered from 120 so users can reclaim ~half the sidebar), plus a clamp helper.
• SessionPersistencePolicy now delegates its min-width constants + sanitizer to that policy. Default/minimum stay 216 → existing users see no change; only the configurable floor moved.
• cmux.json: sidebar.leftMinWidth is parsed (clamped) by the settings file store and added to the supported-paths set.
• Settings UI: a "Sidebar Minimum Width" slider row in the Sidebar section + a curated search entry, localized (en/ja).
• Docs: documented in web/data/cmux.schema.json and the configuration docs (en.json/ja.json).

How to use

// ~/.config/cmux/cmux.json
{ "sidebar": { "leftMinWidth": 120 } }

…or drag the Settings → Sidebar → Sidebar Minimum Width slider. The sidebar can then be dragged down to the configured floor (clamped 100–260).

Tests

• LeftSidebarWidthSettings clamp + identifiers (CmuxSettings package).
• cmux.json apply + clamp, resolvedMinimumSidebarWidth, ContentView.clampedSidebarWidth drag-floor, and range/key parity (cmuxTests/SidebarWidthPolicyTests.swift).
• Search anchor resolution for the new row (CmuxSettingsUI).

Default behavior is unchanged (216 default/minimum preserved; all existing width tests still pass).

🤖 Generated with Claude Code

---

Summary by cubic

Make the left (workspace) sidebar’s minimum width configurable so users can drag it narrower (100–260 pt). Default stays 216 pt; set via sidebar.leftMinWidth in cmux.json or a Settings slider. Addresses #6784.

• New Features

  • Added LeftSidebarWidthSettings (source of truth): key sidebar.leftMinWidth, UserDefaults sidebarMinimumWidth, 100–260 pt range (default 216), clamp helper.
  • SessionPersistencePolicy now uses this policy; the drag floor respects the configured value.
  • Settings: “Sidebar Minimum Width” slider (shows value, Reset) and a curated search entry; fully localized.
  • Config: added JSON‑path support and loader that reads and clamps from cmux.json.
  • Tests: policy clamp + identifiers, cmux.json apply/clamp, drag‑floor behavior, and settings anchor resolution; sidebar width tests migrated to Swift Testing.

• Bug Fixes

  • Schema: web/data/cmux.schema.json uses exclusiveMinimum: 0 to match the loader; docs translated across all web locales.
  • CI: refreshed .github/swift-file-length-budget.tsv for the new settings row and tests.

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

Summary by CodeRabbit

• New Features

  • Added a configurable “Sidebar Minimum Width” setting for the left/workspace panel, including a slider in the settings UI.
  • Persisted via configuration and enforced during load with schema support.

• Bug Fixes

  • Clamp logic now robustly keeps values within the supported range, and invalid/non-finite inputs fall back to the default.

• Documentation & Localization

  • Added localized help text for the new sidebar.leftMinWidth setting across supported languages.

• Tests

  • Expanded and updated coverage for clamping, persistence parsing, and settings path resolution.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cmux	Ready	Preview, Comment	Jul 4, 2026 9:32pm
cmux-staging	Building	Preview, Comment	Jul 4, 2026 9:32pm

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a configurable left sidebar minimum width setting across settings storage, persistence, cmux.json parsing, UI, schema, localization, and tests. Also migrates sidebar width tests to Swift Testing and includes unrelated iOS and localization ordering edits.

Changes

Left Sidebar Minimum Width Feature

Layer / File(s)	Summary
Policy contract and tests Packages/macOS/CmuxSettings/Sources/CmuxSettings/Policies/LeftSidebarWidthSettings.swift, Packages/macOS/CmuxSettings/Tests/CmuxSettingsTests/LeftSidebarWidthSettingsTests.swift	Adds LeftSidebarWidthSettings with keys, bounds, range, and clamping logic, plus dedicated tests.
Settings catalog and JSON path wiring Packages/macOS/CmuxSettings/Sources/CmuxSettings/Keys/SidebarCatalogSection.swift, Sources/CmuxSettingsJSONPathSupport.swift	Adds the leftMinWidth catalog entry and registers the settings path/typealias.
Session persistence and file parsing Sources/SessionPersistence.swift, Sources/KeyboardShortcutSettingsFileStore.swift	Uses the shared width policy constants and clamping logic, and parses leftMinWidth from cmux.json.
Sidebar settings UI Packages/macOS/CmuxSettingsUI/Sources/CmuxSettingsUI/Sections/SidebarSection.swift, Packages/macOS/CmuxSettingsUI/Sources/CmuxSettingsUI/Navigation/CuratedSettingEntry+Default.swift, Packages/macOS/CmuxSettingsUI/Tests/CmuxSettingsUITests/SettingsRowAnchorResolutionTests.swift	Adds the sidebar minimum-width row, slider binding, curated search entry, and row-path test update.
Schema and localization strings web/data/cmux.schema.json, Resources/Localizable.xcstrings, web/messages/*.json	Adds sidebar.leftMinWidth to the schema and localized descriptions across the resource files.
SidebarWidthPolicyTests migration cmuxTests/SidebarWidthPolicyTests.swift	Converts the sidebar width and color contrast tests from XCTest to Swift Testing.

Unrelated Minor Edits

Layer / File(s)	Summary
iOS UIKit conditional compilation tweaks Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalViewportInputs.swift, Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/TerminalViewportSnapshot.swift	Adjusts #endif boundaries without changing behavior.
Localizable.xcstrings reordering Resources/Localizable.xcstrings	Reorders existing agent notification and terminal context menu localization entries.

Estimated code review effort: 3 (Moderate) | ~30 minutes

---

Important

Pre-merge checks failed

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

❌ Failed checks (1 error, 2 warnings)

Check name	Status	Explanation	Resolution
Cmux No Hacky Sleeps	❌ Error	download-button.tsx adds requestAnimationFrame to delay dialog opening one frame to dodge an outside-press race; that’s a coordination timer in production TSX.	Open the dialog from the menu’s close/selection completion signal or another real readiness event, not a frame-delayed dispatch.
Out of Scope Changes check	⚠️ Warning	Resources/Localizable.xcstrings also reorders unrelated agent-notification and terminal-context-menu strings, which is outside the sidebar-width scope.	Keep this PR focused on sidebar-width changes and move unrelated localization reordering into a separate cleanup change.
Description check	⚠️ Warning	The description covers the summary and testing, but it is missing the Demo Video, Review Trigger, and Checklist sections required by the template.	Add the missing Demo Video, Review Trigger, and Checklist sections, and include a video link for the sidebar UI change if available.

✅ Passed checks (22 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes expose and use a configurable left sidebar minimum width, matching the issue's request to remove the hard-coded 216pt floor.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Cmux Swift Actor Isolation	✅ Passed	PASS: The new left-sidebar policy is a plain Sendable value helper; UI changes stay on @MainActor, and loader/session code only touches local data.
Cmux Swift Blocking Runtime	✅ Passed	No production Swift files changed in the actual diff; the submodule update contains no Swift-file delta, so no blocking primitives were introduced.
Cmux Browser Automation Off-Main	✅ Passed	PR only changes submodule pointers; no target browser-automation files or browser.* routing code were touched.
Cmux Expensive Synchronous Load	✅ Passed	New seed/list scans run via Task.detached, and the new list-path filter uses boundedTranscriptPath/fileExists only; the codex tree scan stays on the open-transcript path.
Cmux Cache Substitution Correctness	✅ Passed	The PR adds a config-backed width policy with a cold fallback; no fresh authoritative read was swapped for a stale/opportunistic cache in persistence/history/snapshot code.
Cmux Algorithmic Complexity	✅ Passed	Changed production code is O(1) per setting/drag path; only fixed-size observation lists and simple clamps/parsing were added, with no scalable rescans.
Cmux Swift Concurrency	✅ Passed	PASS: the diff’s new leftMinWidth policy/UI/tests are synchronous; no new DispatchQueue, Combine, completion-handler, or fire-and-forget Task patterns were introduced.
Cmux Swift @Concurrent	✅ Passed	No touched Swift diff adds invalid @concurrent/nonisolated async usage; the only async UI call is preexisting and already hops to FontConfigWriter off-main actor.
Cmux Swift File And Package Boundaries	✅ Passed	Core sidebar-width logic lives in the new 51-line CmuxSettings package type; touched app files only gained small glue updates (+10/+8/+56) and stay below the rule thresholds.
Cmux Swiftpm Lockfiles	✅ Passed	Project diff only adds source files; no XCRemoteSwiftPackageReference/XCSwiftPackageProductDependency, Package.swift, Package.resolved, .gitignore, or workflow changes.
Cmux Swift Logging	✅ Passed	Only logging change is DEBUG-only input tracing in TerminalInputDebugLog; no added production print/NSLog/debugPrint or unsafe Logger changes.
Cmux User-Facing Error Privacy	✅ Passed	No new user-facing errors/alerts/recovery copy were added; the only new invalid-setting log is internal and privacy-hashed, and the new strings are settings/docs copy.
Cmux Full Internationalization	✅ Passed	New Swift UI strings use String(localized:defaultValue:); the xcstrings key has all 20 catalog locales; web messages cover every locale in routing.ts.
Cmux Swiftui State Layout	✅ Passed	SidebarSection only adds a new @State DefaultsValueModel row inside a static VStack card; no GeometryReader, lazy-list store refs, or render-time writes were introduced.
Cmux Architecture Rethink	✅ Passed	New LeftSidebarWidthSettings mirrors the existing sidebar policy pattern; no sleeps, polling, locks, or split lifecycle ownership were introduced, and the source of truth stays centralized.
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	PASS: The PR only changes settings/persistence/docs; diff-wide scan found no new NSWindow/WindowGroup/NSPanel code, no cmux.* window IDs, and no cmuxAuxiliaryWindowIdentifiers edits.
Cmux Source Artifacts	✅ Passed	PASS: The only changed paths are submodule pointer updates (ghostty, vendor/bonsplit); no logs, caches, build output, or scratch artifacts are present.
Cmux No Test Or Debug Seam In Production Source	✅ Passed	Changed production sources only add DEBUG logging and a dedicated debug logger; no new ForTesting/TestHook accessors or test-only seams were added.
Cmux No Ambient Global State	✅ Passed	No new ambient globals: the sidebar policy is a constructable value type used via instances, and added helpers stay inside types/extensions; no new singleton/state surfaces.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: making the sidebar minimum width configurable.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-6784-allow-narrower-sidebar-widths

---

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

[greptile-apps]

Greptile Summary

This PR makes the left (workspace) sidebar's minimum resize width configurable via a new LeftSidebarWidthSettings policy, mirroring the existing RightSidebarWidthSettings pattern. Default behavior is unchanged (216 pt default and floor); users can lower the floor to 100 pt via sidebar.leftMinWidth in cmux.json or a new Settings slider.

• New LeftSidebarWidthSettings struct in CmuxSettings: provides the single source of truth for jsonKey, settingsPath, minimumWidthKey, defaultMinimumWidth (216), range (100–260), and the clampedMinimumWidth helper. SessionPersistencePolicy now delegates all min-width constants and its sanitizedMinimumSidebarWidth to this type.
• Settings UI and catalog: a SettingsCardRow slider with value display and Reset button is added to SidebarSection.swift; CuratedSettingEntry+Default.swift and SidebarCatalogSection.swift are updated; all three new string keys are translated across every supported app locale (xcstrings) and every web locale.
• cmux.json loader (KeyboardShortcutSettingsFileStore.swift) and CmuxSettingsJSONPathSupport.swift parse and clamp the new key, following the same exclusiveMinimum: 0 + runtime-clamp pattern as rightMaxWidth; the JSON Schema is updated to match.

Confidence Score: 5/5

Safe to merge — the change is backward-compatible, default behavior is unchanged, and new configuration paths are fully tested.

The new LeftSidebarWidthSettings type is a pure value type with no mutable state; it cleanly replaces inline literals in SessionPersistencePolicy without altering any existing call sites. The configurable floor is correctly threaded through resolvedMinimumSidebarWidth → ContentView.clampedSidebarWidth via an explicit parameter, so the static minimumSidebarWidth = 216 fallback remains correct. Localization covers all app and web locales. The json-path guard, clamp, and schema are consistent with the existing rightMaxWidth pattern. No actor isolation, blocking, or state management concerns introduced.

No files require special attention.

Important Files Changed

Filename	Overview
Packages/macOS/CmuxSettings/Sources/CmuxSettings/Policies/LeftSidebarWidthSettings.swift	New policy struct; cleanly mirrors RightSidebarWidthSettings with static constants plus an instance clampedMinimumWidth method. Sendable value type, no state. Correct nan/infinity guard and clamping logic.
Sources/SessionPersistence.swift	SessionPersistencePolicy constants delegated to LeftSidebarWidthSettings; sanitizedMinimumSidebarWidth now calls clampedMinimumWidth. Behavior-preserving refactor; default/minimum stay 216 pt.
Sources/KeyboardShortcutSettingsFileStore.swift	Adds leftMinWidth parsing in the sidebar JSON section, following the same value > 0 guard + clamp + logInvalid-on-null pattern as rightMaxWidth. Consistent with the schema's exclusiveMinimum: 0.
Packages/macOS/CmuxSettingsUI/Sources/CmuxSettingsUI/Sections/SidebarSection.swift	Adds slider row with value label and Reset button for leftMinWidth, using a clamping Binding and leftMinWidthIsDefault guard. Follows the rightMaxWidth UI pattern. All new strings are localized.
cmuxTests/SidebarWidthPolicyTests.swift	Migrated from XCTest to Swift Testing; adds new tests for left sidebar min-width policy, cmux.json apply/clamp, and ContentView drag-floor. Private expectEqual helper is file-scope private — correct for a test helper.
Resources/Localizable.xcstrings	Adds three new sidebar string keys (label, subtitle, reset, value format) across all 20 app locales. Also reorders existing notification strings (no content change).
web/data/cmux.schema.json	Adds leftMinWidth with type number and exclusiveMinimum: 0, matching the runtime guard; description documents the 100–260 clamp and 216 default.
Sources/CmuxSettingsJSONPathSupport.swift	Adds LeftSidebarWidthSettings.settingsPath to the supported JSON paths set. Clean, no issues.
Packages/macOS/CmuxSettings/Sources/CmuxSettings/Keys/SidebarCatalogSection.swift	Adds leftMinWidth DefaultsKey using LeftSidebarWidthSettings constants. Clean delegation to the new policy type.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["cmux.json\nsidebar.leftMinWidth: 120"] --> B["CmuxSettingsFileStore\nparseSidebarSection"]
    B --> C{"value > 0?"}
    C -- Yes --> D["LeftSidebarWidthSettings().clampedMinimumWidth(value)\n→ clamped to 100–260"]
    C -- No --> E["logInvalid(settingsPath)"]
    D --> F["UserDefaults\nsidebarMinimumWidth = 120"]
    G["Settings UI Slider\n100–260 pt"] --> H["leftMinWidthBinding.set(clampedValue)"]
    H --> F
    F --> I["SessionPersistencePolicy\n.resolvedMinimumSidebarWidth(defaults:)"]
    I --> J["ContentView.clampedSidebarWidth\n(width, max: 600, min: resolved)"]
    J --> K["Sidebar renders at\nconfigured minimum floor"]
    L["LeftSidebarWidthSettings\ndefault=216, range=100…260"] --> B
    L --> G
    L --> I

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A["cmux.json\nsidebar.leftMinWidth: 120"] --> B["CmuxSettingsFileStore\nparseSidebarSection"]
    B --> C{"value > 0?"}
    C -- Yes --> D["LeftSidebarWidthSettings().clampedMinimumWidth(value)\n→ clamped to 100–260"]
    C -- No --> E["logInvalid(settingsPath)"]
    D --> F["UserDefaults\nsidebarMinimumWidth = 120"]
    G["Settings UI Slider\n100–260 pt"] --> H["leftMinWidthBinding.set(clampedValue)"]
    H --> F
    F --> I["SessionPersistencePolicy\n.resolvedMinimumSidebarWidth(defaults:)"]
    I --> J["ContentView.clampedSidebarWidth\n(width, max: 600, min: resolved)"]
    J --> K["Sidebar renders at\nconfigured minimum floor"]
    L["LeftSidebarWidthSettings\ndefault=216, range=100…260"] --> B
    L --> G
    L --> I

Loading

_{Reviews (11): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}

[austinywang]

Thanks @greptile-apps — fixed the schema/parser inconsistency in 8083bc8. The sidebar.leftMinWidth schema now uses exclusiveMinimum: 0 to match the loader's value > 0 guard (mirroring rightMaxWidth), so a schema-aware editor and the runtime agree. Values are still clamped to 100–260 at runtime, which the property description documents.

[greptile-apps]

Thanks for the follow-up — that's the right fix. Using exclusiveMinimum: 0 keeps the schema and runtime guard in sync, and mirroring rightMaxWidth is a good consistency win. The property description documenting the 100–260 clamp covers the remaining gap between what the schema allows and what the runtime enforces. Looks good.

[austinywang]

Addressed the web-docs locale gap in 5d77983: schemaDescriptions.sidebar.leftMinWidth is now translated across all 20 supported web locales (added ar, bs, da, de, es, fr, it, km, ko, no, pl, pt-BR, ru, th, tr, uk, zh-CN, zh-TW), matching the sibling rightMaxWidth coverage and each locale's existing terminology.

[austinywang]

CodeRabbit pre-merge note on web/app/[locale]/components/download-button.tsx: I verified the current branch diff against origin/main does not touch that file (git diff --name-only origin/main...HEAD -- "web/app/[locale]/components/download-button.tsx" is empty). That finding is from merged base/main changes, so there is no branch change to apply for this PR.

[oliver-im]

@austinywang wondering if the PR will be merged, it's a much needed feature!

[teamleaderleo]

Thanks for this, Austin. Your approach is carried forward in #14875 (rebased on current main, with you as co-author), so I'm closing this one in favor of it.