claude-mux

Overview ¶

claude-mux is a PTY multiplexer that enables bidirectional terminal access from multiple sources (e.g., IntelliJ terminal + claude-squad web UI).

Usage:

claude-mux [options] <command> [args...]
claude-mux --attach <session-name>
claude-mux --list

Options:

-n, --name <name>       Custom session name (default: auto-generated from directory)
-a, --attach [session]  Attach to existing tmux session (interactive picker if no session specified)
-l, --list              List available claude-squad tmux sessions

Example:

claude-mux claude
claude-mux -n "api-refactor" claude
claude-mux --name "feature-xyz" aider --model gpt-4
claude-mux --list                           # Show available sessions
claude-mux --attach staplersquad_ext_12345   # Reattach to existing session

The multiplexer creates a Unix domain socket at /tmp/claude-mux-<PID>.sock that claude-squad can discover and connect to for terminal streaming.

Session names are automatically generated from the current directory, command, and PID, e.g., "staplersquad_ext_myproject_claude_12345". The PID suffix ensures uniqueness when running multiple sessions in the same directory. You can override this with -n/--name.

Reattaching to sessions:

After a restart, tmux sessions may still be running but without the streaming socket. Use --list to see available sessions and --attach to reconnect:

claude-mux --list
claude-mux --attach staplersquad_ext_myproject_claude_12345

Setup for seamless use with IntelliJ:

# Option 1: Shell alias
alias claude='claude-mux claude'

# Option 2: PATH override (create ~/bin/claude wrapper)
#!/bin/bash
exec claude-mux /usr/local/bin/claude "$@"