cmux

Use this guide when cmux is your primary terminal and you want each Arashi worktree to open as its own cmux workspace.

Prerequisites

cmux v0.64.18 or newer.
The cmux CLI installed with the application and available from the managed terminal.
Local cmux socket access enabled. The normal cmux processes only access mode works for Arashi launched inside a cmux terminal.

cmux-managed terminals set CMUX_WORKSPACE_ID and CMUX_SURFACE_ID. Arashi uses those identifiers for detection because cmux and standalone Ghostty both report TERM_PROGRAM=ghostty.

Switch to an Existing Worktree

arashi switch feature-auth

From a cmux-managed terminal, Arashi runs the structured equivalent of:

cmux workspace create --cwd /absolute/path/to/worktree --focus true --json

The worktree path is passed as a distinct process argument, so paths containing spaces, quotes, or shell-significant characters are not interpolated through a shell. Arashi validates the returned workspace reference or UUID before reporting success.

Launch After Create

arashi create feature-auth --launch

The same cmux-aware launcher is used for post-create launch defaults. If coordinated worktree creation succeeds but cmux launch fails, the worktrees remain created and the command reports the launch failure separately.

You can also enable post-create launch in .arashi/config.json:

{
  "defaults": {
    "create": {
      "switch": true,
      "launch": true
    }
  }
}

Precedence

Arashi preserves its existing explicit launch and nested-session behavior:

Explicit --sesh or IDE launch flags such as --vscode, --cursor, and --kiro take precedence.
An active tmux session nested inside cmux opens a tmux window.
Otherwise, a cmux-managed terminal creates and focuses a cmux workspace.
Standalone Ghostty and other detected terminal apps keep their existing launch behavior.

Arashi does not currently provide an explicit --cmux flag. Automatic detection is limited to managed cmux terminals; setting CMUX_SOCKET_PATH alone does not activate cmux launch behavior.

Troubleshooting

Arashi opens standalone Ghostty

Confirm the invocation is running inside a cmux-managed terminal:

printf '%s\n' "$CMUX_WORKSPACE_ID" "$CMUX_SURFACE_ID"

At least one identifier must be non-empty. A socket path by itself is intentionally insufficient because external processes can point at a cmux socket without being inside a cmux surface.

`cmux workspace create` is unavailable

Update cmux to v0.64.18 or newer and verify the namespaced command:

cmux workspace create --help

Arashi relies on --cwd, --focus, and structured JSON output rather than parsing the legacy new-workspace text response.

Socket access fails

Check that cmux socket access is not Off. For calls made from a cmux terminal, the default cmux processes only mode is sufficient. If cmux reports an inaccessible or disabled socket, Arashi returns LAUNCH_FAILED with the cmux error and does not silently open another terminal.