pi-tmux-sidebar

在独立 tmux 服务中并行运行多个 Pi,左侧常驻多会话与 Git 侧边栏,底部提供实时 Agent 状态栏

Packages

Package details

extension

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 持续运行,点击或按键即可秒切。

pi-tmux-sidebar 界面预览


系统要求

  • 操作系统:macOS / Linux / Windows WSL(原生 CMD / PowerShell 不支持 tmux)
  • tmux:3.0+(兼容 Ubuntu 22.04 3.2a、Debian 12 3.3a、Ubuntu 24.04 3.4 及 macOS brew 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 扩展的兼容性说明

  1. 状态栏与 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 之后,以便输入框单上边线包装器能叠加保留其 ❯ 提示符。
  2. 桌面通知透传: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 —— 感谢佬友们的交流与反馈。

License

MIT