MeinardEdrei/tmux-spotlight
GitHub: MeinardEdrei/tmux-spotlight
一个由 fzf 驱动的极简 tmux 会话管理器与模糊窗口切换器，提供 Spotlight 风格的弹窗来快速搜索、启动、重命名和清理 tmux 会话与窗口。
Stars: 21 | Forks: 0
# tmux-spotlight
一个快速、极简的 [tmux](https://github.com/tmux/tmux) 会话管理器与窗口切换器，由 [fzf](https://github.com/junegunn/fzf) 驱动。模糊搜索窗口与会话，通过 `zoxide`/`fd` 启动命名项目会话，动态重命名与清理 —— 所有操作均可在一个 Spotlight 样式的弹窗中完成。
我原本希望为自己的 tmux 环境寻找一个类似 MacBook 上的应用切换器，但发现现有的插件都过于臃肿且杂乱。所以我编写了这个工具。它严格专注于窗口和会话管理 —— 保持极简、快速且视觉清爽，而不是看起来像 90 年代的终端巫师界面。
*模糊搜索窗口并清理大量堆积的会话。*
## 功能
- **极简依赖：** 仅需 `bash`、`tmux` 和 `fzf`（外加用于文件夹启动的 `zoxide` 和 `fd`）。
- **命名会话启动器：** 切换到文件夹搜索模式（`zoxide` + `fd`），即可瞬间启动或切换到以项目目录自动命名的会话。输入无匹配项的名称时，将直接以该名称创建一个全新的会话。
- **实时预览：** 鼠标悬停时查看活跃的终端内容或目录文件列表。背景色会被自动去除，以确保代码和目录显示保持清爽。
- **整洁网格布局：** 信息在整齐的垂直网格上对齐，便于快速视觉解析，每个窗口均内联显示其所属的会话名。
- **MRU 排序：** 你最近使用的窗口会浮动到列表顶部，无论是在弹窗中还是原生 tmux 导航中的操作都会被追踪。
- **内联重命名：** 直接在弹窗中重命名高亮显示的窗口或其所属会话 —— 无需退回到命令行。
- **快速清理：** 立即关闭单个窗口，或在弹出确认提示后终止整个会话（因为该操作会关闭其中的所有窗口）。两者均会瞬间重载弹窗。
- **友好的取消提示：** 重命名和终止会话的提示均支持按 Esc 或直接按 Enter 输入空值来安全退出。
## 安装说明
**前置条件：** 确保已安装 [fzf](https://github.com/junegunn/fzf)。推荐安装 [zoxide](https://github.com/ajeetdsouza/zoxide) 和 [fd](https://github.com/sharkdp/fd) 用于文件夹搜索和命名会话启动 —— 如果两者均未安装，文件夹模式将显示警告，而不是静默显示空列表。
使用 [TPM](https://github.com/tmux-plugins/tpm)，将以下内容添加到你的 `~/.tmux.conf` 中：
```
set -g @plugin 'MeinardEdrei/tmux-spotlight'
```
然后按下 `prefix + I` 来获取并安装该插件。
## 快捷键
### 启动
- `prefix + Tab`（默认）
- `Alt + Space`（无前缀快捷键默认 —— 可在 tmux 中随处使用）
### 弹窗内部
- `Enter` ：切换到某个窗口，或为选中的文件夹启动/切换到以其目录自动命名的**命名会话**
- 输入一个**无匹配项**的名称并按下 `Enter`，将以该名称创建一个全新的会话
- `Alt + f` ：切换到**项目文件夹**（结合了你的 `zoxide` 目录数据库与由 `fd` 发现的未访问目录）
- `Alt + w` ：切换回**已打开的窗口**
- `Alt + x` ：终止高亮显示的**会话**（重载列表）
- `Alt + q` ：关闭高亮显示的**窗口/标签页**（重载列表）
- `Alt + r` ：重命名高亮显示的**窗口/标签页**（提示输入新名称，重载列表）
- `Alt + s` ：重命名高亮窗口所属的**会话**（提示输入新名称，重载列表）
## 配置
你可以通过在 `~/.tmux.conf` 中添加以下任意变量来覆盖默认配置：
```
# 快捷键
set -g @spotlight-bind 'Tab'
set -g @spotlight-bind-triggerless 'M-Space'
# 尺寸
set -g @spotlight-width '80%'
set -g @spotlight-height '60%'
# 实时预览设置
set -g @spotlight-preview 'on'
set -g @spotlight-preview-location 'right'
set -g @spotlight-preview-ratio '50%'
# 样式
# 自定义纯色背景色 (透明默认为 'default')
# set -g @spotlight-background '#1e1e2e'
# 自定义选中高亮背景 (默认为终端选中主题)
# 选项: 'default' | 'none' / 'transparent' | 任何 ANSI 颜色或十六进制代码
# set -g @spotlight-selection 'none'
# 自定义弹窗快捷键 (fzf 绑定语法)
# set -g @spotlight-bind-folders 'alt-f'
# set -g @spotlight-bind-windows 'alt-w'
# set -g @spotlight-bind-kill-session 'alt-x'
# set -g @spotlight-bind-kill-window 'alt-q'
# set -g @spotlight-bind-rename 'alt-r'
# set -g @spotlight-bind-rename-session 'alt-s'
# 文件夹模式的搜索根目录 (默认为 $HOME)
# set -g @spotlight-folders-dir '$HOME'
```
MRU（最近使用）排序记录在 `~/.cache/tmux-spotlight/mru` 文件中。随时删除此文件即可将排序重置回 tmux 的默认顺序。
## 路线图
- [x] Zoxide + fd 工作区启动器（搜索并瞬间打开项目文件夹）
- [x] 实时预览（终端内容 / 目录列表）
- [x] 快速清理（从弹窗中终止会话/窗口）
- [x] 带有动态 emoji 编码的整洁网格布局
- [x] 会话名称显示 —— 在列表中直接显示窗口所属的会话，而不仅仅是窗口名/路径
- [x] 内联重命名（窗口） —— 直接在弹窗内重命名 tmux 窗口
- [x] 内联重命名（会话） —— 直接在弹窗内重命名 tmux 会话
- [x] 命名会话启动 —— 通过 zoxide/fd 打开的文件夹会自动创建一个以该目录命名的会话（而不是默认的数字编号），输入一个全新的查询会以该名称创建会话
- [x] MRU 排序 —— 按最近使用情况对窗口列表进行排序，而不是 tmux 默认的创建顺序，让你最近打开的几个窗口优先显示
- [ ] 主题预设 —— 开箱即用地支持 `catppuccin`、`nord`、`gruvbox`、`tokyonight`
- [ ] 独立启动 —— 可在 tmux 外部使用（例如全新的 shell）来选择文件夹/会话并连接，而不需要已存在的 tmux 客户端
- [ ] Pane 级别跳转 —— 直接搜索并切换到特定的 pane，而不仅仅是包含它的窗口
- [ ] 已连接/未连接会话显示 —— 在列表中显示某个会话是否已经在其他地方连接了客户端
- [ ] 可配置的文件夹排除项 —— 让 `@spotlight-folders-exclude` 扩展硬编码的 fd 忽略列表（`.git`、`node_modules` 等），以支持特定项目的目录
标签：应用安全