tmux-kit

基于 agent-tmux 的人类友好 tmux 简化命令。

安装

本仓库使用 bun workspaces：

bun install

构建

bun run --cwd packages/agent-tmux build
bun run --cwd packages/tmux-kit build

用法

tmux-kit server ls

机器可读：

tmux-kit server ls --json

清理（建议先预览）：

tmux-kit server prune --dry-run

定点清理单个 stale socket（默认 dry-run）：

tmux-kit server cleanup popup-123
tmux-kit server cleanup popup-123 --no-dry-run

会话编号与导航：

tmux-kit session ensure
tmux-kit session rename work
tmux-kit session move left
tmux-kit session switch-index 2
tmux-kit window move-to-session 1

Scratchpad 与布局辅助：

tmux-kit scratchpad
tmux-kit layout toggle-orientation

命令

tmux-kit server ls [--json]
tmux-kit server prune [--dry-run] [--json]
tmux-kit server cleanup <name> [--no-dry-run] [--json]
tmux-kit servers [--json]
tmux-kit sessions [--json]
tmux-kit windows [--json]
tmux-kit panes [--json]
tmux-kit send <paneTarget> <text> [--no-enter] [--enter-delay-ms N] [--session S] [--window W] [--json]
tmux-kit read <paneTarget> [--lines N] [--session S] [--window W] [--json]
tmux-kit switch <target> [--json]
tmux-kit session ensure [--json]
tmux-kit session rename <label> [--client <tty>] [--json]
tmux-kit session move <left|right> [--client <tty>] [--json]
tmux-kit session switch-index <index> [--client <tty>] [--json]
tmux-kit window move-to-session <index> [--client <tty>] [--json]
tmux-kit scratchpad [--name <name>] [--json]
tmux-kit layout toggle-orientation [--json]

输出契约

• 成功：exit code 0；stdout 只输出结果。
• 失败：非零 exit code；stderr 以 Error: 开头。
• --json：stdout 为单行 JSON（不夹杂其他文本）。

环境变量

• AGENT_TMUX_SERVER / AGENT_TMUX_SOCKET：指定 tmux -L <name>。
• TMUX_TMPDIR：覆盖 tmux socket 目录（servers 使用）。
• --server <name> / --socket <name>：CLI 语法糖（等价于设置 AGENT_TMUX_SERVER）。

JSON 字段（稳定）

• servers --json：{ servers: [{ name, path }] }
• server prune --json：转发到 agent-tmux server prune（同一套 JSON 输出契约）
• server cleanup --json：{ target, path?, reachable?, dryRun, removed, reason? }
• sessions --json：{ sessions: [{ name }] }
• windows --json：{ windows: [{ session, index, id, name }] }
• panes --json：{ panes: [{ session, windowIndex, windowId, paneIndex, paneId, command, title }] }
• send/read --json：转发到 agent-tmux send/read（同一套 JSON 输出契约）
• switch --json：{ target, switched }
• session ensure --json：{ action, renamed, changes: [{ id, from, to }] }
• session rename --json：{ action, label, current: { id, from, to }, renamed, changes }
• session move --json：{ action, direction, swapped, renamed, changes }
• session switch-index --json：{ action, index, target: { id, name, windowIndex? }, switched }
• window move-to-session --json：{ action, index, windowId, fromSessionId, toSessionId, moved, switched }
• scratchpad --json：{ action, name, existed, created, switched, mode, scratchWindowId? }
• layout toggle-orientation --json：{ action, changed, layout?, reason? }