tmux-manager

Manages tmux sessions from a YAML config file. The script and its default config live together — the script always looks for tmux-sessions.yaml in the same directory as itself.

Script: {baseDir}/scripts/tmux-manager.py
Default config: {baseDir}/scripts/tmux-sessions.yaml
Sample config: INLINECODE3

To deploy: copy tmux-manager.py to any directory, place a tmux-sessions.yaml next to it, and run it with uv run from anywhere.

Usage

CODEBLOCK0

Flags

Selectors

Flag	Meaning
INLINECODE7	Target every session in the config
INLINECODE8

Target sessions by session_group (repeatable, comma-separated) — all windows created | | --window-group GROUP | Filter to only matching windows (repeatable, comma-separated) — can be combined with --session-group | | -s SESSION | Target a specific session by name (repeatable) |

INLINECODE13 and -s are mutually exclusive with everything else. --session-group and --window-group can be used together to scope both sessions and windows.

Actions — default is create

Flag	Meaning
(no action flag)	Create targeted sessions; skip ones already running
INLINECODE17

Output / Inspection

Flag	Meaning
INLINECODE21	Stream live pane output (Ctrl+C to stop)

Send Commands

Flag	Meaning
INLINECODE22	Send a shell command to a running session or specific window

Config & Validation

Flag	Meaning
INLINECODE23	Use an alternative config file
INLINECODE24

Check config for errors and warnings (no selector needed) | | --list-groups | List all session groups and window groups (no selector needed) |

Examples

CODEBLOCK1

Behaviour Notes

- Idempotent creates — sessions already running are skipped. Use --restart to force recreate.
--kill requires a selector — use --all --kill to kill everything managed by this config.
--tail / --send-keys accept only a single -s SESSION[:WINDOW] target.
SESSION[:WINDOW] — append :windowname to target a specific window, e.g. my-session:claude. Without it, the active window is used.
--validate does not require a selector — warns on unknown fields, catching typos like window_grou or sesion_group.
--list-groups does not require a selector — reads config only.
pre_hook / post_hook run on the host shell, not inside tmux.
pre_hook_fail: abort — stops session creation if the pre_hook exits non-zero. Default is warn (prints warning, continues).
--window-group — sessions already running are skipped unless --restart is used. On restart, only the matching windows are created.
--session-group + --window-group combined — narrows to the specified sessions first, then opens only the matching windows within them.
Sessions without a session_group are only reachable via --all or -s.

Native tmux equivalents

These operations don't need a wrapper — use tmux directly:

Operation	Native command
Kill all tmux sessions	INLINECODE50
Snapshot pane output

tmux capture-pane -p -t SESSION[:WINDOW] |

Sample Config (`tmux-sessions.yaml.sample`)

CODEBLOCK2

Full Config Reference

Field	Level	Description
INLINECODE53	session	Required. Must be unique.
INLINECODE54

tmux-manager

通过YAML配置文件管理tmux会话。脚本及其默认配置位于同一目录中——脚本始终会在自身所在目录中查找tmux-sessions.yaml。

脚本： {baseDir}/scripts/tmux-manager.py
默认配置： {baseDir}/scripts/tmux-sessions.yaml
示例配置： {baseDir}/scripts/tmux-sessions.yaml.sample

部署方式：将tmux-manager.py复制到任意目录，在其旁边放置tmux-sessions.yaml，然后从任何位置使用uv run运行。

用法

uv run {baseDir}/scripts/tmux-manager.py (--all | -s SESSION [...] | --session-group GROUP [...] [--window-group GROUP [...]] | --window-group GROUP [...]) [--kill | --restart] [--dry-run] [--list] [--config FILE]
uv run {baseDir}/scripts/tmux-manager.py --send-keys -s SESSION[:WINDOW] COMMAND
uv run {baseDir}/scripts/tmux-manager.py --tail -s SESSION[:WINDOW]
uv run {baseDir}/scripts/tmux-manager.py --validate [--config FILE]
uv run {baseDir}/scripts/tmux-manager.py --list-groups [--config FILE]

标志

选择器

标志	含义
--all	针对配置中的每个会话
--session-group GROUP

--all和-s与其他所有选项互斥。--session-group和--window-group可一起使用以限定会话和窗口范围。

操作——默认为创建

标志	含义
(无操作标志)	创建目标会话；跳过已在运行的会话
--kill

输出/检查

标志	含义
--tail -s SESSION[:WINDOW]	实时流式输出窗格内容（Ctrl+C停止）

发送命令

标志	含义
--send-keys -s SESSION[:WINDOW] cmd	向正在运行的会话或特定窗口发送shell命令

