workmux

workmux

workmux 将 Git worktree 与 tmux 窗口配对，用于并行开发。每个 worktree 都是一个隔离的工作区，拥有自己的分支、终端状态和 AI Agent。

如果用户要求你创建 worktree 或分派任务（例如，"/workmux add ..."），你就是调度者。 编写提示词文件并运行命令。不要先探索、阅读或研究代码库。使用你已有的上下文。worktree Agent 会完成所有工作。

在项目中打开 Agent

当用户要求在 <project> 中打开或启动新的 Agent 时，将项目名称视为 tmux 会话名称。确定项目目录；如果 tmux 会话已存在，则复用该会话；如果不存在，则创建会话。在该会话的新窗口中启动 Agent，并将项目目录设为其工作目录。使用用户指定的 Agent，或已配置的默认 Agent。这指的是在 tmux 中运行终端 Agent，而不是在助手应用中新建聊天。

对于现有会话：

tmux new-window -d -P -F '#{window_id}' -t <project> -n <name> \
  -c <project-path> <agent>

如果会话不存在，则在其第一个窗口中启动 Agent 并创建会话：

tmux new-session -d -P -F '#{window_id}' -s <project> -n <name> \
  -c <project-path> <agent>

使用 tmux 会话元数据确定现有项目路径，例如 tmux list-sessions -F '#{session_name}\t#{session_path}'。如果元数据已提供路径，则避免列出目录。使用 tmux new-window -d -P -F '#{window_id}' ... 创建窗口，以返回新窗口 ID；后续操作使用该 ID，不要再次列出窗口。用户要求切换时，将客户端查找和切换合并到一次工具调用中。仅在用户要求时才切换。如果命令成功的结果已能确认操作完成，则避免冗余的验证调用。

如果单独的 worktree 明显有利于完成任务，则从目标仓库运行 workmux add。传入 --parent-session <project>，将 Agent 放入指定的 tmux 会话。使用已配置的默认 Agent；如果用户指定了 Agent，则传入 -a <agent>。如有需要，Workmux 会创建父会话。否则，使用现有的项目检出目录。

检查 Agent 状态

复用已知的会话、路径和句柄。如果句柄未知，先检查会话的协调器或仪表板。

在一次工具调用中，批量运行相关 Agent 的 workmux status 和 workmux capture <handle> -n 50。跳过空闲的 shell 和无关项目。报告任务、进展、阻碍因素和完成依据；情况明确后即停止。

核心概念

• 句柄：worktree 目录名称，由分支名称转换而来（slugify）。用于在所有命令中标识 worktree
• Worktree 目录：默认位于 <project>__worktrees/<handle>，与项目根目录处于同级
• 窗口前缀：tmux 窗口默认命名为 wm-<handle>（可通过 window_prefix 配置）
• Agent 状态：Agent 通过钩子报告状态：working（工作中）、waiting（需要输入）、done（已完成）

命令

创建 worktree

workmux add <branch-name>

创建 git worktree，执行文件操作和钩子，按照配置的窗格布局创建 tmux 窗口，并切换到该窗口。

主要标志：

• --pr <number|url>：按编号或完整 URL 将 GitHub 拉取请求检出到新的 worktree 中。本地分支默认使用 PR 头部分支名称。传入 <branch-name> 可覆盖该名称，例如： workmux add --pr https://github.com/owner/repo/pull/123 custom-name。需要经过身份验证的 gh。
• -b, --background：创建 worktree，但不切换到该 worktree
• -p <text>：为 AI Agent 窗格提供内联提示词
• -P <file>：从文件读取提示词
• -e, --prompt-editor：在 $EDITOR 中编写提示词
• -A, --auto-name：通过 LLM 根据提示词生成分支名称
• -a <agent>：覆盖 Agent（多 worktree 模式下可指定多个 Agent）
• -w, --with-changes：将未提交的更改移至新 worktree
• --base <branch>：基于指定分支创建分支
• --name <name>：覆盖 worktree 句柄
• --target-name <name>：覆盖 workmux 管理的 tmux 窗口或会话名称
• --parent-session <session>：将窗口模式的目标放入此 tmux 会话中；如果该父会话不存在，则创建它
• -o, --open-if-exists：如果 worktree 已存在，则打开它（幂等）
• -W, --wait：阻塞，直到 tmux 窗口关闭
• -n, --count <N>：创建 N 个 worktree 实例
• --foreach <matrix>：根据变量矩阵创建 worktree
• --no-hooks, --no-file-ops, --no-pane-cmds：跳过设置步骤

不使用复用器创建

workmux add <branch-name> --headless --json

执行文件操作和创建后钩子，但不创建窗口或启动 Agent。无需运行中的复用器。--json 需要 --headless，并返回一份 JSON 回执，其中包含句柄、worktree 路径 和生效的工作目录；钩子输出会写入 stderr。

请使用明确的本地分支名称。支持 --base、--name、--no-hooks 和 --no-file-ops，但不支持 PR 检出、提示词、--background 或其他 复用器/Agent 选项。worktree 会一直保留，直到被移除：使用 workmux remove <handle> 清理，或稍后使用 workmux open <handle> 打开窗口。

列出 worktree

workmux list          # all worktrees
workmux list --pr     # with GitHub PR status
workmux list <name>   # filter by handle or branch

显示分支、Agent 状态、tmux 窗口状态和未合并的提交。

合并分支

