feat(shortcuts): add bindable Pin/Unpin Workspace action

[oyhoyhk]

▎ 🤖 Authored with AI assistance. This change was implemented with Claude (Anthropic) via Claude Code. A human author reviewed it and is responsible for the submission. Commits carry a Co-Authored-By: Claude trailer.

Summary

What changed? Adds a bindable keyboard-shortcut action, Pin or Unpin Focused Workspace, that toggles the pinned state of the currently focused workspace.

Why? The behavior already exists via the workspace context menu and the command palette (TabManager.togglePin), but there was no way to pin/unpin from the keyboard. This exposes it as a first-class, user-customizable shortcut action.

Design notes:

• Ships unbound by default. The natural mnemonic (⌘⇧F) collides with an existing default binding, so instead of forcing a conflicting default, the action ships unbound and users can assign any chord in Settings → Keyboard Shortcuts. This mirrors the precedent set by sendFeedback and the canvas-align actions.
• Implementation mirrors the existing toggleFocusedWorkspaceGroupCollapsed action end-to-end (enum case, group, label, default, routing) to stay consistent with how focused-workspace actions are wired.
• The routing handler returns false (lets the chord propagate) when no workspace is focused, consistent with the group shortcuts' fall-through policy.

Files changed:

• CmuxSettings/ShortcutAction: new togglePinnedWorkspace case + navigation group membership + display label
• CmuxSettings/ShortcutAction+Defaults: unbound default stroke
• KeyboardShortcutSettings.Action: mirrored case, label, and unbound default
• AppDelegate: shortcut routing + handleTogglePinnedWorkspaceShortcut (calls TabManager.togglePin on the focused workspace)
• web/data/cmux.schema.json + web/data/cmux-shortcuts.ts: binding enum entry + shortcuts metadata

Testing

• CmuxSettings package builds cleanly (swift build) and all 251 package tests pass (swift test).
• Full macOS app (Debug) builds cleanly with the change.
• Verified manually: bound the action to ⌘⇧F in Settings → Keyboard Shortcuts, then confirmed it pins and unpins the focused workspace, matching the existing context-menu "Pin Workspace" behavior.

Demo Video

For UI or behavior changes, include a short demo video (GitHub upload, Loom, or other direct link).

• Video URL or attachment:

Review Trigger (Copy/Paste as PR comment)

@codex review
@coderabbitai review
@greptile-apps review
@cubic-dev-ai review

Checklist

• I tested the change locally
• I added or updated tests for behavior changes
• I updated docs/changelog if needed
• I requested bot reviews after my latest commit (copy/paste block above or equivalent)
• All code review bot comments are resolved
• All human review comments are resolved

---

🤖 Generated with Claude Code

---

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

---

Note

Low Risk
Shortcut plumbing only; no new pin logic beyond calling existing togglePin, ships unbound so default behavior is unchanged.

Overview
Adds a new customizable shortcut action Pin or Unpin Focused Workspace so users can toggle pin state from the keyboard; it reuses existing TabManager.togglePin behavior already available from the context menu and command palette.

The action is wired end-to-end like other focused-workspace shortcuts: new togglePinnedWorkspace cases in CmuxSettings and KeyboardShortcutSettings, unbound by default (to avoid default-key collisions such as ⌘⇧F), and AppDelegate routing via handleTogglePinnedWorkspaceShortcut that only consumes the key when a focused workspace exists—otherwise the chord falls through to other bindings.

Web shortcut metadata and cmux.schema.json are updated so the action appears in docs and config validation.

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

---

Summary by cubic

Adds a bindable keyboard shortcut to pin or unpin the focused workspace, reusing the existing TabManager.togglePin behavior.

• New togglePinnedWorkspace action, routed in AppDelegate through the main container to toggle the focused workspace.
• Ships unbound by default to avoid colliding with an existing binding; assign a chord in Settings → Keyboard Shortcuts (e.g., ⌘⇧F).
• The chord only fires when a live focused workspace exists; otherwise it falls through to other bindings, so a stale selection doesn't swallow the key.
• Updated embedded config schema, web shortcuts metadata, skill docs, and localized labels across all 20 locales.

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

Summary by CodeRabbit

• New Features

  • Added a “Pin or Unpin Focused Workspace” shortcut action, available in the context menu and command palette.
  • The action is intentionally shipped unbound by default to avoid shortcut collisions.
  • Added localized label/description (English and Japanese) and enabled configurable bindings in shortcut settings (including chords).

• Bug Fixes

  • Shortcut handling no longer consumes keyboard events when no valid focused workspace/tab is available, allowing other matching shortcuts to trigger.

[vercel]

Someone is attempting to deploy a commit to the Manaflow Team on Vercel.

A member of the Team first needs to authorize it.

[chatgpt-codex-connector]

