Ataraxy-Labs/opensessions
GitHub: Ataraxy-Labs/opensessions
OpenSessions 是一个 tmux 侧边栏插件，通过可视化面板集中管理终端会话，实时展示 AI 代理状态、Git 分支和本地端口，支持一键切换并提供编程式 API 供外部工具集成。
Stars: 469 | Forks: 27
# 打开 sessions
[](https://opensource.org/licenses/MIT)
[](https://github.com/Ataraxy-Labs/opensessions)
tmux 就是你所需要的一切。让 tmux 再次伟大 :)
当你的 sessions、agents 和 localhost 标签页开始倍增时，`opensessions` 是 `tmux` 的一个侧边栏。
它存在于你现有的 tmux 工作流中而不是替代它：一个小巧的面板，用于切换 session、查看 agent 状态、显示 repo 面包屑导航，以及快速跳转回正确的终端。
目前 tmux 是唯一受支持的 mux。代码库中有较早的 zellij 集成代码，但还不够稳定，无法作为受支持的功能进行文档说明；我们正在寻找希望帮助其恢复到支持标准的维护者。
## 使用 TPM 安装
前置条件：
- `tmux`
- `bun`
- [TPM](https://github.com/tmux-plugins/tpm)
将以下内容添加到 `~/.tmux.conf` 中：
```
set -g @plugin 'Ataraxy-Labs/opensessions'
```
然后重新加载 tmux 并安装插件：
```
tmux source-file ~/.tmux.conf
~/.tmux/plugins/tpm/bin/install_plugins
```
使用 `prefix o → s` 打开侧边栏。
TPM 会将代码库克隆到 `~/.tmux/plugins/opensessions`。它不会安装独立的 `opensessions` 二进制文件。`opensessions` 会通过你本地安装的 `bun` 从该检出目录运行。
如果你希望通过单条 shell 命令完成相同的设置：
```
grep -q "Ataraxy-Labs/opensessions" ~/.tmux.conf 2>/dev/null || printf '\nset -g @plugin '\''Ataraxy-Labs/opensessions'\''\n' >> ~/.tmux.conf && tmux source-file ~/.tmux.conf && ~/.tmux/plugins/tpm/bin/install_plugins
```
## 更新
使用 TPM 的内置更新（`prefix + U`）或运行：
```
~/.tmux/plugins/tpm/bin/update_plugins opensessions
```
插件在更新后会自动重启服务器，以便加载新代码。如果侧边栏之前是打开的，可以使用 `prefix o → s` 重新开启。
## 卸载
在移除插件文件**之前**运行卸载脚本——它会清理 tmux 的 hooks、按键绑定、侧边栏面板以及环境变量，否则这些内容会持续存在并导致故障：
```
sh ~/.tmux/plugins/opensessions/integrations/tmux-plugin/scripts/uninstall.sh
```
然后从 `~/.tmux.conf` 中移除 `set -g @plugin 'Ataraxy-Labs/opensessions'` 这一行，并运行 `prefix + alt + u`（TPM 卸载）。
## 支持状态
- `@opensessions/mux-tmux` 和 tmux 插件流程受支持。
- `@opensessions/mux-zellij` 仍处于实验阶段。
- 该代码库围绕可运行的应用、可复用的包以及宿主集成，为贡献者进行了组织。
## 当前功能
- 跨 session 的实时 agent 状态，支持 Amp, Claude Code, Codex 和 OpenCode。
- 针对每个线程的 `done`、`error` 和 `interrupted` 状态的未读标记。
- UI 中的 session 上下文：列表中的分支、详情面板中的工作目录、线程名称以及检测到的 localhost 端口。
- 编程式元数据 API：agents 和脚本可通过 HTTP 将状态、进度和日志推送到侧边栏。
- 使用 `j`/`k`、方向键、`Tab`、`1`-`9` 快速切换，支持 session 重新排序、隐藏/恢复、创建和终止操作。
- `prefix o → s` 和 `prefix o → t` 用于侧边栏聚焦和开关，`prefix o → 1` 到 `9` 用于快速切换，可选的无 prefix 快捷键，应用内主题切换，以及用于更多 mux 提供者或监听器的插件 hooks。
- Bun 工作区、源码优先执行，以及运行在 `127.0.0.1:7391` 上的本地服务器。
## 编程式 API
脚本和 agents 可以通过 HTTP 将自定义元数据推送到侧边栏——无需二进制文件：
```
# 在 session 上设置状态标签
curl -X POST http://127.0.0.1:7391/set-status \
-H 'content-type: application/json' \
-d '{"session":"my-app","text":"Deploying","tone":"warn"}'
# 设置进度
curl -X POST http://127.0.0.1:7391/set-progress \
-H 'content-type: application/json' \
-d '{"session":"my-app","current":3,"total":10,"label":"services"}'
# 推送日志条目
curl -X POST http://127.0.0.1:7391/log \
-H 'content-type: application/json' \
-d '{"session":"my-app","message":"Tests passed","source":"ci","tone":"success"}'
```
端点：`/set-status`、`/set-progress`、`/log`、`/clear-log`、`/notify`
提示音/类型：`neutral`、`info`、`success`、`warn`、`error`——每一种都有独特的图标和颜色。
完整参考：[docs/reference/programmatic-api.md](./docs/reference/programmatic-api.md)
## 本地开发
从本地克隆进行冒烟测试：
```
git clone https://github.com/Ataraxy-Labs/opensessions.git
cd opensessions
bun install
bun test
bun run start:tui
```
这会启动侧边栏客户端，并在需要时自动启动服务器。
有关包含快捷键、故障排除和配置选项的完整 tmux 工作流，请遵循以下指南。
## 文档
- [在 tmux 中开始使用](./docs/tutorials/get-started-in-tmux.md)
- [设置 Ghostty 快捷键](./docs/how-to/set-up-ghostty-shortcuts.md)
- [配置参考](./docs/reference/configuration.md)
- [功能与快捷键参考](./docs/reference/features-and-keybindings.md)
- [编程式 API 参考](./docs/reference/programmatic-api.md)
- [架构说明](./docs/explanation/architecture.md)
- [契约与扩展接口](./CONTRACTS.md)
- [插件编写指南](./PLUGINS.md)
## 一些具体细节
- Session 排序会持久化保存在 `~/.config/opensessions/session-order.json` 中。
- Amp 监听器会读取 `~/.local/share/amp/threads/*.json`，并在某个线程在那里被查看时，清除 Amp 的 `session.json` 中的未读状态。
- Claude Code 监听器会读取 `~/.claude/projects/` 中的 JSONL 记录。
- Codex 监听器会读取 `~/.codex/sessions/` 或 `$CODEX_HOME/sessions/` 中的 JSONL 记录文件，并从 `turn_context.cwd` 解析出 session。
- OpenCode 监听器会轮询 `~/.local/share/opencode/opencode.db` 中的 SQLite 数据库。
- 隐藏的侧边栏会被存放在名为 `_os_stash` 的 tmux session 中，这样它们无需重启侧边栏进程即可恢复。
- 点击检测到的端口会打开 `http://localhost:`。
## 代码库布局
### Apps (应用)
- `apps/server` —— Bun 服务器引导程序，负责将内置的 mux 提供者和 agent 监听器连接起来
- `apps/tui` —— 使用 Solid 构建的 OpenTUI 侧边栏客户端，以及标准的侧边栏启动脚本
### Packages (包)
- `packages/runtime` —— 共享运行时逻辑：tracker、配置、插件加载器、服务器内部机制、主题、排序
- `packages/mux/contract` —— 作为 `@opensessions/mux` 暴露的 mux 契约和能力守卫
- `packages/mux/providers/tmux` —— 作为 `@opensessions/mux-tmux` 暴露的 tmux 提供者
- `packages/mux/providers/zellij` —— 作为 `@opensessions/mux-zellij` 暴露的实验性 zellij 提供者
- `packages/mux/tmux-sdk` —— 底层的类型化 tmux 绑定，供 tmux 相关代码使用
### Integrations (集成)
- `opensessions.tmux` —— 面向用户的 TPM 根入口点
- `integrations/tmux-plugin` —— 面向 tmux 的脚本和宿主集成粘合代码
## 当前限制
- 该应用目前实际上固定绑定在 `127.0.0.1:7391`。
- `theme`、`sidebarWidth`、`sidebarPosition`、`plugins` 和 `mux` 已在运行时中接入；其他类型化的配置字段尚未全部生效。
- 核心中存在内联主题对象，但运行中的服务器只持久化并广播主题名称。
## Star History
[](https://star-history.com/#Ataraxy-Labs/opensessions&Date)
## 许可证
MIT
当你的 sessions、agents 和 localhost 标签页开始倍增时，`opensessions` 是 `tmux` 的一个侧边栏。
它存在于你现有的 tmux 工作流中而不是替代它：一个小巧的面板，用于切换 session、查看 agent 状态、显示 repo 面包屑导航，以及快速跳转回正确的终端。
目前 tmux 是唯一受支持的 mux。代码库中有较早的 zellij 集成代码，但还不够稳定，无法作为受支持的功能进行文档说明；我们正在寻找希望帮助其恢复到支持标准的维护者。
## 使用 TPM 安装
前置条件：
- `tmux`
- `bun`
- [TPM](https://github.com/tmux-plugins/tpm)
将以下内容添加到 `~/.tmux.conf` 中：
```
set -g @plugin 'Ataraxy-Labs/opensessions'
```
然后重新加载 tmux 并安装插件：
```
tmux source-file ~/.tmux.conf
~/.tmux/plugins/tpm/bin/install_plugins
```
使用 `prefix o → s` 打开侧边栏。
TPM 会将代码库克隆到 `~/.tmux/plugins/opensessions`。它不会安装独立的 `opensessions` 二进制文件。`opensessions` 会通过你本地安装的 `bun` 从该检出目录运行。
如果你希望通过单条 shell 命令完成相同的设置：
```
grep -q "Ataraxy-Labs/opensessions" ~/.tmux.conf 2>/dev/null || printf '\nset -g @plugin '\''Ataraxy-Labs/opensessions'\''\n' >> ~/.tmux.conf && tmux source-file ~/.tmux.conf && ~/.tmux/plugins/tpm/bin/install_plugins
```
## 更新
使用 TPM 的内置更新（`prefix + U`）或运行：
```
~/.tmux/plugins/tpm/bin/update_plugins opensessions
```
插件在更新后会自动重启服务器，以便加载新代码。如果侧边栏之前是打开的，可以使用 `prefix o → s` 重新开启。
## 卸载
在移除插件文件**之前**运行卸载脚本——它会清理 tmux 的 hooks、按键绑定、侧边栏面板以及环境变量，否则这些内容会持续存在并导致故障：
```
sh ~/.tmux/plugins/opensessions/integrations/tmux-plugin/scripts/uninstall.sh
```
然后从 `~/.tmux.conf` 中移除 `set -g @plugin 'Ataraxy-Labs/opensessions'` 这一行，并运行 `prefix + alt + u`（TPM 卸载）。
## 支持状态
- `@opensessions/mux-tmux` 和 tmux 插件流程受支持。
- `@opensessions/mux-zellij` 仍处于实验阶段。
- 该代码库围绕可运行的应用、可复用的包以及宿主集成，为贡献者进行了组织。
## 当前功能
- 跨 session 的实时 agent 状态，支持 Amp, Claude Code, Codex 和 OpenCode。
- 针对每个线程的 `done`、`error` 和 `interrupted` 状态的未读标记。
- UI 中的 session 上下文：列表中的分支、详情面板中的工作目录、线程名称以及检测到的 localhost 端口。
- 编程式元数据 API：agents 和脚本可通过 HTTP 将状态、进度和日志推送到侧边栏。
- 使用 `j`/`k`、方向键、`Tab`、`1`-`9` 快速切换，支持 session 重新排序、隐藏/恢复、创建和终止操作。
- `prefix o → s` 和 `prefix o → t` 用于侧边栏聚焦和开关，`prefix o → 1` 到 `9` 用于快速切换，可选的无 prefix 快捷键，应用内主题切换，以及用于更多 mux 提供者或监听器的插件 hooks。
- Bun 工作区、源码优先执行，以及运行在 `127.0.0.1:7391` 上的本地服务器。
## 编程式 API
脚本和 agents 可以通过 HTTP 将自定义元数据推送到侧边栏——无需二进制文件：
```
# 在 session 上设置状态标签
curl -X POST http://127.0.0.1:7391/set-status \
-H 'content-type: application/json' \
-d '{"session":"my-app","text":"Deploying","tone":"warn"}'
# 设置进度
curl -X POST http://127.0.0.1:7391/set-progress \
-H 'content-type: application/json' \
-d '{"session":"my-app","current":3,"total":10,"label":"services"}'
# 推送日志条目
curl -X POST http://127.0.0.1:7391/log \
-H 'content-type: application/json' \
-d '{"session":"my-app","message":"Tests passed","source":"ci","tone":"success"}'
```
端点：`/set-status`、`/set-progress`、`/log`、`/clear-log`、`/notify`
提示音/类型：`neutral`、`info`、`success`、`warn`、`error`——每一种都有独特的图标和颜色。
完整参考：[docs/reference/programmatic-api.md](./docs/reference/programmatic-api.md)
## 本地开发
从本地克隆进行冒烟测试：
```
git clone https://github.com/Ataraxy-Labs/opensessions.git
cd opensessions
bun install
bun test
bun run start:tui
```
这会启动侧边栏客户端，并在需要时自动启动服务器。
有关包含快捷键、故障排除和配置选项的完整 tmux 工作流，请遵循以下指南。
## 文档
- [在 tmux 中开始使用](./docs/tutorials/get-started-in-tmux.md)
- [设置 Ghostty 快捷键](./docs/how-to/set-up-ghostty-shortcuts.md)
- [配置参考](./docs/reference/configuration.md)
- [功能与快捷键参考](./docs/reference/features-and-keybindings.md)
- [编程式 API 参考](./docs/reference/programmatic-api.md)
- [架构说明](./docs/explanation/architecture.md)
- [契约与扩展接口](./CONTRACTS.md)
- [插件编写指南](./PLUGINS.md)
## 一些具体细节
- Session 排序会持久化保存在 `~/.config/opensessions/session-order.json` 中。
- Amp 监听器会读取 `~/.local/share/amp/threads/*.json`，并在某个线程在那里被查看时，清除 Amp 的 `session.json` 中的未读状态。
- Claude Code 监听器会读取 `~/.claude/projects/` 中的 JSONL 记录。
- Codex 监听器会读取 `~/.codex/sessions/` 或 `$CODEX_HOME/sessions/` 中的 JSONL 记录文件，并从 `turn_context.cwd` 解析出 session。
- OpenCode 监听器会轮询 `~/.local/share/opencode/opencode.db` 中的 SQLite 数据库。
- 隐藏的侧边栏会被存放在名为 `_os_stash` 的 tmux session 中，这样它们无需重启侧边栏进程即可恢复。
- 点击检测到的端口会打开 `http://localhost:标签：Agent状态监控, Bun, CLI, Git分支显示, tmux插件, TPM, WiFi技术, Zellij, 会话切换, 多路复用器, 威胁情报, 开发者工具, 开源, 快捷切换, 本地开发环境, 标签页管理, 终端UI, 终端会话管理器, 终端侧边栏, 终端复用, 终端工作流