workmux merge                 # merge current branch into main
workmux merge <branch>        # merge specific branch
workmux merge --rebase        # rebase before merging (linear history)
workmux merge --squash        # squash all commits into one
workmux merge --into <branch> # merge into a different target branch
workmux merge --keep          # merge but keep worktree/window/branch
workmux merge --notification  # show system notification on success

合并分支，删除 tmux 窗口，移除 worktree，并删除本地分支。完整工作流（提交、变基，然后合并）请使用 /merge 技能。

移除 worktree

workmux remove                # current worktree
workmux remove <name>...      # specific worktrees
workmux rm --gone             # worktrees whose remote branch was deleted
workmux rm --all              # all worktrees
workmux rm -f <name>          # force, skip confirmation
workmux rm --keep-branch      # keep the branch, remove worktree + window

打开 / 关闭窗口

workmux open <name>           # open or switch to tmux window
workmux open --new            # force a new window (creates suffix -2, -3)
workmux open <name> -p "..."  # open with a prompt for agent panes
workmux close <name>          # close tmux window, keep worktree

与其他 Agent 交互

这些命令通过 worktree 句柄指定 Agent。如果在当前仓库中找不到该句柄，workmux 会在全局范围搜索所有活跃 Agent。名称冲突时，使用 project:handle 语法消除歧义。

# Check agent statuses
workmux status                          # all agents
workmux status auth api-tests           # specific agents

# Wait for agents
workmux wait agent-a agent-b            # block until done
workmux wait agent-a --timeout 3600     # with timeout (seconds)
workmux wait agent-a agent-b --any      # wait for first to finish
workmux wait agent-a --status working   # wait for specific status

# Read agent terminal output
workmux capture agent-a                 # last 200 lines (default)
workmux capture agent-a -n 50           # last 50 lines

# Send instructions to an agent
workmux send agent-a "fix the tests"    # short message
workmux send agent-a "/merge"           # send a skill command
workmux send agent-a -f followup.md     # from file
workmux send myproject:docs "update the API section"  # cross-project

# Run shell commands in an agent's worktree
workmux run agent-a -- pytest tests/    # wait and stream output
workmux run agent-a -b -- npm run build # run in background

其他命令

workmux path <name>           # print worktree filesystem path
workmux dashboard             # TUI dashboard of all active agents
workmux config edit           # open global config in $EDITOR
workmux config reference      # print default config with all options documented
workmux init                  # generate .workmux.yaml in current project

配置

分为两个级别：全局（~/.config/workmux/config.yaml）和项目级（.workmux.yaml）。项目配置会覆盖全局配置。

关键选项

agent: claude                    # default agent for <agent> placeholder
merge_strategy: rebase           # merge, rebase, or squash
mode: window                     # window or session

panes:
  - command: <agent>             # <agent> resolves to configured agent
    focus: true
  - split: horizontal            # second pane with shell

files:
  copy:
    - .env                       # copy from main worktree
  symlink:
    - node_modules               # symlink from main worktree

post_create:
  - '<global>'                   # include global hooks
  - npm install                  # project-specific setup

base_branch: develop             # default base for new worktrees
window_prefix: wm-               # tmux window name prefix

在项目配置数组中使用 '<global>' 可包含全局值。

如需查看记录了所有选项的完整配置参考，请运行 workmux config reference。

Agent 检测

内置 Agent（claude、gemini、codex、opencode、kiro-cli、 vibe）会在窗格命令中自动检测，并自动注入提示词。<agent> 占位符会解析为已配置的 Agent。

常见工作流

完成工作：直接合并

使用 /merge 一步完成提交、变基到基准分支和合并。此操作会清理 worktree、tmux 窗口和分支。

完成工作：基于 PR

1. 提交更改
2. git push -u origin HEAD
3. 使用 /open-pr 编写 PR 描述并在浏览器中打开
4. PR 在远程合并后，使用 workmux rm --gone 清理

委派任务

使用 /worktree 将任务拆分给并行运行的 worktree Agent。Agent 会编写提示词文件并运行 workmux add -b -P <file>。

如需协调完整生命周期（启动、监控、合并），请使用 /coordinator。

跨项目创建 worktree

workmux add 会在当前工作仓库中创建 worktree。将 命令的工作目录设为目标项目，并传入 --parent-session，即可将受管理的窗口直接放入指定的 tmux 会话。工作目录和 tmux 会话彼此独立。后台调用和 Agent 工具调用可能无法获取 $TMUX_PANE，因此在需要指定放置位置时，协同调度应始终传入 --parent-session。如果父会话不存在，Workmux 会创建它，因此不要使用 tmux new-window 或 tmux new-session 来初始化会话。

# Run with the command working directory set to <project-path>
workmux add <branch> -b -P <prompt-file> --parent-session <session>

仅当受管理的 tmux 目标需要使用与 worktree 默认名称不同的名称时，才使用 --target-name <name>。在 目标仓库中运行 workmux 命令，这样它才能从正确的 Git 仓库和基分支创建 worktree。

分派任务前不要进行调研。使用你已有的上下文，但不要为了编写提示词而探索或阅读代码。Worktree Agent 可以通过绝对路径读取其他项目中的文件，因此请通过路径引用其他项目，并让 Agent 自行探索。

相关技能

• /merge：提交、变基并合并当前分支
• /rebase：使用智能冲突解决进行变基
• /worktree：将任务委派给并行 worktree Agent
• /coordinator：协调多个 Agent（启动、监控、合并）
• /open-pr：编写 PR 描述并在浏览器中打开