tmuxx

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

tmuxx

Use this skill to control tmux and worktree-based agent tasks through

tmuxx agent

通过

tmuxx agent

使用此工具来控制tmux和基于工作树的Agent任务。

Hard Rules

硬性规则

Prefer
```
tmuxx agent
```
for session/window/worktree management. If pane command passthrough fails on a target environment, fall back to raw
```
tmux send-keys
```
for shell builtins.
Always pass
```
--json
```
so outputs are machine-parseable.
Prefer deterministic workflow commands over low-level primitives:
- ```
start-task
```
- ```
task-report
```
- ```
complete-task
```
- ```
abort-task
```
Only use low-level commands (
```
split-pane
```
,
```
send-command
```
, etc.) when workflow commands cannot solve the request.

优先使用
```
tmuxx agent
```
进行会话/窗口/工作树管理。如果在目标环境中窗格命令传递失败，则退回到原生
```
tmux send-keys
```
来处理Shell内置命令。
始终传递
```
--json
```
参数，确保输出可被机器解析。
优先使用确定性工作流命令而非底层原语：
- ```
start-task
```
- ```
task-report
```
- ```
complete-task
```
- ```
abort-task
```
仅当工作流命令无法满足需求时，才使用底层命令（
```
split-pane
```
、
```
send-command
```
等）。

Standard Workflow

标准工作流

1) Start task

1) 启动任务

bash

tmuxx agent start-task <session_name> "<task prompt>" --json

Optional:

```
--branch <name>
```
```
--base-branch <branch>
```
```
--agent-command "claude -p"
```
(or other compatible command)

bash

tmuxx agent start-task <session_name> "<task prompt>" --json

可选参数：

```
--branch <name>
```
```
--base-branch <branch>
```
```
--agent-command "claude -p"
```
（或其他兼容命令）

Setup Workspace (common first operation)

配置工作区（常见初始操作）

bash

tmuxx agent create-session dev --json
tmuxx agent create-window dev --name editor --json
tmuxx agent create-window dev --name logs --json
tmuxx agent list-sessions --json

bash

tmuxx agent create-session dev --json
tmuxx agent create-window dev --name editor --json
tmuxx agent create-window dev --name logs --json
tmuxx agent list-sessions --json

2) Monitor task — with pane-level insights

2) 监控任务 — 含窗格级洞察

bash

tmuxx agent task-report <branch> --json
tmuxx agent list-worktrees --json
tmuxx agent list-sessions --json

task-report

now includes pane-level details for each task:

```
pane_details[].status
```
: "idle", "running", "waiting_for_input", "error"
```
pane_details[].needs_prompt
```
: True if pane is waiting for user input/approval (permission request, confirmation, etc.)
```
pane_details[].window_name
```
: Which window the pane is in
```
pane_details[].command
```
: What command is running

list-sessions

also includes pane-level statuses for every session, so you can see at a glance:

Which panes are actively running
Which are idle
Which are waiting for user input (permission wall, approval prompt, etc.)

bash

tmuxx agent task-report <branch> --json
tmuxx agent list-worktrees --json
tmuxx agent list-sessions --json

task-report

现在包含每个任务的窗格级详情：

```
pane_details[].status
```
: "idle"（空闲）、"running"（运行中）、"waiting_for_input"（等待输入）、"error"（错误）
```
pane_details[].needs_prompt
```
: 若窗格正在等待用户输入/确认（权限请求、确认操作等），则为True
```
pane_details[].window_name
```
: 窗格所在的窗口名称
```
pane_details[].command
```
: 当前运行的命令

list-sessions

也包含每个会话的窗格级状态，让你一目了然：

哪些窗格正在活跃运行
哪些处于空闲状态
哪些因等待用户输入而阻塞（权限墙、确认提示等）

3) Complete task

3) 完成任务

bash

tmuxx agent complete-task <branch> --test-command "<cmd>" --json

bash

tmuxx agent complete-task <branch> --test-command "<cmd>" --json

4) Abort task

4) 终止任务

bash

tmuxx agent abort-task <branch> --json

bash

tmuxx agent abort-task <branch> --json

Diagnostics / Inspection

诊断/检查

bash

tmuxx agent list-sessions --json
tmuxx agent capture-pane %0 --lines 200 --json
tmuxx agent capture-window @0 --json
tmuxx agent read-agent-log <branch> --json

run-and-capture

returns output scoped to the command you sent (not full pane history).

bash

tmuxx agent list-sessions --json
tmuxx agent capture-pane %0 --lines 200 --json
tmuxx agent capture-window @0 --json
tmuxx agent read-agent-log <branch> --json

run-and-capture

返回的输出仅局限于你发送的命令（而非完整窗格历史）。

Low-level Operations (Fallback)

底层操作（备选方案）

bash

