pi-tmux-sidebar
在独立 tmux 服务中并行运行多个 Pi,左侧常驻多会话与 Git 侧边栏,底部提供实时 Agent 状态栏
Package details
Install pi-tmux-sidebar from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-tmux-sidebar- Package
pi-tmux-sidebar- Version
0.1.2- Published
- Nov 15, 2026
- Downloads
- 593/mo · 251/wk
- Author
- mrhear
- License
- MIT
- Types
- extension
- Size
- 283.8 KB
- Dependencies
- 0 dependencies · 1 peer
Pi manifest JSON
{
"extensions": [
"./extensions/index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-tmux-sidebar (pisb)
在独立 tmux 服务里并行运行多个 Pi 会话:每个窗口左侧常驻会话与 Git 侧边栏,右侧运行 Pi,底部提供实时 Agent 状态栏与 /fast 优先档位开关。后台 Pi 持续运行,点击或按键即可秒切。

系统要求
- 操作系统:macOS / Linux / Windows WSL(原生 CMD / PowerShell 不支持
tmux) - tmux:
3.0+(兼容 Ubuntu 22.043.2a、Debian 123.3a、Ubuntu 24.043.4及 macOSbrew install tmux;OSC 8 超链接透传需3.4+,底栏[fast]鼠标点击需3.8+,低版本仍可用/fast命令) - Node.js:
>= 22.18 - Pi CLI:
@earendil-works/pi-coding-agent(pi在PATH中可用)
若本机尚未安装
tmux,直接运行pi时插件会输出一行简短提示并自动回退为普通单窗口pi,不会阻塞正常使用。
安装与启动
作为 Pi 插件安装(推荐)
# 从 npm 安装
pi install npm:pi-tmux-sidebar
# 或从 Git 仓库安装
pi install git:github.com/mrhear630/pi-tmux-sidebar
# 或从本地目录安装
pi install ./pi-tmux-sidebar
安装完成后,在普通交互式终端里直接输入 pi 即可自动进入带左侧栏的 tmux 窗口;已有会话时会在同一会话中新开一个窗口。
- 脱离后台运行:按
Ctrl+b d暂时离开,所有 Pi 继续在后台运行;想直接回到原窗口可执行tmux -L pisb attach -t pi(或使用下方的pisb命令)。 - 临时禁用侧边栏:
PISB_DISABLE=1 pi - 不会转入 tmux 的场景:已在任意
tmux会话内、pi -p/--mode json|rpc/--export/--list-models/--help/--version、pi install|list|update|...子命令,以及非交互管道(脚本、子代理)。 - 卸载:
pi remove npm:pi-tmux-sidebar(或安装时使用的对应来源)
可选 pisb 命令行入口
若通过 npm install -g pi-tmux-sidebar 或在本仓库执行 npm link,可直接使用 pisb 命令:
pisb # 回到已有 "pi" 会话(不新开窗口);不存在则在当前目录新建
pisb ~/projects/web-app # 在指定目录新开一个 Pi 窗口并切过去
pisb ~/projects/web-app -- --model gpt-5 # -- 后的参数原样传给 pi
即使未执行 pi install,通过 pisb 启动时也会自动以 pi -e 临时加载扩展,不会重复挂载。
独立 tmux 服务与零污染设计
默认情况下,pisb 通过 tmux -L pisb 运行在名为 pisb 的独立 socket 上:
tmux/pisb.conf中的状态栏样式、mouse on、base-index 1、Alt+s等选项仅作用于pisb独立服务,不会覆盖或污染你日常使用的默认tmux配置、状态栏与其他会话。- 新开窗口中的
pi由常驻后台的tmux -L pisb服务进程派生(PI_CODING_AGENT_DIR与PI_CODING_AGENT_SESSION_DIR会自动透传);模型供应商密钥建议通过/login或写入<agentDir>/auth.json持久化,避免仅临时export在当前 shell 后被已有 tmux 服务忽略。 - 如果你希望将 Pi 窗口放进系统默认
tmux服务,可设置环境变量PISB_SOCKET=default。
| 环境变量 | 默认值 | 说明 |
|---|---|---|
PISB_SOCKET |
pisb |
使用的 tmux -L <name> 独立 socket 名;设为 default / none / 0 时共用系统默认 tmux server |
PISB_SESSION |
pi |
tmux 会话名称 |
PISB_WIDTH |
30 |
强制覆盖侧边栏列宽(未设置时可在设置页保存 16–100 列,支持鼠标拖拽分隔线) |
PISB_DISABLE |
未设置 | 设为 1 时普通终端运行 pi 不自动进入 tmux,也不输出缺失 tmux 提示 |
PI_CODING_AGENT_DIR |
~/.pi/agent |
遵循 Pi 官方配置目录变量;侧边栏状态、搜索索引与回收站均存储在该目录下 |
PI_CODING_AGENT_SESSION_DIR |
<agentDir>/sessions |
遵循 Pi 官方会话存储目录变量 |
核心功能
1. 多会话管理与防误关策略
- 待处理提醒:后台会话出现「待回答(弹框确认/提问)→ 运行出错 → 后台完成未查看」时,会话页顶部自动汇总待处理列表;按
!或点[待办]按优先级一键跳转,切过去查看后自动清除完成标记。 - 平铺目录分组:置顶目录(
★)排在最前,其余按最近活动时间倒序;重名目录自动补充父级目录区分(如web/app、admin/app)。点击目录原地展开全部未打开的历史会话,点击右侧+直接在该目录新建会话。 - 切走自动关空闲窗口:从侧边栏切换到其他会话、打开历史或新建窗口时,原窗口只要处于空闲且输入框无未发送草稿,会自动关闭窗口以防堆积(历史记录完整保留,随时可重开)。
- 自动保留保护:正在运行、等待输入、启动中、输入框有未发送草稿,或按
K显式标记「保留」的会话均不会自动关闭;也可在,设置页全局关闭此策略。 - 手动关闭保护:点击行尾
✕、鼠标中键或按x关闭窗口时,待输入与后台完成未看的窗口拒绝直接关闭;运行中或有草稿的窗口需在 15 秒内按y二次确认强关;tmux 状态不可读时保守拒绝关闭。
- 自动保留保护:正在运行、等待输入、启动中、输入框有未发送草稿,或按
- 安全回收站与目录归档:
- 在历史或最近任务行按
d(或右键菜单选「删除会话」)后,确认区会显示会话标题、目录和大小;按y或点击[y 确认]才会删除,按Esc或点击[Esc 取消]可取消。会话文件整体移入私有回收区<agentDir>/pisb-trash/(从不改写会话内容);正打开或 60 秒内仍在写入的会话禁止删除。按u可一键撤销最近一批删除;永久清空回收区时会同步清理对应会话的元数据与正文索引缓存。 - 在目录行按
a(或右键菜单选「归档目录」)可将不常用项目收到底部默认折叠的「已归档」分组,不移动任何会话文件;在该目录新建或打开会话会自动取消归档。
- 在历史或最近任务行按
2. 全量历史搜索(f)
- 会话页按
/为当前列表轻量模糊筛选;按f进入独立历史搜索页,突破列表 2,000 条上限。 - 支持
[所有项目 / 当前项目](p)范围切换,以及[模糊元数据 / 正文](t)模式切换(流式检索 user/assistant 文本并展示上下文片段,原始 JSONL 会话只读,增量索引缓存在<agentDir>/pisb-session-index/)。
3. Git 标签页与全屏左右对比(g)
会话 Git
my-service
本地 main
远端 origin/main ↑1 ↓0
▾ 已暂存 1
M src/auth.ts [-]
▾ 未暂存 2
▾ src/routes/ 2
M login.ts [+]
? health.ts [+]
▾ 最近提交
▸ a1b2c3d 完善鉴权校验 2时
[暂存] [取消暂存]
[提交] [拉取] [推送] [分支]
- 目录树与分批暂存:单子目录链自动折叠为一行(如
src/core/http/);支持单文件行尾[+]/[-],以及选中目录或分组标题后按s/u批量暂存与取消暂存(预检路径边界,拒绝跨所选目录范围的重命名误伤)。 - 全屏左右对比查看器:点击工作区改动文件或展开提交记录中的文件,自动在当前窗口分屏放大展示左右分栏 Diff(左旧右新、行号对齐、中文等宽折行,
n/N跳改动块,q/Esc或点右上角[关闭]还原)。 - 日常安全操作:支持提交(
c,有暂存仅提交暂存,无暂存时提示总数并git add -A提交)、快进拉取(p,git pull --ff-only)、推送(P,无上游分支时先确认再git push -u)、抓取(f)与本地/远端分支树切换(b)。不提供reset --hard、丢弃工作区改动或强推等高危不可逆按钮。
4. 底部状态栏、/fast 开关与输入框美化
- 三段式自适应状态栏:
- 左侧:当前模型、思考强度、
[fast]状态、当前目录、Git 分支、MCP 异常计数与其他扩展状态。 - 中间:动态显示
! input needed(等待用户确认)、◐ read foo.ts · tool 3 · 18s(执行中工具与计时)或本轮结束统计(工具数、耗时、Agent 修改文件数与增删行数)。 - 右侧:上下文窗口进度条与百分比、实时/本轮输出速率
t/s(provider 未返回 token 用量时按字符宽度估算并标~)。窄窗口下按优先级自动折叠次要字段。
- 左侧:当前模型、思考强度、
- Fast 优先处理开关:点击底栏
[fast off]/[fast on](需tmux 3.8+)或输入/fast [on|off],向后续请求注入service_tier: "priority"(显式关闭发送"default"),并按服务端实际响应显示[fast ✓]或[fast fallback]。选择按会话分支与 provider 持久化。 - 项目启动预设(
,设置页):按项目目录保存新会话默认的模型、provider、思考强度、Fast 与附加启动参数(恢复历史会话或命令行显式传参时不覆盖,禁止保存 API key)。
常用快捷键与鼠标操作
| 按键 / 鼠标 | 作用 |
|---|---|
Alt+s |
(tmux 全局)在右侧 Pi 与左侧边栏之间切换焦点 |
Alt+b |
(tmux 全局)收起 / 恢复左侧边栏宽度 |
单击会话 / 1-9 |
立即切换到对应窗口(带短暂连击保护期防止误触) |
右键 / . |
打开当前行上下文菜单(会话、历史、最近任务、目录;macOS 支持 Finder,Linux 图形环境支持文件管理器) |
行尾 ✕ / 中键 / x |
关闭选中的打开会话 |
n / 顶部 [+新建] |
打开侧边栏文件夹浏览器,选定目录后按 Ctrl+n 或点 [在此目录新建会话] 启动 |
! / : / , |
跳到下个待处理会话 / 打开可搜索命令面板 / 打开设置与项目预设 |
f / / |
打开全量历史搜索页 / 当前列表快速筛选 |
t / a |
置顶或取消置顶目录 / 归档或取消归档目录 |
d / u |
删除历史会话至回收站(y 确认)/ 撤销最近一批删除 |
K |
保留或取消保留会话(防止切走时自动关闭空闲窗口) |
g / Esc |
切换到 Git 页 / 从子页面返回会话页(在会话页按 Esc 或 Tab 回到右侧 Pi) |
在右侧 Pi 输入框内也可直接执行:
/pisb [palette|search|settings|next|hide]/fast [on|off]
与其他 Pi 扩展的兼容性说明
- 状态栏与 Footer 插槽:
extensions/statusbar.ts为了把 Git 分支和其他扩展状态转发到 tmux 底栏,会将 Pi 内置 TUI footer 替换为空组件:- 请勿与
@narumitw/pi-statusline等同样接管底栏的扩展同时启用。 - 若安装了
pi-cc-extensions,请在~/.pi/agent/pi-cc-extensions.json中将enableCustomFooter设为false,并确保pi-tmux-sidebar在settings.json的packages数组中排在pi-cc-extensions之后,以便输入框单上边线包装器能叠加保留其❯提示符。
- 请勿与
- 桌面通知透传:
tmux/pisb.conf在独立pisb服务中按 tmux 版本自动分级启用透传(tmux 3.4+开启allow-passthrough all支持后台窗口通知,tmux 3.3开启allow-passthrough on支持当前可见窗格,tmux 3.2及更低版本自动跳过),原版通知扩展发送的 OSC 777 / OSC 9 通知在高版本 tmux 下可透传至外层终端,低版本也不会中断建会话。
开发与测试
npm test
所有单元与 PTY 鼠标集成测试均运行在临时目录(隔离 HOME / PI_CODING_AGENT_DIR)与独立测试 tmux socket 中,使用本地假进程与假服务,不会读取真实历史会话或发起付费模型请求。
友链
- 友链:LINUX DO —— 感谢佬友们的交流与反馈。