@lobes/vmux

Parallel agents with tmux and worktrees

Manage multiple AI coding agents in isolated git worktrees.
Branch, develop, and merge — all in parallel.

Issues

Language: English | 日本語

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