tmuxx agent create-session <name> --json
tmuxx agent create-window <session> --name <name> --json
tmuxx agent split-pane %0 --horizontal --json
tmuxx agent send-command %0 --json -- <command text>
tmuxx agent send-text %0 --json -- <text>
tmuxx agent send-keys %0 C-c --json
tmuxx agent send-keys %0 --literal --json -- <text>
tmuxx agent run-and-capture %0 --wait-seconds 2 --lines 200 --json -- <command text>
tmuxx agent resize-pane %0 right --amount 10 --json
tmuxx agent kill-pane %0 --json
tmuxx agent kill-window @0 --json
tmuxx agent kill-session <name> --json

bash

tmuxx agent create-session <name> --json
tmuxx agent create-window <session> --name <name> --json
tmuxx agent split-pane %0 --horizontal --json
tmuxx agent send-command %0 --json -- <command text>
tmuxx agent send-text %0 --json -- <text>
tmuxx agent send-keys %0 C-c --json
tmuxx agent send-keys %0 --literal --json -- <text>
tmuxx agent run-and-capture %0 --wait-seconds 2 --lines 200 --json -- <command text>
tmuxx agent resize-pane %0 right --amount 10 --json
tmuxx agent kill-pane %0 --json
tmuxx agent kill-window @0 --json
tmuxx agent kill-session <name> --json

Deep Activity Insights (v0.3.7+)

深度活动洞察（v0.3.7+）