To use Codex here, create a Codex account and connect to github.

[coderabbitai]

Important

Review skipped

We couldn't safely recover the incremental review. No full review was started, and the last reviewed checkpoint was preserved. Retry later, or explicitly request a full review by commenting @coderabbitai full review.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds the togglePinnedWorkspace shortcut action, keeps it unbound by default, exposes localized configuration metadata, and toggles the focused workspace while preserving fallback shortcut handling.

Changes

Toggle pinned workspace shortcut

Layer / File(s)	Summary
Shortcut action and configuration contracts Packages/macOS/CmuxSettings/Sources/CmuxSettings/Values/*, Sources/KeyboardShortcutSettings.swift, Resources/Localizable.xcstrings, web/data/*	Registers togglePinnedWorkspace, assigns it to navigation, adds localized labels and descriptions, leaves it unbound by default, and permits the binding in the schema.
Focused workspace shortcut handling Sources/AppDelegate.swift	Resolves the focused workspace, toggles its pin state when possible, and allows other shortcut handling to continue when no target is available.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ShortcutEvent
  participant AppDelegate
  participant TabManager
  ShortcutEvent->>AppDelegate: invoke togglePinnedWorkspace
  AppDelegate->>TabManager: resolve focused window and selectedTabId
  TabManager-->>AppDelegate: return selected tab or no target
  AppDelegate->>TabManager: togglePin(tabId:)
  AppDelegate-->>ShortcutEvent: consume event when handled

Loading

Suggested reviewers: lawrencecchen, azooz2003-bit, austinywang

---

Important

Pre-merge checks failed

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

❌ Failed checks (1 error, 1 warning)

Check name	Status	Explanation	Resolution
Cmux Full Internationalization	❌ Error	Swift catalog is fully translated, but the new web shortcut label is only en/ja while routing.ts lists 20 locales and no matching web/messages entry exists for the other 18.	Move the shortcut copy into next-intl/web messages or add translations for every locale in web/i18n/routing.ts, and ensure cmux-shortcuts.ts reads locale-specific strings at runtime.
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 (23 passed)

Check name	Status	Explanation
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.
Cmux Swift Actor Isolation	✅ Passed	AppDelegate and TabManager are @MainActor, and the new helper only calls main-actor TabManager.togglePin; no new Sendable or background UI access was introduced.
Cmux Swift Blocking Runtime	✅ Passed	Added shortcut plumbing only; scans of the modified files found no new semaphores, waits, sleeps, main-queue syncs, or locks.
Cmux Browser Automation Off-Main	✅ Passed	PASS: The diff only adds a workspace-pin shortcut handler and localized string; no browser.* socket commands, worker-router changes, or mainActor waits were touched.
Cmux Expensive Synchronous Load	✅ Passed	The new shortcut path only resolves a TabManager and calls togglePin; it adds no agent-history/session load on the main actor or other interactive path.
Cmux Cache Substitution Correctness	✅ Passed	No persistence/history/snapshot cache substitution here; the new shortcut only routes to live tabManager state and rejects stale selectedTabId before toggling.
Cmux No Hacky Sleeps	✅ Passed	Only TS data/schema changed; no setTimeout/sleep/polling/backoff or fixed waits appear in the diff, so the runtime-no-hacky-sleeps rule isn’t violated.
Cmux Algorithmic Complexity	✅ Passed	The change adds only a single linear existence check before existing linear pin-toggle logic; no nested/batch rescans or hot-path sorting/filtering were introduced.
Cmux Swift Concurrency	✅ Passed	The diff adds only synchronous shortcut routing and metadata; no new DispatchQueue, Combine, completion-handler, or fire-and-forget Task patterns were introduced.
Cmux Swift @Concurrent	✅ Passed	PASS: The diff only adds sync shortcut plumbing and a main-actor routing helper; no new nonisolated async, @concurrent, or heavy async UI calls appear in the changed Swift code.
Cmux Swift File And Package Boundaries	✅ Passed	PASS: The feature is split cleanly—CmuxSettings owns the new shortcut action/defaults, and the app target only adds small AppKit glue; no new oversized-file or package-boundary violation.
Cmux Swiftpm Lockfiles	✅ Passed	Only source/localization/web files changed; no .gitignore, Package.resolved, Package.swift, or xcodeproj dependency refs were touched, so the lockfile rule isn't violated.
Cmux Swift Logging	✅ Passed	Changed hunks only add shortcut routing/metadata; no new print/debugPrint/dump/NSLog/Logger calls appear in the touched files.
Cmux User-Facing Error Privacy	✅ Passed	PASS: The diff only adds shortcut labels/metadata and a fall-through handler; it does not introduce user-facing errors, alerts, command output, or recovery copy with private details.
Cmux Swiftui State Layout	✅ Passed	PR only adds shortcut enum/routing/plumbing and a label string; no new @Observable/``@Published/GeometryReader/lazy-row store refs or render-time state writes.
Cmux Architecture Rethink	✅ Passed	Small bridge fix only: shortcut routes to existing TabManager.togglePin, with fallthrough when no live workspace; no timing, observer, lock, or side-channel patterns added.
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	Diff only adjusts shortcut routing/localization; it adds no NSWindow/NSPanel/WindowGroup or cmuxAuxiliaryWindowIdentifiers changes, so the auxiliary-window rule isn’t triggered.
Cmux Source Artifacts	✅ Passed	All changed paths are intentional source/config/localization files; no logs, build output, scratch dirs, or dependency checkouts were added.
Cmux No Test Or Debug Seam In Production Source	✅ Passed	New code adds a normal shortcut action and handler; no debug*/ForTesting/*TestHook* seam or test-only #if DEBUG accessor was added in production Sources.
Cmux No Ambient Global State	✅ Passed	PASS: The new shortcut logic stays inside AppDelegate and existing enums/extensions; no new file-scope funcs, mutable globals, static-only namespaces, or singletons were added.
Title check	✅ Passed	The title clearly summarizes the main change: adding a bindable Pin/Unpin Workspace action.
Description check	✅ Passed	The description covers the summary, rationale, testing, review trigger, and checklist, with only the demo video section left blank.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR adds a bindable shortcut for pinning or unpinning the focused workspace. The main changes are:

• New shortcut action cases in the Swift settings models.
• AppDelegate routing that calls the existing workspace pin toggle.
• An unbound default shortcut so users can choose their own chord.
• Updated app localization, web shortcut metadata, and config schema.

Confidence Score: 4/5

This is close, but the changed shortcut path still has issues to fix before merging.

• The shortcut can still act on the wrong workspace owner when window context resolution fails.
• The web shortcut description still falls back to English for several supported locales.
• The enum, default, schema, and app string-catalog wiring otherwise look consistent.

Sources/AppDelegate.swift, web/data/cmux-shortcuts.ts

Important Files Changed

Filename	Overview
Sources/AppDelegate.swift	Adds routing for the pin/unpin shortcut, but the handler can still fall back to the wrong tab manager when the target window has no main-window context.
web/data/cmux-shortcuts.ts	Adds web shortcut metadata for the new action, but the new description is not present for every supported web locale.
Resources/Localizable.xcstrings	Adds the Swift string-catalog entry for the new shortcut label across the app catalog locales.
Sources/KeyboardShortcutSettings.swift	Adds the new settings action, localized label, and unbound default.
Packages/macOS/CmuxSettings/Sources/CmuxSettings/Values/ShortcutAction.swift	Adds the new shared shortcut action and display label.
Packages/macOS/CmuxSettings/Sources/CmuxSettings/Values/ShortcutAction+Defaults.swift	Adds the new shared action with no default key stroke.
web/data/cmux.schema.json	Adds the new shortcut action to the config schema enum.

_{Reviews (2): Last reviewed commit: "fix(shortcuts): guard stale pin toggle +..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit a0498f0. Configure here.}

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@Sources/AppDelegate.swift`:
- Around line 14949-14951: Update the shortcut handler containing
tabManager.togglePin(tabId: focusedId) to verify that the selected tab still
exists and the pin mutation succeeds before consuming the shortcut; return false
when the ID is stale or no state change occurs, and true only after an actual
pin mutation.
- Around line 14942-14945: Remove the app-global self.tabManager fallback in
handleTogglePinnedWorkspaceShortcut. Resolve the TabManager exclusively from
contextForMainWindow(targetWindow), using the target window’s structured
context, and return false when that context or manager is unavailable so the
shortcut fails closed.

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

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6cb86e02-040d-4ce8-8114-0375652315de

📥 Commits

Reviewing files that changed from the base of the PR and between 98b86ec and a0498f0.

📒 Files selected for processing (6)

• Packages/macOS/CmuxSettings/Sources/CmuxSettings/Values/ShortcutAction+Defaults.swift
• Packages/macOS/CmuxSettings/Sources/CmuxSettings/Values/ShortcutAction.swift
• Sources/AppDelegate.swift
• Sources/KeyboardShortcutSettings.swift
• web/data/cmux-shortcuts.ts
• web/data/cmux.schema.json

[coderabbitai]

♻️ Duplicate comments (1)

Sources/AppDelegate.swift (1)

14943-14945: ⚠️ Potential issue | 🟠 Major

Do not fall back to the app-global self.tabManager for a missing window context.

When the shortcut originates from a non-main window, contextForMainWindow(targetWindow) can be nil, causing this fallback to toggle whichever workspace is selected in self.tabManager rather than the workspace associated with the focused window. Resolve through the target window’s structured context and fail closed when unavailable. As per path instructions, correctness-critical shortcut handling and workspace state resolution must use a single authoritative source of truth and any degraded branches must fail closed (disable/no-op) rather than relying on an unreliable fallback branch.

🐛 Proposed fix

-        let targetWindow = preferredWindow ?? shortcutRoutingActiveWindow
-        let resolvedTabManager: TabManager? = contextForMainWindow(targetWindow)?.tabManager ?? self.tabManager
-        guard let tabManager = resolvedTabManager else { return false }
+        let targetWindow = preferredWindow ?? shortcutRoutingActiveWindow
+        guard let tabManager = contextForMainWindow(targetWindow)?.tabManager else {
+            return false
+        }

🤖 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 `@Sources/AppDelegate.swift` around lines 14943 - 14945, Update the
resolvedTabManager logic in the shortcut-handling path to remove the app-global
self.tabManager fallback. Resolve the manager exclusively from targetWindow’s
structured context, and return false when that context or its tabManager is
unavailable so shortcut handling fails closed.

Source: Path instructions

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

Duplicate comments:
In `@Sources/AppDelegate.swift`:
- Around line 14943-14945: Update the resolvedTabManager logic in the
shortcut-handling path to remove the app-global self.tabManager fallback.
Resolve the manager exclusively from targetWindow’s structured context, and
return false when that context or its tabManager is unavailable so shortcut
handling fails closed.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: e3c16f8b-a736-4903-b6d5-44f712eaf106

📥 Commits

Reviewing files that changed from the base of the PR and between a0498f0 and dde656f.

📒 Files selected for processing (2)

• Resources/Localizable.xcstrings
• Sources/AppDelegate.swift

[oyhoyhk]

@lawrencecchen — when you have a moment, would you be open to taking a look at this? No rush at all.

For context, it mirrors your toggleFocusedWorkspaceGroupCollapsed action end-to-end (enum case, navigation group, label, default, routing) so it stays consistent with how the other focused-workspace shortcuts are wired, and it ships unbound by default to avoid clobbering an existing keybinding.

I've worked through the automated review feedback:

• Added a guard so the shortcut only consumes the chord when the selected id is a live workspace, so a no-op togglePin no longer swallows the key (dde656f).
• Added the missing shortcut.togglePinnedWorkspace.label across all 20 locales in Localizable.xcstrings.
• Left the contextForMainWindow(...) ?? self.tabManager routing fallback as-is, since the sibling handlers (handleToggleFocusedWorkspaceGroupCollapsedShortcut, createEmptyWorkspaceGroup) use the identical pattern — making only this one fail-closed would be inconsistent. CodeRabbit raised the same point and withdrew it.
• Kept the web cmux-shortcuts.ts entry as en+ja, matching the other 98 of 101 entries (only 3 note-heavy entries are fully localized).

Happy to adjust anything if you'd prefer a different approach. Thanks for building cmux!

[teamleaderleo]

This remains wanted, and current main needs a small shortcut-file refresh. Before we re-land your change, please comment exactly I have read the CLA Document v2.2 and I hereby sign the CLA so the CLA check can pass :)

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[oyhoyhk]

I have read the CLA Document v2.2 and I hereby sign the CLA

[oyhoyhk]

recheck

[teamleaderleo]

Taking this: refreshing the unbound Pin/Unpin Workspace shortcut for current main and checking all binding entrypoints.

• OrchardSpoon g1 🌀

[teamleaderleo]

Thanks @oyhoyhk, I updated this with main and kept the new action in the current split shortcut files :) I also regenerated the native config schema and reused your catalog translations for all 20 web locales. The shortcut stays unbound by default and uses the existing pin action. Independent review, schema/catalog checks, web lint, and test wiring passed. Native CI and shortcut dogfood are still pending.

• OrchardSpoon g1 🌀

[github-actions]

CI failure attribution

CI failed on 89b7647cf0 (run 36987754870 attempt 2): 1 code.

Job	Verdict	Why
macos / macOS compile admission	code	a compile error

Matched log lines

macos / macOS compile admission: /tmp/cmux-ci/src/cmuxTests/CodexForkMonitorArgumentTests.swift:13:33: error: type 'CMUXCLI' (aka 'CmuxTuiRemoteRouting') has no member 'codexForkMonitorArguments'

Not re-run automatically: macos / macOS compile admission is not a machine failure.

Written by scripts/ci/classify_failures.py (ci-failure-attribution.yml); signatures are its SIGNATURES table. A machine verdict is the runner's fault, not this PR's.

[teamleaderleo]

I fixed the shortcut-action reference omission caught by CI. shortcuts.bindings.togglePinnedWorkspace is now listed, and the supported-path checks pass all eight tests. The app code is unchanged; current-head CI and dogfood are still pending.

• OrchardSpoon g1 🌀