Previously, v2SurfaceSendText, v2SurfaceSendKey, v2SurfaceClearHistory, and
v2SurfaceReadText would silently fall back to ws.focusedPanelId when a caller
supplied a surface_id that could not be resolved (e.g. a stale ref or an ordinal
whose mapping had not yet been registered). This caused two distinct bugs:
- #2042: Commands like `cmux send --surface surface:9999` would succeed (exit 0)
and deliver input to the focused pane instead of returning an error, making
automation that targets specific surfaces unreliable.
- #2045: When the fallback landed on a browser panel, the subsequent
ws.terminalPanel(for:) check failed and returned "Surface is not a terminal",
making valid terminal surfaces appear broken when addressed by ref.
The fix adds an explicit check: if params["surface_id"] is present but
v2UUID() returns nil (resolution failure), we immediately return a not_found
error instead of falling back to the focused pane. When surface_id is absent,
the existing focused-pane fallback is preserved for backward compatibility.
Fixes#2042, Fixes#2045
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* Support modifier+key combinations in send-key (ctrl+enter, shift+tab, etc.)
The send-key command only supported a few hardcoded ctrl+letter combos
and bare special keys. Generic modifier combinations like ctrl+enter
(needed for GitHub Copilot CLI submission) returned "Unknown key".
Now the parser splits on + and - separators, accumulates modifier flags
(ctrl, shift, alt/opt, cmd/super), and resolves the base key via a new
keycodeForNamedKey helper that maps named keys (enter, tab, escape,
backspace, space, arrow keys) to virtual keycodes.
Closes#1990
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Fix delete key mapping and filter empty parts in modifier parser
- Separate "delete" (forward delete, kVK_ForwardDelete) from "backspace"
(kVK_Delete) in keycodeForNamedKey. The original mapping had both
pointing to kVK_Delete (which is actually Backspace on macOS).
- Filter empty strings from split results to reject malformed inputs
like "+shift+a" that would produce an empty modifier part.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Fix single named keys silently failing and remove force unwrap in send-key
Single named keys like "space", "up", "delete" were rejected by
guard parts.count >= 2 before reaching keycodeForNamedKey(). Now
standalone named keys are handled before the modifier-combo path.
Also replaced parts.last! with guard let for safe unwrapping.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Add `cmux omo` command for OpenCode + oh-my-openagent integration
Same pattern as `cmux claude-teams`: creates a tmux shim so
oh-my-openagent's TmuxSessionManager spawns agents as native cmux
splits instead of tmux panes. Sets TMUX/TMUX_PANE env vars, prepends
shim to PATH, and execs into opencode.
Closes https://github.com/manaflow-ai/cmux/issues/2085
* Auto-install oh-my-opencode plugin when running cmux omo
Before launching opencode, cmux omo now:
- Checks if oh-my-opencode is registered in ~/.config/opencode/opencode.json
- If not, creates/updates the config with the plugin entry
- Checks if the npm package is installed in node_modules
- If not, runs bun add (or npm install) to install it
- Then proceeds with tmux shim setup and exec
* Use shadow config dir to avoid modifying user's opencode setup
Instead of writing directly to ~/.config/opencode/opencode.json,
cmux omo now creates a shadow config at ~/.cmuxterm/omo-config/ that
layers oh-my-opencode on top of the user's existing config. Symlinks
node_modules, package.json, bun.lock, and plugin config from the
original dir. Sets OPENCODE_CONFIG_DIR to the shadow directory.
Running plain `opencode` remains unaffected.
* Add Agent Integrations docs section with Claude Code Teams and oh-my-opencode pages
Adds sectioned sidebar navigation to the docs site. The new Agent
Integrations section contains separate pages for cmux claude-teams and
cmux omo, documenting usage, tmux shim mechanics, directory layout,
environment variables, and the shadow config approach. Both pages
include a nightly-only warning. Full English and Japanese translations,
nav item keys added to all 19 locales.
* Remove uppercase from sidebar section headers
* Add more spacing above and below sidebar section headers
* Enable tmux mode in oh-my-opencode config, improve docs
- cmux omo now writes tmux.enabled=true to the shadow oh-my-opencode.json
config. Without this, oh-my-openagent's TmuxSessionManager won't spawn
visual panes even though $TMUX is set (the config defaults to false).
- Nightly warnings now link to /nightly instead of generic text.
- Added "What you get" section to oh-my-opencode docs explaining the
visual pane behavior (auto-layout, idle cleanup, queueing).
- Added tmux.enabled step to first-run and how-it-works sections.
* Add terminal-notifier shim to route oh-my-openagent notifications to cmux
oh-my-openagent sends macOS notifications via terminal-notifier
(args: -title <t> -message <m> [-activate <id>]). The shim in
~/.cmuxterm/omo-bin/terminal-notifier intercepts these calls and
routes them through cmux notify, so notifications appear in cmux's
sidebar panel instead of as raw macOS notifications.
* Add pane geometry to tmux-compat for oh-my-openagent grid planning
oh-my-openagent's TmuxSessionManager needs pane geometry (columns,
rows, position, window dimensions) to decide where to spawn agent
panes. Without this data, agents run headlessly.
Server side:
- pane.list v2 response now includes pixel_frame, cell_size, columns,
rows per pane, plus container_frame at the top level
- Uses BonsplitController.layoutSnapshot() for pixel geometry and
ghostty_surface_size() for terminal grid dimensions
CLI side:
- tmuxEnrichContextWithGeometry() computes character-cell positions
from pixel frames and cell dimensions for tmux format variables
(pane_width, pane_height, pane_left, pane_top, pane_active,
window_width, window_height)
- list-panes now resolves pane targets (%uuid) via tmuxResolvePaneTarget
instead of failing with "Workspace not found"
- display-message enriched with geometry for format strings like
#{pane_width},#{window_width}
- tmux -V now returns "tmux 3.4" (needed by oh-my-openagent's
tmux-path-resolver verification)
* Add socket tests for tmux-compat pane geometry
6 tests verifying the geometry enrichment works end-to-end:
- pane.list returns pixel_frame, columns, rows, cell_size, container_frame
- tmux -V returns version string
- list-panes -F renders geometry format variables as integers
- list-panes -t %<uuid> resolves pane targets
- display -p renders pane_width and window_width
- After split, two panes have different positions and halved widths
All 6 pass on macmini (cmux-macmini).
* Handle tmux -V in shim script directly (no socket needed)
oh-my-openagent's tmux-path-resolver runs tmux -V to verify the binary
works. The __tmux-compat handler requires a socket connection, which
may not be established at verification time. Handle -V in the bash
shim directly to avoid the socket dependency.
* Lower default tmux pane min widths for cmux omo
oh-my-openagent defaults: main_pane_min_width=120, agent_pane_min_width=40,
requiring 161+ columns. Most terminal windows are narrower, causing
decideSpawnActions to return canSpawn=false and defer agents forever.
cmux omo now sets: main_pane_min_width=60, agent_pane_min_width=30,
main_pane_size=50, requiring only 91 columns. Also moved tmux -V
handling into the bash shim to avoid needing a socket connection for
the version check.
* Resolve merge conflicts with main (main-vertical layout, focus param)
- Keep upstream main-vertical layout anchoring from #2119
- Keep upstream focus param (v2Bool) instead of no_focus
- Combine with our -d flag handling: -d sets focus=false
- Include customCommands nav item from main
* Implement select-layout equalize and resize-pane absolute width
When oh-my-openagent spawns agent panes, it calls select-layout
main-vertical after each split to redistribute panes evenly, then
resize-pane -x <columns> to set the main pane width. Both were
previously no-ops, causing cascading uneven splits.
Server side:
- Add workspace.equalize_splits v2 API that calls the existing
TabManager.equalizeSplits (sets all dividers to 0.5)
CLI side:
- select-layout now calls workspace.equalize_splits before tracking
main-vertical state
- resize-pane -x <columns> without directional flags now computes
the pixel delta from current to desired width and resizes accordingly
* Fix equalize to use proportional divider positions
The previous equalize set all dividers to 0.5, which in a right-
recursive binary tree (from successive splits) gives 50/25/12.5/6.25%
instead of equal sizes.
New algorithm counts leaf panes on each side of each split and sets
the divider to N_left / (N_left + N_right). For 5 panes in a chain:
1/5, 1/4, 1/3, 1/2, giving each pane exactly 20%.
* Fix select-layout main-vertical to only equalize vertical splits
The proportional equalize was treating the top-level horizontal split
(main vs agent column) the same as vertical splits, setting the main
pane to 1/6 of the window with 5 agents.
For main-vertical layout, only equalize vertical splits (the agent
column), leaving the horizontal main/agent divider untouched. The
subsequent resize-pane -x handles the main pane width.
workspace.equalize_splits now accepts an optional orientation filter
("vertical" or "horizontal") to scope which splits get equalized.
* Re-equalize agent column after kill-pane
* Address PR review comments
- Fix cmux omo --help: remove omo from the help-bypass guard so
--help shows usage text instead of trying to launch opencode
- Don't overwrite unreadable opencode.json: fail with an error
instead of silently resetting to empty config
- Drain installer pipes concurrently before waitUntilExit to
prevent deadlock from full pipe buffers during bun/npm install
---------
Co-authored-by: Lawrence Chen <lawrencecchen@users.noreply.github.com>
Allow naming a workspace at creation time instead of requiring a
separate rename-workspace call afterward.
Threads a title parameter through:
- CLI: --name <title> flag parsed and sent as "title" in v2 params
- V2 handler: extracts title, passes to TabManager.addWorkspace()
- TabManager: uses provided title instead of auto-generated
"Terminal N" and calls setCustomTitle() to persist it
- V1 handler: accepts optional name argument
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* Fix claude-teams pane anchoring: main-vertical layout + focus
Claude's agent teams sends `split-window -h` for each teammate then
`select-layout main-vertical` to stack them vertically. Three fixes:
1. Implement select-layout main-vertical: track layout state in the
tmux compat store so subsequent horizontal splits of the leader
pane get redirected to vertical splits of the right-side column.
2. Pass focus:false to surface.split from the split-window handler
so internal bonsplit focus stays on the leader pane.
3. Fix tmuxCompatStoreURL to respect $HOME env var (was using
NSString.expandingTildeInPath which ignores $HOME).
Closes https://github.com/manaflow-ai/cmux/issues/2118
* Fix claude-teams split routing: auto-seed main-vertical on first right split
The split-window routing was broken in two ways:
1. After the first teammate split (right), the main-vertical state wasn't
being created, so all subsequent splits also went right instead of
stacking down in the right column.
2. The old code only redirected splits when main-vertical was already active
AND the target was the leader surface. Claude's teams protocol targets
arbitrary panes from list-panes, not necessarily the leader.
Now the first teammate split goes right (creating the column), auto-seeds
the main-vertical state, and all subsequent splits stack downward. The
caller's surface (CMUX_SURFACE_ID) is used as the anchor regardless of
which pane Claude targets.
Also adds caller surface preference in pane target resolution so the
caller's exact surface is used when the target pane matches, preventing
stale selected-surface references after tab switches.
---------
Co-authored-by: Lawrence Chen <lawrencecchen@users.noreply.github.com>
* Add set-color/clear-color workspace actions for tab color via CLI
Expose the existing tab color functionality through the workspace-action
CLI command, enabling programmatic tab color setting without the GUI
context menu.
Supports both named colors (Red, Blue, Amber, etc.) and hex values
(#RRGGBB). Named colors resolve against the built-in palette via
case-insensitive matching.
Usage:
cmux workspace-action --action set-color --color blue
cmux workspace-action --action set-color --color "#C0392B"
cmux workspace-action set-color Amber
cmux workspace-action clear-color
* Return explicit null color in clear_color JSON response
Restore "color": null in the clear_color response payload so JSON
consumers can distinguish "color was cleared" from "no color field".
---------
Co-authored-by: Ariel Tobiana <arieltobiana@gmail.com>
The socket API's send-key command only supported enter, escape, tab,
backspace, and ctrl+letter. Arrow keys and shift+tab had to be sent
as raw escape sequences via send_text, but 0x1B is filtered out by
socketTextChunks and converted to a standalone Escape key event,
breaking multi-byte sequences like \x1b[A (ArrowUp).
This commit extends sendNamedKey to handle:
- Arrow keys: up/down/left/right (with arrow_up/arrowup aliases)
- shift+tab / shift-tab / backtab
- home, end
- delete / del / forward_delete
- pageup / page_up
- pagedown / page_down
These map directly to the existing sendKeyEvent infrastructure using
the appropriate kVK_* keycodes and modifier flags.
Co-authored-by: I Luk Kim <yirugi@gmail.com>
* fix(browser): use native value setter for React/Vue/Angular compatibility
fill, type, and select commands set input values via direct property
assignment (el.value = x), which does not trigger state updates in
frameworks that override the value setter on element instances.
Use Object.getOwnPropertyDescriptor on the prototype to call the
native setter, which bypasses the framework override and allows the
subsequent input/change events to propagate correctly through
React's synthetic event system.
Affects: browser.fill, browser.type, browser.select
* walk prototype chain instead of instanceof for cross-realm and web component support
---------
Co-authored-by: joshuaswanson <joshuaswanson@users.noreply.github.com>
Add tty field to surface items in system.tree JSON response,
reading from existing surfaceTTYNames dictionary. Also show
tty= in the CLI text tree output for terminals that have a
registered TTY.
This enables external tools (e.g. CodeV) to cross-reference
claude process TTYs with cmux surfaces for accurate session
detection when multiple sessions share the same working directory.
* Allow customizing numbered workspace and surface shortcuts
* Update bonsplit submodule to squashed main commit
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Fixes#1715
The resolveTabForReport() function had an early guard that returned nil
when self.tabManager was nil, even when a valid --tab argument was
provided. This prevented Claude hook commands from resolving tabs via
AppDelegate.shared when the local tabManager wasn't available.
Changes:
- Modified resolveTabForReport() to allow tab resolution via --tab param
even when self.tabManager is nil
- Removed early guard in upsertSidebarMetadata() that blocked resolution
Co-authored-by: BillionClaw <267901332+BillionClaw@users.noreply.github.com>
* Fix stale Claude status in sidebar by adding missing hooks and OSC suppression
The Claude Code integration only used 3 hooks (SessionStart, Stop, Notification),
leaving gaps that caused stale sidebar status. Now uses 6 hooks:
- SessionEnd: clears status when Claude exits (covers Ctrl+C where Stop doesn't fire)
- UserPromptSubmit: clears "Needs input" and sets "Running" on new prompt
- PreToolUse (async): clears "Needs input" when Claude resumes after permission grant
Also:
- Suppress OSC 9/99 desktop notifications for workspaces with active Claude hook
sessions to prevent duplicates from the raw OSC path
- Store Claude process PID in status entries for stale-session detection
- Add 30-second sweep timer that checks agent PIDs and clears stale entries
(safety net for SIGKILL/crash where no hook fires)
- Update wrapper test expectations for the new hook set
Fixes https://github.com/manaflow-ai/cmux/issues/1301
* Don't show "Running" status on Claude launch, only when actually working
SessionStart now registers the PID for tracking and OSC suppression via
set_agent_pid without setting a visible status entry. "Running" only
appears when the user submits a prompt (UserPromptSubmit) or Claude
starts using tools (PreToolUse).
Added set_agent_pid / clear_agent_pid socket commands to decouple PID
tracking from visible status entries. OSC suppression checks agentPIDs
instead of statusEntries so it works during the initial idle period.
* Don't restore status entries across app restarts
Status entries are ephemeral runtime state tied to running processes
(e.g. claude_code "Running"). Restoring them after restart shows stale
status for processes that no longer exist.
* Address PR review comments and remove debug logging
- session-end: only clear status/PID/notifications when Stop didn't fire first
- PID sweep: check errno == ESRCH instead of treating all kill(pid,0) failures as dead
- Validate CMUX_CLAUDE_PID > 0
- Propagate tracked PID in pre-tool-use setClaudeStatus
- OSC suppression: use tabManagerFor(tabId:) for multi-window support
- clearAgentPID: resolve tab UUID before async dispatch
- restoreSessionSnapshot: also clear agentPIDs alongside statusEntries
- Fix AskUserQuestion surfaceId overwrite (wrong workspace notification)
- Fix notification text matching for "Claude Code needs your attention"
- AskUserQuestion: render option labels as bracketed inline text
- Remove artificial text truncation limits
- Remove temporary JSONL debug logging from all handlers
* Use resolveTabIdForSidebarMutation in clearAgentPID
* Fallback stable socket listener to user socket path
* Move stable socket path out of /tmp
* Keep socket health checks active on fallback paths
---------
Co-authored-by: Lawrence Chen <lawrencecchen@users.noreply.github.com>
* Add cmux welcome command with ASCII logo and shortcuts
Adds `cmux welcome` CLI command that prints a blue-to-purple gradient
chevron logo, version info, and key shortcuts. Auto-runs once on first
workspace creation via UserDefaults. Adds "Welcome" to the ? help menu
in the sidebar footer, which opens a new workspace running the command.
* Polish welcome, feedback, and shortcuts flows
