Fix #3511: discover cmux user themes

[austinywang]

Summary

• Fixes the user-theme discovery gap from Light theme renders white text on white background — foreground/palette config has no effect #3511 by adding ~/Library/Application Support/com.cmuxterm.app/themes/<name> to runtime theme resolution.
• Adds the same cmux app-support themes directory to cmux themes list / cmux themes set discovery.
• Adds regression coverage for both the runtime search path and CLI theme listing.

Reproduction

• Created a temporary theme file at ~/Library/Application Support/com.cmuxterm.app/themes/CmuxIssue3511LocalRepro.
• Ran /Applications/cmux.app/Contents/Resources/bin/cmux themes list; the temporary theme was absent.
• Ran /Applications/cmux.app/Contents/Resources/bin/cmux themes set CmuxIssue3511LocalRepro; observed Unknown theme.
• Expected the theme to be listed and accepted because the issue documents that directory as the user-theme location.

Note: the white-on-white live-surface foreground refresh path described in #3511 was already addressed on current main by PR #3852; this PR covers the remaining reproducible user-theme directory failure.

Testing

• Not run locally per repository/task instruction. CI will run the regression.

Closes #3511

---

Note

Low Risk
Low risk: extends theme/config search paths to include cmux-specific Application Support locations (including CFFIXED_USER_HOME) and adds tests; main risk is unintended path precedence/duplication affecting which theme/config is selected.

Overview
Fixes theme discovery so user themes under ~/Library/Application Support/com.cmuxterm.app/themes (and equivalent paths when CFFIXED_USER_HOME is set) are found by both runtime theme resolution and cmux themes CLI commands.

Introduces CmuxApplicationSupportDirectories.userDirectories to centralize and de-duplicate Application Support roots, updates CLI config/theme search to use it, and adds regression tests (including an integration-style CLI JSON themes list check).

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

---

Summary by cubic

Make cmux discover user themes in ~/Library/Application Support/com.cmuxterm.app/themes at runtime and via the CLI, including when CFFIXED_USER_HOME is set. Fixes #3511 so these themes appear in cmux themes list and can be applied with cmux themes set.

• Bug Fixes
  • Centralized Application Support root resolution via CmuxApplicationSupportDirectories.userDirectories (user domain, CFFIXED_USER_HOME, and ~) with standardized de-dup; used by GhosttyConfig.themeSearchPaths and the CLI.
  • CLI config lookup now uses this helper to scan com.mitchellh.ghostty and com.cmuxterm.app for config/config.ghostty, with de-duplication.
  • Added tests for fixed-home and user-domain paths, plus a CLI JSON test that verifies discovery, current theme, and source_path; includes a bundled CLI runner with a timeout for stability.

^{Written for commit 0f1ba75. Summary will update on new commits. Review in cubic}

Summary by CodeRabbit

• New Features

  • Enhanced theme discovery to include additional per-user Application Support locations (including support for an environment-overridden home directory) so custom themes in those paths are automatically found.

• Tests

  • Added tests validating theme discovery (including a CLI-based test using an env override) and test utilities to run the bundled CLI and enforce timeouts.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
cmux	Ready	Preview, Comment	May 18, 2026 8:11am
cmux-staging	Building	Preview, Comment	May 18, 2026 8:11am

[coderabbitai]

📝 Walkthrough

Walkthrough

CLI and GhosttyConfig now include com.cmuxterm.app per-user Application Support theme paths: CLI enumerates application-support roots via a new helper and GhosttyConfig adds the .../com.cmuxterm.app/themes/<theme> lookup; tests validate static path inclusion and dynamic discovery via CFFIXED_USER_HOME.

Changes

User Theme Directory Support