tmuxx now tracks activities at the pane level to provide visibility into concurrent agent workflows (inspired by Superterm's "agentic attention" concept):

tmuxx现在能够在窗格级别跟踪活动，以提供并发Agent工作流的可见性（灵感来自Superterm的"Agent注意力"概念）：

Pane Status Types

窗格状态类型

idle
: Pane is waiting at a shell prompt (bash, zsh, etc.)
running
: Pane has an active process (agent, compiler, test runner)
waiting_for_input
: Pane is expecting user input (permission request, confirmation, etc.)
error
: Pane process exited with error

idle
：窗格在Shell提示符（bash、zsh等）下等待
running
：窗格有活跃进程（Agent、编译器、测试运行器）
waiting_for_input
：窗格正在等待用户输入（权限请求、确认操作等）
error
：窗格进程因错误退出

Detecting "Needs Prompt"

检测"需要提示"

The

needs_prompt

flag detects when a pane is blocked waiting for user action. Patterns detected:

Permission requests: "permission needed", "Allow/Deny", etc.
Input prompts: "[y/n]", "yes/no", "press any key"
Approval walls: "waiting for approval", "confirm action"
Tool prompts: "Tool: execute_bash" (Superterm-style)

needs_prompt

标志可检测窗格是否因等待用户操作而阻塞。可检测的模式包括：

权限请求："permission needed"、"Allow/Deny"等
输入提示："[y/n]"、"yes/no"、"press any key"
确认墙："waiting for approval"、"confirm action"
工具提示："Tool: execute_bash"（Superterm风格）

Example Output

示例输出

json

{
  "pane_details": [
    {
      "pane_id": "%0",
      "window_name": "editor",
      "command": "claude",
      "status": "running",
      "needs_prompt": false
    },
    {
      "pane_id": "%1",
      "window_name": "logs",
      "command": "tail",
      "status": "idle",
      "needs_prompt": false
    }
  ]
}

json

{
  "pane_details": [
    {
      "pane_id": "%0",
      "window_name": "editor",
      "command": "claude",
      "status": "running",
      "needs_prompt": false
    },
    {
      "pane_id": "%1",
      "window_name": "logs",
      "command": "tail",
      "status": "idle",
      "needs_prompt": false
    }
  ]
}

Use Cases

使用场景

Batch agent coordination: Launch 8 agents, check
```
task-report
```
to see which ones are blocked on permissions
Deep session monitoring:
```
list-sessions
```
now shows pane statuses across all sessions — no more tab-cycling
Prompt detection: Automatically identify when agents hit permission walls or need user approval

批量Agent协调：启动8个Agent，通过
```
task-report
```
查看哪些因权限问题而阻塞
深度会话监控：
```
list-sessions
```
现在显示所有会话的窗格状态 — 无需再循环切换标签页
提示检测：自动识别Agent何时遇到权限墙或需要用户确认

TUI Enhancements (v0.3.9+)

TUI增强功能（v0.3.9+）

The interactive TUI (

tmuxx

) includes real-time pane activity visualization with ANSI color-rendered preview:

交互式TUI（

tmuxx

）包含实时窗格活动可视化功能，支持ANSI颜色渲染预览：

Header Legend

头部图例

Single-line header with all status indicators:

[tmuxx]  ● active  ● selected  ● attached  ▶ running  ⏸ waiting  ⎇ worktree

单行头部显示所有状态指示器：

[tmuxx]  ● active  ● selected  ● attached  ▶ running  ⏸ waiting  ⎇ worktree

Pane Status Badges

窗格状态徽章

Each pane shows inline status in the tree:

```
▶
```
= running (blue) — agent actively executing
```
⏸
```
= waiting (red) — agent blocked on permission/approval

每个窗格在树状视图中显示内联状态：

```
▶
```
= 运行中（蓝色）— Agent正在执行
```
⏸
```
= 等待中（红色）— Agent因权限/确认而阻塞

Worktree Tree Nodes (4th level)

工作树节点（第4级）

Worktree info appears as a child node under panes (green

⎇ branch-name

demo
├── editor :0 ●
│   └── zsh %0
├── build :1
│   ├── sleep %1 ▶
│   └── claude %2 ⏸
│       └── ⎇ feature-auth
└── logs :2
    └── tail %3 ▶

工作树信息作为窗格的子节点显示（绿色

⎇ branch-name

）：

demo
├── editor :0 ●
│   └── zsh %0
├── build :1
│   ├── sleep %1 ▶
│   └── claude %2 ⏸
│       └── ⎇ feature-auth
└── logs :2
    └── tail %3 ▶

Key Improvements

主要改进

ANSI color preview — terminal output renders with full colors
Context-aware footer — bindings hide when not applicable (e.g., Kill hidden with no sessions)
Prompt detection — automatically flags agents waiting for user input
Persistent theme (v0.3.11+) — theme selection saved to
```
~/.config/tmuxx/config.json
```
and restored on launch
Auto worktree detection (v0.3.12+) — any pane in a git worktree shows
```
⎇ branch
```
automatically, regardless of how it was created
Tmux status bar integration (v0.3.13+) — clickable
```
[tmuxx]
```
button in tmux status bar (top-right) to detach back to tmuxx TUI

ANSI颜色预览 — 终端输出以全彩色渲染
上下文感知页脚 — 绑定在不适用时自动隐藏（例如：无会话时隐藏"Kill"选项）
提示检测 — 自动标记等待用户输入的Agent
持久化主题（v0.3.11+）— 主题选择会保存到
```
~/.config/tmuxx/config.json
```
，并在启动时恢复
自动工作树检测（v0.3.12+）— 任何处于Git工作树中的窗格都会自动显示
```
⎇ branch
```
，无论其创建方式如何
Tmux状态栏集成（v0.3.13+）— Tmux状态栏右上角的可点击
```
[tmuxx]
```
按钮，用于切回tmuxx TUI

Error Recovery

错误恢复

When a command fails:

Re-run with identical arguments once.
Run
```
tmuxx agent task-report <branch> --json
```
(if branch-based).

Run

tmuxx agent list-sessions --json

and

tmuxx agent list-worktrees --json

If still blocked, return the exact command, error text, and suggested next command.

当命令失败时：

使用相同参数重新运行一次。
若基于分支，运行
```
tmuxx agent task-report <branch> --json
```
。

运行

tmuxx agent list-sessions --json

和

tmuxx agent list-worktrees --json

。

若仍阻塞，返回确切的命令、错误文本以及建议的下一步命令。

Known Limitations

已知限制

For historical binaries (
```
<=0.3.4
```
), pane command passthrough may fail or require awkward quoting for shell builtins (
```
cd
```
,
```
pwd
```
,
```
export
```
).
If stuck on an older binary, use raw
```
tmux send-keys -t <pane> "<text>" Enter
```
as a temporary fallback.

对于历史版本二进制文件（
```
<=0.3.4
```
），窗格命令传递可能失败，或需要对Shell内置命令（
```
cd
```
、
```
pwd
```
、
```
export
```
）使用复杂的引号转义。
若被困在旧版本二进制文件中，可临时使用原生
```
tmux send-keys -t <pane> "<text>" Enter
```
作为替代方案。

Notes

注意事项

screenshot-window

may require optional dependencies (

pip install "tmuxx[mcp]"

If using npm,
```
npm install -g tmuxx
```
installs only a wrapper. The Python
```
tmuxx
```
binary must still be available in
```
PATH
```
(
```
pipx install tmuxx
```
recommended).
Use direct
```
tmux
```
only if
```
tmuxx
```
is not installed or is broken, and explicitly state the reason.

screenshot-window

可能需要可选依赖（

pip install "tmuxx[mcp]"

）。

若使用npm，
```
npm install -g tmuxx
```
仅安装一个包装器。Python版
```
tmuxx
```
二进制文件仍需在
```
PATH
```
中可用（推荐使用
```
pipx install tmuxx
```
）。
仅当
```
tmuxx
```
未安装或损坏时，才使用原生
```
tmux
```
，并需明确说明原因。