English · 中文
English
Use tmux panes in the VS Code integrated terminal on macOS. Each pane runs zsh, and you can click a pane to focus it.
Preview
Setup
Requires VS Code 1.139 or later and Homebrew. After installing the extension, open a new VS Code terminal to start tmux. On first activation, the extension selects its terminal profile as the default and adds the shortcuts below to your VS Code user keybindings. Those shortcuts still work as usual outside the terminal.
If you later choose another default terminal profile, the extension respects your choice. Run Tmux Terminal: Use as Default Terminal to switch back. When you first open a tmux terminal, the extension checks for tmux and, if needed, runs brew install --no-ask tmux without an installation confirmation prompt. Progress appears in a VS Code notification; installation errors appear in Output → Tmux Terminal.
The terminal stays wherever you have placed the VS Code terminal view. If task and debug terminal shells have not been configured, the extension sets them to zsh.
| Shortcut |
Action |
⌘D |
Split left and right |
⌘⇧D |
Split top and bottom |
⌘⌥ + arrow key |
Focus the pane in that direction |
⌘W |
Close the current pane immediately |
⌘V |
Paste text or an image from the clipboard |
⇧Enter |
Insert a newline in zsh, Codex, and Coco input |
These shortcuts apply on macOS when this extension is the default terminal profile and the terminal has focus. ⇧Enter inserts a literal newline in zsh and sends Alt+Enter to other programs. If a program uses custom keybindings, configure Alt+Enter to insert a newline there. ⌘W terminates the process running in the current pane.
Copy an image or a screenshot to the clipboard, then press ⌘V in the terminal (or run Tmux Terminal: Paste (Text or Image)). Images are saved as PNG files in a private directory under the macOS temporary directory and pasted as file paths without submitting the input. Agent CLIs that support image-path pastes, such as Codex, can attach them. In a shell, the path is inserted. Plain text uses VS Code’s normal terminal paste. Temporary images are retained for agents to read later and can be removed after use; macOS may also clean them up. This works with local CLIs; it does not upload images to SSH or remote hosts.
Each new VS Code terminal starts a separate tmux session. The extension uses the vscode-integrated tmux socket and does not change your iTerm2 configuration.
Buy me a coffee
If Tmux Terminal makes your work a little smoother, you can buy me a coffee. Thank you for your support! ☕
中文
在 macOS 的 VS Code 集成终端中使用 tmux 分屏。每个窗格都运行 zsh，点击即可切换焦点。
效果预览
使用方法
需要 VS Code 1.139 或更高版本，并已安装 Homebrew。安装插件后，新建一个 VS Code 终端即可启动 tmux。首次激活时，插件会将自己的终端配置设为默认，并将下方快捷键添加到 VS Code 的用户键盘快捷方式中。这些快捷键在终端以外仍保留原有功能。
如果你之后选择了其他默认终端配置，插件会尊重你的选择。运行 Tmux Terminal: Use as Default Terminal 即可切换回来。首次打开 tmux 终端时，插件会检查是否已安装 tmux；如未安装，会直接运行 brew install --no-ask tmux，不再弹出安装确认。安装进度显示在 VS Code 通知中，错误信息可在 输出 → Tmux Terminal 中查看。
终端会保留在你放置 VS Code 终端视图的位置。如果尚未配置任务和调试终端的 shell，插件会将它们设为 zsh。
| 快捷键 |
功能 |
⌘D |
左右分屏 |
⌘⇧D |
上下分屏 |
⌘⌥ + 方向键 |
将焦点切换到对应方向的窗格 |
⌘W |
立即关闭当前窗格 |
⌘V |
粘贴剪贴板中的文本或图片 |
⇧Enter |
在 zsh、Codex 和 Coco 输入中换行 |
这些快捷键仅在 macOS 上、此插件为默认终端配置且终端获得焦点时生效。⇧Enter 在 zsh 中插入换行符，在其他程序中发送 Alt+Enter。如果程序使用自定义快捷键，请在该程序中将 Alt+Enter 配置为换行。⌘W 会终止当前窗格中运行的进程。
复制图片或截图到剪贴板后，在终端按 ⌘V，也可运行 Tmux Terminal: Paste (Text or Image)。插件会将图片保存为 macOS 临时目录下私有目录中的 PNG 文件，再粘贴文件路径，不自动提交输入。支持图片路径粘贴的 Agent CLI（如 Codex）可将其识别为附件；在 shell 中则插入路径。普通文本仍使用 VS Code 原有的终端粘贴。临时图片会保留供 Agent 后续读取，用完可手动删除，macOS 也可能清理它们。此功能用于本机 CLI，不会将图片上传到 SSH 或远程主机。
每个新建的 VS Code 终端都会启动独立的 tmux 会话。插件使用 vscode-integrated tmux socket，不会修改你的 iTerm2 配置。
请我喝杯咖啡
如果 Tmux Terminal 让你用终端更顺手，欢迎请我喝杯咖啡。感谢你的支持！☕
