# PROJECTS

Cross-project tracking (features, bugs, backlog) for cmux.

## Done
- 2026-02-14: Fixed updater release regression path: made `.github/workflows/release.yml` Sparkle Info.plist key injection idempotent (re-running tags no longer fails with "Entry Already Exists"), and hardened `scripts/bump-version.sh` to keep `CURRENT_PROJECT_VERSION` above the latest published Sparkle appcast build number so upgrades from `0.27.0` can be detected.
- 2026-02-14: Relicensed the repository to strong copyleft (`AGPL-3.0-or-later`), added canonical `LICENSE` text, and updated project/package metadata to advertise AGPL consistently.
- 2026-02-14: Added an opt-in nightly update channel in Settings (`Receive nightly builds`) that routes Sparkle feed selection between stable and nightly appcasts, plus a scheduled GitHub Actions nightly pipeline (`.github/workflows/nightly.yml`) that only rebuilds when `main` has new commits since `nightly` (or when manually forced).
- 2026-02-13: Added `demos/wkwebview-ssh-proxy-cookie-demo/` with a standalone macOS Swift app (two WKWebViews), two Docker backends (`:8080`) running behind separate SSH SOCKS tunnels, and scripts/docs to demonstrate same URL (`shared.test:8080`) routing to different backends plus app-level cookie sync between separate proxy-scoped data stores.
- 2026-02-13: Expanded skill docs for end users: added deep-linkable `cmux-browser` references (`authentication.md`, `session-management.md`, `snapshot-refs.md`, `video-recording.md`, `proxy-support.md`) + templates, and added a new `skills/cmux/` core skill for windows/workspaces/panes/surfaces workflows.
- 2026-02-13: Changed CLI ID formatting defaults to refs-first for `--json` output (UUID output now opt-in via `--id-format uuids|both`) and added regression test `tests_v2/test_cli_id_format_defaults.py`.
- 2026-02-13: Added new repo skill `skills/cmux-browser/` adapted from `vercel-labs/agent-browser` with cmux CLI syntax, wait/snapshot/ref workflow guidance, common automation flows, and command mapping references.
- 2026-02-13: Kept browser favicons in color when a pane/tab bar is unfocused by excluding raster tab icons from inactive saturation in Bonsplit tab rendering. Added regression coverage in `vendor/bonsplit/Tests/BonsplitTests/BonsplitTests.swift`.
- 2026-02-13: Browser agent-UX follow-up: `browser fill` now accepts empty text for clear operations, legacy `new-pane`/`new-surface` output now prefers short `surface:N` refs, and mutating browser actions gained optional post-action verification snapshots via `snapshot_after` (`--snapshot-after` in CLI). Added regression coverage in `tests_v2/test_browser_api_comprehensive.py` and `tests_v2/test_browser_cli_agent_port.py`.
- 2026-02-13: Final titlebar hint vertical micro-adjustment: moved `Cmd+B`/`Cmd+I`/`Cmd+N` pills up by 1px for pixel-level alignment.
- 2026-02-13: Nudged titlebar shortcut hint pills an additional 4px left and 4px down (`Cmd+B`, `Cmd+I`, `Cmd+N`) for tighter visual alignment.
- 2026-02-13: Adjusted titlebar command hint pills (`Cmd+B`, `Cmd+I`, `Cmd+N`) to render 4px further left and slightly smaller text for better alignment with controls.
- 2026-02-13: Fixed production updater diagnostics by enabling `UpdateLogStore` writes in non-Debug builds, so `Copy Update Logs` contains real update check/download/error activity for release users.
- 2026-02-13: Fixed missing Bonsplit pane shortcut-pill fade by removing tab-strip-wide `disablesAnimations` transaction (which suppressed hint animations) and switching hint/close accessory rendering to an explicit opacity crossfade tied to `showsShortcutHint`.
- 2026-02-13: Restored explicit fade-in and fade-out animation for Bonsplit pane Ctrl/Cmd shortcut hint pills using `.easeInOut(duration: 0.14)` on visibility transitions so hold/release both animate reliably.
- 2026-02-13: Aligned Bonsplit pane shortcut-hint animation timing/easing with command-hold hints by removing separate monitor-side ease-in/ease-out durations and using the shared view-level `.easeInOut(duration: 0.14)` transition path.
- 2026-02-13: Sidebar drag/drop indicator now canonicalizes to a single insertion boundary between workspace rows (no dual top/bottom targets for the same gap), and the drop line is rendered as one centered divider in the inter-row spacing.
- 2026-02-13: Added smooth fade-in/fade-out animation for Bonsplit pane `Ctrl+1..9` shortcut hints by animating monitor visibility transitions (intentional hold reveal + release hide).
- 2026-02-12: Completed browser parity migration for v2 CLI/socket; added extended browser command families and explicit not_supported mapping for WKWebView/CDP gaps; added/ported v2 tests (test_browser_api_extended_families.py, test_browser_api_unsupported_matrix.py, test_browser_cli_agent_port.py); aligned v2 visual D12 VIEW_DETACHED as non-blocking like v1; reran full VM suites run-tests-v1.sh and run-tests-v2.sh passing.
- 2026-02-12: Fixed empty notifications popover keyboard leakage: when the `Show Notifications` popover is open with no notifications, plain typing no longer passes through to the focused terminal. Added UI regression coverage (`testEmptyNotificationsPopoverBlocksTerminalTyping`).
- 2026-02-12: Menu-bar notification rows (main `Notifications` menu + Menu Bar Extra inline rows) now clamp to a max text width, wrap, and truncate to 3 lines with an ellipsis. Implemented via shared `MenuBarNotificationLineFormatter` layout logic so both surfaces stay in sync, with unit regression coverage for wrapped truncation and short-text preservation.
- 2026-02-12: Notifications shortcut UX fix: `Cmd+I` now reliably toggles the notifications popover closed when already open (including while the popover panel is visible), and `Escape` now dismisses an open notifications popover. Added VM UI regression coverage (`testNotificationsPopoverCanCloseViaShortcutAndEscape`).
- 2026-02-12: Shortcut-hint follow-up: pane tab hints now always display `Ctrl+1..9` labels (even when revealed by Command-hold), and titlebar hint positioning now applies a rightward safety shift to prevent left-edge clipping near the traffic-light area (e.g. `Cmd+B`). Added a UI regression assertion that the sidebar titlebar hint stays at or to the right of the sidebar icon lane.
- 2026-02-12: Fixed titlebar shortcut-hint layout shift by keeping all titlebar hint pills on one Y row and resolving collisions horizontally, added accessibility identifiers for titlebar controls/hints, and added VM UI regression coverage (`TitlebarShortcutHintsUITests`) asserting aligned Y + no control-frame shift when hints are always shown.
- 2026-02-12: Added a top-level macOS menu bar `Notifications` menu (main app menu, not the status-item extra) with parity actions/inline recent notification rows (show, jump latest unread, mark all read, clear all, open row). Extracted shared notification menu snapshot logic so both the main menu and menu bar extra reuse the same unread counting/state text/recent-item selection behavior, and added unit regression coverage.
- 2026-02-12: Shortcut-hint visibility pass: added collision-aware lane layout for titlebar shortcut pills to prevent overlap, unified stronger blur-backed pill styling across sidebar/titlebar/pane hints, and moved pane `Ctrl/Cmd+1..9` hints into a centered trailing slot aligned with tab close affordances/text. Added unit regression coverage for lane assignment logic.
- 2026-02-12: Fixed terminal file/image drop regression in cmux by restoring AppKit drag destination handling on `GhosttyNSView` (register drop types + perform drop insertion), and added `tests/test_file_drop_paths.py` e2e regression coverage via debug socket `simulate_file_drop` to verify dropped paths are inserted shell-escaped.
- 2026-02-12: Sidebar drag behavior polish: edge auto-scroll now continues when pointer leaves the scroll area/window vertically during drag, and added a top sidebar blur scrim under traffic lights/titlebar controls to prevent scrolled workspace rows from visually bleeding behind the controls.
- 2026-02-12: Sidebar drag auto-scroll follow-up: improved edge scrolling when cursor leaves row drop targets by keeping drag-scroll active outside rows, allowing bounded out-of-viewport scrolling, and consulting AppKit `autoscroll(with:)` behavior for drag events.
- 2026-02-12: Moved titlebar shortcut hints (sidebar/bell/plus) downward so pills render below the icon buttons, with a small style-aware base Y offset plus existing debug offset tuning.
- 2026-02-12: Fixed titlebar shortcut hint clipping on the rightmost control (e.g. `Cmd+N`) by reserving trailing inset based on titlebar hint X offset, so the pill is no longer cut off.
- 2026-02-12: Improved sidebar workspace drag/reorder UX for long lists: drop edge now follows cursor position within the hovered row (top vs bottom half), added auto-scroll while dragging near the top/bottom viewport edges, and kept no-op edge indicator suppression intact. Added unit regression coverage for pointer-edge planning and auto-scroll planning.
- 2026-02-12: Expanded `Debug Window Controls` with full shortcut-hints debug controls (always-show toggle, sidebar/titlebar/pane X/Y offsets, reset hints, and copy hint payload) so hint tuning is available directly in the debug windows hub.
- 2026-02-12: Added `Always show shortcut hints` checkbox in Sidebar Debug (global across sidebar/titlebar/pane hints), with persistence in copyable debug payloads and snapshot script output.
- 2026-02-12: Exposed the global "Always show shortcut hints" toggle directly in the Debug menu and Debug Window Controls window for easier access.
- 2026-02-12: Sidebar workspace drag/drop indicator now suppresses no-op edge placements (no blue border for first-before-first, last-after-last, self-drop, or single-workspace cases). Added unit regression tests for drop-indicator planning edge cases.
- 2026-02-12: Added debug-tunable X/Y offsets for keyboard shortcut hint badges across sidebar workspace hints (`Cmd+1..9`), titlebar control hints (sidebar/bell/plus shortcut labels), and Bonsplit pane tab hints (`Ctrl/Cmd+1..9`). Exposed these in `Sidebar Debug` with reset/copy support, and included the new fields in combined debug snapshot output.
- 2026-02-12: Added sidebar workspace reordering via drag-and-drop, including accessibility reorder actions (`Move Up` / `Move Down`) and context-menu move actions for keyboard/AX users. Added unit regression coverage for `TabManager.reorderWorkspace`, and tuned sidebar workspace title typography to semibold `12.5`pt.
- 2026-02-12: Added a grouped `Debug > Debug Windows` menu in the app (Sidebar, Background, Menu Bar Extra, plus `Open All Debug Windows`) and created a repo-local `cmux-debug-windows` skill with a helper snapshot script (`skills/cmux-debug-windows/scripts/debug_windows_snapshot.sh`) for combined copyable debug settings payloads.
- 2026-02-12: Expanded shortcut hint overlays: Command-hold hints now wait longer before showing and include titlebar controls using current user-configured shortcuts (Toggle Sidebar, Show Notifications, New Workspace). Added focused-pane Bonsplit tab hints for `Ctrl+1..9` (with `9` mapped to the last tab) using intentional Control-only hold behavior.
- 2026-02-12: Refined sidebar `Cmd+digit` hint UX: hint badge now renders on the close-button Y level without row layout shift, and hints only appear after an intentional Command-only hold (short delay + canceled when any non-modifier key is pressed). Added unit regression coverage for the Command-only hint policy.
- 2026-02-12: Added a `New workspace placement` preference (`Top`, `After current`, `End`) in Settings, defaulting to `After current` for fresh installs. Workspace creation now follows this setting across app/menu/shortcut/service/socket entry points, and unit regression tests cover default preference + insertion-index behavior.
- 2026-02-12: Fixed a check-for-updates regression where the first manual check could run before Sparkle was ready (so `Checking for Updates…` / `No Updates Available` never appeared). `UpdateController` now waits for readiness before issuing the check, and `UpdatePillUITests` adds sidebar regression coverage for loading + no-update states.
- 2026-02-12: Sidebar now shows `Cmd+digit` badges on workspace rows while the Command key is held, and workspace shortcut routing is unified so `Cmd+9` always targets the last workspace (with unit regression coverage for the mapping).
- 2026-02-12: Moved the update pill/button and `THIS IS A DEV BUILD` indicator from the titlebar into a bottom-left footer inside the sidebar (debug builds), so update/dev status lives with sidebar UI instead of titlebar accessories.
- 2026-02-12: Sidebar update control now uses the update pill in debug builds (non-idle update states only), and the checking spinner matches the browser tab loading spinner style.
- 2026-02-12: Added macOS Finder/Services “here” integrations for cmux: `New … Workspace Here` (maps to `openTab`) and `New … Window Here` (maps to `openWindow`), with path dedupe/normalization and explicit working-directory routing for both new windows and new workspaces. Added unit regression tests for service path resolution.
- 2026-02-12: Menu bar extra now includes a `Quit cmux` action, and menu bar badge tuning defaults were updated to the latest shared payload values (with backward-compatible support for legacy `menubarDebugTextRectXAdjust`).
- 2026-02-12: Added a Debug menu window for menu bar extra tuning (preview unread count override, live badge position/size controls, and one-click copy payload for sharing exact values).
- 2026-02-12: Expanded menu bar extra debug controls with separate 2-digit X/Y positioning so single-digit and two-digit badge text can be tuned independently.
- 2026-02-12: Refined menu bar extra UX: inserted a separator between inline notification rows and action items, and adjusted the unread count glyph in the status icon (bigger, higher, slightly left) while keeping the white cmux icon and fixed-width layout.
- 2026-02-12: Menu bar extra now shows a dev-only build hint line (`Build Tag: <tag>` for tagged reloads, `Build: DEV (untagged)` otherwise) so parallel `cmux DEV` instances are distinguishable from the menu.
- 2026-02-12: Added a right-side menu bar extra with a dynamic unread badge on the icon plus quick actions for notifications (show/jump/mark-read/clear), check for updates, and preferences.
- 2026-02-12: Added unread notification count badges on the app icon (Dock/Cmd+Tab) with a new Settings toggle to disable it; added unit regression coverage for badge labeling and default preference behavior.
- 2026-02-12: Fixed browser-pane split shortcuts so `Cmd+D` and `Cmd+Shift+D` work from both `WKWebView` and the browser omnibar by adding menu-backed split commands wired to effective shortcut settings and shared split handling in `AppDelegate`. Added VM UI regression coverage in `BrowserPaneNavigationKeybindUITests` for both focus states.
- 2026-02-12: Fixed browser omnibar click focus routing so clicking the omnibar re-focuses the browser pane/surface (instead of leaving focus on the previous pane). Added VM UI regression coverage in `BrowserPaneNavigationKeybindUITests` (`testClickingOmnibarFocusesBrowserPane`).
- 2026-02-12: Updated `Cmd+L` behavior to be context-aware: when focused panel is browser it focuses omnibar (existing behavior), and when focused panel is terminal/non-browser it opens a browser in the focused pane then focuses omnibar. Added VM UI regression coverage (`testCmdLOpensBrowserWhenTerminalFocused`).
- 2026-02-12: Split-close rendering follow-up: coalesced post-topology terminal geometry reconciliation in `Workspace` (close/split/geometry events) and hardened split-close visual test setup readiness in `TabManager` to avoid false setup failures. Re-verified VM UI regressions for right-column/bottom-row split close and full `CloseWorkspaceCmdDUITests` suite.
- 2026-02-08: Stabilized nested splits (no more "existing split disappears" during nested L/R splits) and added regression tests.
- 2026-02-08: Fixed "frozen" terminal panes/tabs (input not visible until Enter/unfocus) and added visual typing + HTML report tooling.
- 2026-02-08: Removed bonsplit tab content crossfade + selection animation to reduce flashes/blanking during pane/tab changes.
- 2026-02-09: Show unread notification badge as a blue dot in bonsplit tabs.
- 2026-02-09: Multi-window support (Cmd+Shift+N) with per-window workspaces; notifications, notification popover, and Cmd+Shift+U route to the correct window; added UI test coverage.
- 2026-02-09: Cmd+Shift+W now labeled "Close Workspace" and confirmation dialog text uses "workspace" (not "tab"); added UI test coverage and de-flaked multi-window notification UI-test setup timing.
- 2026-02-09: Cmd+D now confirms the close confirmation dialog and closes the window when closing the last workspace.
- 2026-02-09: Suppressed Sparkle "Check for updates automatically?" permission prompt (rely on update pill only); added UI test coverage.
- 2026-02-09: Cmd+W close now uses "Close Tab" semantics (closes the focused tab; if it is the last tab, closes the workspace/window) and supports Cmd+D confirm when it would close the window; added UI test coverage.
- 2026-02-09: Ctrl+D shell exit no longer "recreates" a terminal when the last tab closes; it closes the workspace/window instead.
- 2026-02-09: Fixed dragging tabs moving the whole window by dynamically padding content below the actual titlebar height.
- 2026-02-09: Cmd+N now opens a new window when no windows are open; otherwise it creates a new workspace. Updated titlebar tooltip text to "New workspace" and added a UI test for the no-windows Cmd+N behavior.
- 2026-02-09: Fixed `./scripts/reload.sh` single-instance safety check on macOS (use `ps etime` parsing instead of GNU-only `etimes`).
- 2026-02-09: Fixed Cmd+W close panel confirmation path not closing when a running-process dialog appears (bypass Bonsplit delegate gating after user confirms).
- 2026-02-09: Fixed WKWebView consuming app menu shortcuts (e.g. Cmd+N/Cmd+W, tab switching) by routing key equivalents through the main menu first; added unit tests and UI-test coverage scaffolding.
- 2026-02-09: Centralized customizable shortcut definitions and wired titlebar button tooltips to show effective shortcuts.
- 2026-02-09: Regression: 2x2 split then close both right panels can leave the remaining top pane blank/frozen (no visual updates until focus changes). Fix: reassert Ghostty display ID after focusing to restart stuck CVDisplayLink; added screenshot-based UI regression test.
- 2026-02-10: Follow-up: closing both right splits could still produce a single transient "one frame blank" flash during relayout. Fix: ensure Bonsplit never renders an empty content view when tabs exist (fallback tab when `selectedTabId` is transiently nil), and remove synchronous `ghostty_surface_draw` / post-close refresh polling that caused rendering artifacts. UI test now captures a vsync-aligned screenshot timeline and asserts no post-close frame goes visually blank.
- 2026-02-10: Sidebar workspace close keeps focused index stable when possible (prefer focusing the next workspace, not the one above).
- 2026-02-10: Closing Bonsplit tabs keeps focused index stable when possible (prefer focusing the next tab, not the one above).
- 2026-02-10: Expanded bonsplit tab bar drop target so cross-pane tab drops work anywhere in the tab bar (including empty trailing space).
- 2026-02-10: bonsplit tab drag/drop: suppress no-op "drop to the right of itself" indicator (e.g. last tab dragged right) and avoid no-op move churn; added unit test coverage.
- 2026-02-10: bonsplit tab bar: fixed fade overlays appearing before the tab strip uses available width (tab strip now occupies full width up to split buttons; removed fade overlay animations).
- 2026-02-10: Browser address bar search now uses a configurable default search engine (Google, DuckDuckGo, Bing) and shows an omnibar dropdown (history + optional remote suggestions); added unit + UI tests (alignment, Ctrl+N/P). Also added Cmd+R reload and default Safari UA to avoid Google fallback/bot checks.
- 2026-02-10: Browser loading UI: removed omnibar progress indicator and replaced it with a spinning tab icon while the page is loading.
- 2026-02-10: Browser omnibar: added an explicit state machine (focus/editing/popup) so Escape and click-outside behaviors match Chrome; added regression tests.
- 2026-02-10: Added a customizable “Flash focused panel” keyboard shortcut (default Cmd+Shift+L) that visually highlights the currently focused terminal or browser panel.
- 2026-02-10: Added PostHog Swift SDK integration and a stable DAU signal (`cmux_daily_active`, once per UTC day per install).
- 2026-02-10: Added a v2 JSON socket API (handle-based) and migrated the automated test suite to v2 while keeping v1 compatibility. Verified v1 + v2 suites passing on the VM (see `docs/v2-api-migration.md`).
- 2026-02-11: Extended the socket/CLI to handle multi-window automation: added v2 `window.list/current/focus/create/close`, v2 `workspace.move_to_window`, and included `window_id` in `system.identify` (plus caller validation). Added v1 window commands for the CLI (`list_windows`, etc). Added VM test coverage (`tests_v2/test_windows_api.py`) and verified v1 + v2 suites passing on the VM.
- 2026-02-11: Fixed split child-exit close semantics and focus indicator drift: exiting (`Ctrl+D`) one side of a split now only closes that pane (never the whole workspace due to transient panel-count state), and terminal first-responder focus now always re-syncs active bonsplit focus so blue focus indicators match actual keyboard focus. Added VM UI regression coverage for child-exit-in-split behavior.
- 2026-02-11: Exposed v2 agent discovery from the CLI: added `cmux identify` (maps to `system.identify`, supports caller via env/flags) and `cmux capabilities` (maps to `system.capabilities`).
- 2026-02-11: Expanded CLI split/pane coverage for agent workflows: added `list-panes`, `list-pane-surfaces`, `focus-pane`, `new-pane`, `new-surface`, `close-surface`, `drag-surface-to-split`, `refresh-surfaces`, `surface-health`, `focus-webview`, `is-webview-focused`, and `trigger-flash` (`surface.trigger_flash`).

## Backlog
- Browser panels: investigate intermittent crash/relaunch around WKWebView lifecycle and focus notifications.
- Keyboard shortcuts: expand VM XCUITest coverage for focus + shortcuts (once Automation Mode is reliably enabled in the VM).
- Socket API: tighten/standardize semantics around split insertion side (left/right/up/down) and pane selection (UUID vs index) across CLI/docs/server.
- CLI: add an `it2`-compatible CLI shim (same subcommands/flags where feasible) that maps to cmux's socket API and ships in `Contents/Resources/bin`.
- Browser automation parity: implement `docs/agent-browser-port-spec.md` (agent-browser command mapping, `cmux browser` surface targeting, move/reorder invariants, and v1 shim strategy).
- Tests: port the agent-browser coverage matrix into `tests_v2/` while keeping both v1 and v2 suites passing.
- Planning: agent-browser port spec decisions locked (ID refs, caller-relative placement, cmux-native output, refs-first output defaults).