配置与验证

标志	含义
--config FILE	使用替代配置文件
--validate

检查配置中的错误和警告（无需选择器） | | --list-groups | 列出所有会话组和窗口组（无需选择器） |

示例

bash
uv run {baseDir}/scripts/tmux-manager.py --all uv run {baseDir}/scripts/tmux-manager.py --all --kill uv run {baseDir}/scripts/tmux-manager.py --all --restart uv run {baseDir}/scripts/tmux-manager.py --all --dry-run uv run {baseDir}/scripts/tmux-manager.py --all --list uv run {baseDir}/scripts/tmux-manager.py --session-group work uv run {baseDir}/scripts/tmux-manager.py --session-group work --restart uv run {baseDir}/scripts/tmux-manager.py --session-group work --list uv run {baseDir}/scripts/tmux-manager.py --kill --session-group work uv run {baseDir}/scripts/tmux-manager.py --window-group dev uv run {baseDir}/scripts/tmux-manager.py --window-group dev --restart uv run {baseDir}/scripts/tmux-manager.py --window-group claude,gemini uv run {baseDir}/scripts/tmux-manager.py --window-group uv run {baseDir}/scripts/tmux-manager.py --session-group uv run {baseDir}/scripts/tmux-manager.py -s my-session uv run {baseDir}/scripts/tmux-manager.py --kill -s my-session uv run {baseDir}/scripts/tmux-manager.py --restart -s my-session uv run {baseDir}/scripts/tmux-manager.py --send-keys -s my-session cmd uv run {baseDir}/scripts/tmux-manager.py --send-keys uv run {baseDir}/scripts/tmux-manager.py --tail -s my-session uv run {baseDir}/scripts/tmux-manager.py --validate uv run {baseDir}/scripts/tmux-manager.py --list-groups uv run {baseDir}/scripts/tmux-manager.py --all --config

行为说明

# 创建所有会话
# 终止配置中的所有会话
# 重启所有会话
# 预览将要创建的内容
# 列出所有会话的状态
# 创建会话组work中的会话
# 重启会话组work中的会话
# 列出会话组work中会话的状态
# 终止会话组work中的所有会话
# 创建会话，仅包含dev窗口
# 重启，仅包含dev窗口
# 多个组，逗号分隔
claude --window-group gemini # 等效写法
TargetTracer,N8N --window-group claude,gemini # 组合使用
# 仅创建my-session
# 仅终止my-session
# 仅重启my-session
# 发送到活动窗口
-s my-session:claude cmd # 发送到特定窗口
# 实时流式输出窗格内容
# 验证配置文件
# 列出所有组
~/my-sessions.yaml # 使用特定配置

- 幂等创建 — 已运行的会话将被跳过。使用--restart强制重新创建。
--kill需要选择器 — 使用--all --kill终止此配置管理的所有会话。
--tail / --send-keys 仅接受单个-s SESSION[:WINDOW]目标。
SESSION[:WINDOW] — 追加:windowname以定位特定窗口，例如my-session:claude。不加则使用活动窗口。
--validate 不需要选择器 — 对未知字段发出警告，捕获诸如windowgrou或sesiongroup之类的拼写错误。
--list-groups 不需要选择器 — 仅读取配置。
prehook / posthook 在主机shell中运行，而非tmux内部。
prehookfail: abort — 如果prehook退出码非零，则停止会话创建。默认为warn（打印警告，继续执行）。
--window-group — 已运行的会话将被跳过，除非使用--restart。重启时，仅创建匹配的窗口。
--session-group + --window-group组合使用 — 首先缩小到指定会话，然后仅在其中打开匹配的窗口。
没有sessiongroup的会话 — 只能通过--all或-s访问。

原生tmux等效操作

这些操作不需要包装器——直接使用tmux：

操作	原生命令
终止所有tmux会话	tmux kill-server
捕获窗格输出快照

tmux capture-pane -p -t SESSION[:WINDOW] |

示例配置 (tmux-sessions.yaml.sample)

yaml
sessions:

# ── 项目会话（无环境变量）─────────────────────────────────────────
- name: Project_1
sessiongroup: Project1
workingdir: ~/Projects/Project1
# focus: claude # 创建后选择哪个窗口（可选）
windows:
- name: claude
window_group: claude # 通过：--window-group claude 定位
command: claude --dangerously-skip-permissions --continue
- name: gemini
window_group: gemini # 通过：--window-group gemini 定位
command: gemini -y --resume
- name: shell # 无window_group — 仅通过--session-group或--all打开
# 无command = 打开一个普通shell

# ──

tmux-managertmux会话管理

tmux-manager

tmux-manager

Usage