Layer / File(s)	Summary
Theme search path configuration CLI/CMUXCLI+ThemeSupport.swift, Sources/GhosttyConfig.swift	CLI's themeDirectoryURLs() now iterates per-user Application Support roots (userApplicationSupportDirectories(environment:)) and conditionally adds <root>/com.cmuxterm.app/themes; GhosttyConfig.themeSearchPaths adds ~/Library/Application Support/com.cmuxterm.app/themes/<themeName>.
Theme discovery test coverage cmuxTests/GhosttyConfigTests.swift	Adds testThemeSearchPathsIncludeCmuxUserThemesDirectory and testThemesListIncludesCmuxUserThemesDirectory (creates a CFFIXED_USER_HOME temp themes dir and runs bundled cmux to assert discovery). Also adds CLIResult, bundledCLIPath(), and runCLI(...) test helpers.

Sequence Diagram(s)

sequenceDiagram
  participant TestRunner
  participant CMUXCLI
  participant FileManager
  participant GhosttyConfig
  TestRunner->>CMUXCLI: run `cmux themes list --json` (env overrides)
  CMUXCLI->>FileManager: userApplicationSupportDirectories(environment:)
  FileManager-->>CMUXCLI: application support root URLs (including CFFIXED_USER_HOME)
  CMUXCLI->>GhosttyConfig: request themeSearchPaths(forThemeName:...)
  GhosttyConfig-->>CMUXCLI: returns search paths (includes com.cmuxterm.app path)
  CMUXCLI-->>TestRunner: JSON theme list output

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• manaflow-ai/cmux#3123: Modifies GhosttyConfig theme discovery logic related to theme search paths.
• manaflow-ai/cmux#830: Also adds macOS Application Support (com.cmuxterm.app) lookups for Ghostty theme/config discovery.
• manaflow-ai/cmux#3226: Updates CLI/config theme discovery behavior including Application Support locations.

Poem

🐰 I hopped through Application Support's glen,
I found a Zag file tucked like a gem,
I nudged the paths so themes are seen,
Now user colors join the screen. ✨

