# tmux 配置

> 在 tmux 中正确传递 Shift+Enter、Ctrl+Enter 等修饰键的推荐配置。

---

LLMS 索引： [llms.txt](/llms.txt)

---

Pi 可以在 tmux 中运行，但 tmux 默认会剥离某些按键的修饰键信息。如果不进行配置，`Shift+Enter` 和 `Ctrl+Enter` 通常无法与普通的 `Enter` 区分开。

## 推荐配置 {#recommended-configuration}

在 `~/.tmux.conf` 中添加：

```tmux
set -g extended-keys on
set -g extended-keys-format csi-u
```

然后完全重启 tmux：

```bash
tmux kill-server
tmux
```

当 Kitty 键盘协议不可用时，Pi 会自动请求扩展按键上报。设置 `extended-keys-format csi-u` 后，tmux 会以 CSI-u 格式转发带修饰键的按键，这是最可靠的配置。`extended-keys-format` 选项要求 tmux 3.5 或更高版本。

## 为什么推荐使用 `csi-u` {#why-csi-u-is-recommended}

如果只设置：

```tmux
set -g extended-keys on
```

tmux 会默认使用 `extended-keys-format xterm`。当应用程序请求扩展按键上报时，带修饰键的按键会以 xterm `modifyOtherKeys` 格式转发，例如：

- `Ctrl+C` → `\x1b[27;5;99~`
- `Ctrl+D` → `\x1b[27;5;100~`
- `Ctrl+Enter` → `\x1b[27;5;13~`

设置 `extended-keys-format csi-u` 后，同样的按键会以如下方式转发：

- `Ctrl+C` → `\x1b[99;5u`
- `Ctrl+D` → `\x1b[100;5u`
- `Ctrl+Enter` → `\x1b[13;5u`

Pi 支持这两种格式，但在 tmux 环境下推荐使用 `csi-u`。

## 这解决了什么问题 {#what-this-fixes}

如果没有 tmux 扩展按键，带修饰键的 Enter 会退化为传统序列：

| 按键 | 未启用扩展按键 | 使用 `csi-u` |
|-----|-----------------|--------------|
| Enter | `\r` | `\r` |
| Shift+Enter | `\r` | `\x1b[13;2u` |
| Ctrl+Enter | `\r` | `\x1b[13;5u` |
| Alt/Option+Enter | `\x1b\r` | `\x1b[13;3u` |

这会影响默认快捷键（`Enter` 提交、`Shift+Enter` 换行），以及所有使用带修饰键 Enter 的自定义快捷键。

## 环境要求 {#requirements}

- tmux 3.5 或更高版本（用于 `extended-keys-format csi-u`，运行 `tmux -V` 可检查版本）
- 支持扩展按键的终端模拟器（Ghostty、Kitty、iTerm2、WezTerm、Windows Terminal）

对于 tmux 3.2 到 3.4，请省略 `extended-keys-format csi-u`；Pi 仍然支持 tmux 默认的 xterm `modifyOtherKeys` 格式。

---

反链：

- [快速开始](/book/pi/quickstart/)