Install

npm install -g @lobes/vmux

Quick Start

cd /path/to/your/project
vmux

Press n to create a new pane, type a prompt, pick one or more agents (or none for a plain terminal), and vmux handles the rest — worktree, branch, and agent launch.

Press u to open rituals: reusable setup recipes for starting a project with a known pane layout. Built-ins include Start Coding, Terminal First, Review Stack, and Release Check. You can also save the current setup as a project ritual and attach a default ritual to that project.

New to tmux? Run:

vmux doctor
vmux doctor --fix

vmux doctor checks tmux, git, clipboard/navigation support, vmux session styling, and the vmux-managed tmux config block. --fix applies safe repairs, backs up an existing ~/.tmux.conf, and only edits the block between # >>> vmux and # <<< vmux.

What it does

vmux creates a tmux pane for each task. Every pane gets its own git worktree and branch so agents work in complete isolation. When a task is done, open the pane menu with m and choose Merge to bring it back into your main branch, or Create GitHub PR to push the branch and file a pull request.

• Worktree isolation — each pane is a full working copy, no conflicts between agents
• Agent support — Claude Code, Codex, OpenCode, Cline CLI, Gemini CLI, Qwen CLI, Amp CLI, pi CLI, Cursor CLI, Copilot CLI, and Crush CLI
• Multi-select launches — choose any combination of enabled agents per prompt
• AI naming — branches and commit messages generated automatically
• Smart merging — auto-commit, merge, and clean up in one step
• macOS notifications — background panes can send native attention alerts when they settle and need you
• Built-in file browser — inspect a pane's worktree, search files, and preview code or diffs without leaving vmux
• Pane visibility controls — hide individual panes, isolate one project, or restore everything later without stopping work
• Multi-project — add multiple repos to the same session
• Rituals — open, save, and attach reusable project setup recipes without restoring brittle tmux snapshots
• Lifecycle hooks — run scripts on worktree create, pre-merge, post-merge, and more

Keyboard Shortcuts

| Key | Action | |---|---| | n | New pane (worktree + agent) | | t | New terminal pane | | u | Open or manage rituals | | e | Rename the selected pane/thread or project inline | | j / Enter | Jump to pane | | m | Open pane menu | | f | Browse files in selected pane's worktree | | x | Close pane | | h | Hide/show selected pane | | H | Hide/show all other panes | | p | Add project to sidebar | | P | Show only the selected project's panes, then show all | | s | Settings | | q | Quit |

When focus is inside a work pane, tmux receives your keys instead of vmux. Use Ctrl-b then Left Arrow to return to the vmux sidebar. When mouse events are enabled, click a pane/thread/worktree row to select it and double-click a pane/thread/worktree name or project header to edit it inline. On macOS, Alt+Shift+M opens the focused pane menu when your terminal sends Option as Meta. In Terminal.app, enable Settings > Profiles > Keyboard > Use Option as Meta key. In iTerm2, use Settings > Profiles > Keys > Left/Right Option Key > Esc+.

Requirements

• tmux 3.0+
• Node.js 18+
• Git 2.20+
• At least one supported agent CLI (for example Claude Code, Codex, OpenCode, Cline CLI, Gemini CLI, Qwen CLI, Amp CLI, pi CLI, Cursor CLI, Copilot CLI, Crush CLI)
• OpenRouter API key (optional, for AI branch names and commit messages)

Contributing

See CONTRIBUTING.md for the recommended local "vmux-on-vmux" development loop, hook setup, and PR workflow.

License

MIT