🚥 Pre-merge checks | ✅ 14 | ❌ 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 (14 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Fix #3511: discover cmux user themes' directly addresses the primary change—enabling discovery of user themes in the cmux Application Support directory, which is the main objective of this PR.
Linked Issues check	✅ Passed	The PR addresses the coding objective from #3511: ensuring user themes in ~/Library/Application Support/com.cmuxterm.app/themes are discoverable by cmux themes list and cmux themes set. Runtime and CLI discovery paths updated with regression tests; related renderer fixes already addressed by #3852.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to theme discovery: adding cmux app-support themes path to runtime resolution, extending CLI discovery with robust Application Support enumeration, and adding targeted regression tests. No unrelated modifications present.
Cmux Swift Actor Isolation	✅ Passed	New pure helper methods use only local value types with no shared mutable state or implicit MainActor isolation issues. No actor isolation debt introduced or worsened.
Cmux Swift Blocking Runtime	✅ Passed	No blocking primitives in production code. DispatchSemaphore is only in test-only scaffolding for process execution, which is allowed.
Cmux No Hacky Sleeps	✅ Passed	PR contains only Swift files. The check scopes to TypeScript, JavaScript, shell, and non-Swift scripts. Swift is explicitly out of scope per the policy (covered by swift-blocking-runtime.md).
Cmux Swift Concurrency	✅ Passed	PR adds no legacy async patterns to production code. Test-only DispatchQueue usage is explicitly allowed for test synchronization.
Cmux Swift @Concurrent	✅ Passed	All changes are synchronous code. No async/await declarations found. The @concurrent check applies only to async functions, which are not present in this PR.
Cmux Swift File And Package Boundaries	✅ Passed	CMUXCLI+ThemeSupport (389 lines, focused theme support), GhosttyConfig (+1 line, 760 total), test additions are all appropriate. No mixing of concerns or package extraction needed.
Cmux Swift Logging	✅ Passed	No logging violations found. Production code contains no print, debugPrint, dump, NSLog, or ad hoc logging. Changes are file I/O and theme discovery only.
Cmux Swiftui State Layout	✅ Passed	PR contains no SwiftUI state modifications. Changes are limited to CLI utilities, a data model struct, and test code—none of which introduce or violate SwiftUI state patterns.
Cmux Architecture Rethink	✅ Passed	Adds theme discovery helper with clear ownership. No problematic timing, observers, or state holders. Test synchronization is test-only. Complies with all rules.
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	PR adds theme discovery and search paths only. No NSWindow, NSPanel, NSWindowController, SwiftUI Window, or WindowGroup instantiation. Not applicable to this check.
Description check	✅ Passed	PR description comprehensively covers changes, testing approach, and references the related issue (#3511). It includes reproduction steps, testing notes, and acknowledges related fixes already merged.

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

✨ 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-3511-light-theme-white-on-white

---

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

[greptile-apps]

Greptile Summary

Fixes the user-theme discovery gap from #3511 by adding ~/Library/Application Support/com.cmuxterm.app/themes to both runtime theme resolution (GhosttyConfig.themeSearchPaths) and CLI theme listing/setting (themeDirectoryURLs, themeConfigSearchURLs). A new CmuxApplicationSupportDirectories.userDirectories helper centralises Application Support root resolution—covering the FileManager user-domain result, CFFIXED_USER_HOME, and the tilde-based fallback—with path de-duplication throughout.

• CmuxApplicationSupportDirectories.swift: New namespace enum that returns up to three de-duplicated Application Support roots: the FileManager user-domain result, the CFFIXED_USER_HOME-derived path (when set), and ~/Library/Application Support as a tilde-based fallback (de-duped with the first on unsandboxed systems).
• GhosttyConfig.swift + CMUXCLI+ThemeSupport.swift: Both callers loop over the shared helper's result and append com.cmuxterm.app/themes/<name> (or the full config sub-paths) for each root, replacing the old single-if let pattern with a uniform multi-root loop.
• cmuxTests/GhosttyConfigTests.swift: Adds unit tests for the fixed-home search path and a subprocess-based CLI integration test that verifies themes list and source_path using CFFIXED_USER_HOME.

Confidence Score: 5/5

Safe to merge — the change only expands theme and config search paths and cannot remove or overwrite existing discovered paths.

The change is strictly additive: CmuxApplicationSupportDirectories.userDirectories returns one path on a standard unsandboxed system (same path the old code used) and at most two distinct paths when CFFIXED_USER_HOME is set. Both constants used across the two callsites resolve to the same "com.cmuxterm.app" string, so runtime and CLI resolution stay in sync. The de-duplication logic is sound, the fallback for a missing FileManager result is preserved via the tilde-based third entry, and the write path is intentionally left unchanged. No production logging, actor isolation, or concurrency primitives were introduced.

No files require special attention.

Important Files Changed

Filename	Overview
Sources/CmuxApplicationSupportDirectories.swift	New namespace enum centralising Application Support root resolution; correctly handles FileManager, CFFIXED_USER_HOME, and tilde-fallback with path de-duplication. No actor isolation or logging issues.
Sources/GhosttyConfig.swift	Adds cmux app-support theme paths to themeSearchPaths by looping over userDirectories; uses the correct CmuxGhosttyConfigPathResolver.releaseBundleIdentifier ("com.cmuxterm.app"), consistent with CLI caller.
CLI/CMUXCLI+ThemeSupport.swift	themeDirectoryURLs and themeConfigSearchURLs updated to use shared helper with de-duplication; removes old if-else fallback, behaviour is preserved for all known cases.
cmuxTests/GhosttyConfigTests.swift	Adds unit tests for fixed-home path injection and a subprocess CLI integration test; uses DispatchSemaphore for timeout — test-only scaffolding, explicitly permitted by the blocking-runtime rule.
cmux.xcodeproj/project.pbxproj	Registers CmuxApplicationSupportDirectories.swift in both the app and CLI targets; PBX UUID format is consistent with the rest of the project.

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

[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 5040dc9. Configure here.}