xlaude：使用 Git Worktree 管理 Claude 实例的 CLI 工具 – 提升你的并行开发工作流

xlaude 是什么？

xlaude 是一款命令行工具，旨在帮助开发者更高效地管理和使用 Claude 实例，尤其是在需要并行处理多个开发任务时。它利用 Git worktree 的特性，为每个 Claude 实例创建隔离的工作空间，从而实现无缝切换、智能清理和会话跟踪等功能。

xlaude 的核心功能：

• 隔离工作空间： 为每个 Claude 实例创建独立的 Git worktree，避免不同任务之间的冲突。
• 无缝切换： 快速打开和切换不同的开发上下文，提高工作效率。
• 智能清理： 安全删除包含未提交更改的 worktree，防止数据丢失。
• 会话跟踪： 记录每个 Claude 实例的对话历史，方便回顾和参考。
• 随机命名： 使用 BIP39 单词列表生成易于记忆的工作空间名称。
• 仪表盘模式： 在后台运行多个 Claude 实例，并通过交互式仪表盘进行管理（需要 tmux）。
• 管道输入支持： 与 Unix 工具集成，实现自动化工作流。
• 可配置 Agent： 使用全局命令启动你偏好的 Agent（默认为 Claude）。

安装 xlaude

你可以通过 Cargo 安装 xlaude：

cargo install xlaude

或者从源码构建：

git clone https://github.com/xuanwo/xlaude
cd xlaude
cargo build --release

Shell 补全

xlaude 支持 bash, zsh, 和 fish shell 的 tab 补全。安装后，生成并安装补全脚本：

• Bash:

xlaude completions bash > ~/.bash_completion.d/xlaude
# 或者添加到 .bashrc:
# eval "$(xlaude completions bash)"

• Zsh:

xlaude completions zsh > ~/.zfunc/_xlaude
# 然后添加到 .zshrc:
# fpath=(~/.zfunc $fpath)

• Fish:

xlaude completions fish > ~/.config/fish/completions/xlaude.fish

补全功能提供：

• 命令和子命令补全
• 动态 worktree 名称补全 (open, dir, delete, 和 rename 命令)
• 丰富的描述，显示仓库名称和会话计数 (zsh/fish)

xlaude 的使用方法：

1. 创建新的工作空间

• 使用自定义名称创建：

xlaude create feature-auth

• 使用随机名称创建：

xlaude create

• 从现有分支创建（本地或远程）：

xlaude create existing-branch

这将在 ../<repo>-<name> 创建一个新的 git worktree。如果分支不存在，它会创建一个新的分支。如果分支已经存在（本地或远程），它会从该现有分支创建 worktree。

2. 打开现有的工作空间

• 打开特定的工作空间：

xlaude open feature-auth

• 打开当前目录（如果它是一个 worktree）：

xlaude open

• 交互式选择（当不在 worktree 中时）：

xlaude open

这会切换到 worktree 目录并启动配置的 agent 命令。默认情况下，它是 claude --dangerously-skip-permissions。如果在 worktree 目录中不带参数运行，它会直接打开当前的 worktree。

3. Agent 配置

你可以配置一个全局 agent 命令，用于 open 命令和仪表盘（tmux 会话）。编辑你的 xlaude 状态文件并设置 agent 为一个完整的命令行字符串：

{
  "worktrees": {
    /* ... */
  },
  "editor": "zed",
  "agent": "codex"
}

• 默认值： 如果省略，则为 claude --dangerously-skip-permissions。
• 该值使用 shell 风格的分裂解析；支持带引号的参数。
• 避免在此处使用 shell 管道/重定向——如果需要，将它们包装在一个小脚本中，并将 agent 设置为该脚本路径。
• 同一个 agent 用于所有地方（没有每个仓库/worktree 的覆盖，没有环境变量覆盖）。
• 状态文件位置（按平台）：请参见下面的“配置”部分。

使用 Codex

要启动 Codex 而不是 Claude，请更新状态文件（在 macOS 上：~/Library/Application Support/com.xuanwo.xuanwo.xlaude/state.json）并设置：

{
  "agent": "codex --dangerously-bypass-approvals-and-sandbox"
}

当程序名称是 codex 并且没有提供位置参数时，xlaude 会自动附加 resume <session-id>，其中 <session-id> 是工作目录与所选 worktree 匹配的最新 Codex 会话。这使你可以重新打开之前的对话，而无需手动步骤。

Codex 会话日志默认在 ~/.codex/sessions 下发现。如果将会话存储在其他位置，请在运行 xlaude 之前导出 XLAUDE_CODEX_SESSIONS_DIR=/custom/path，以便 resume 逻辑可以找到它们。

4. 添加现有工作空间

• 添加当前工作空间，使用分支名称：

cd ../myproject-bugfix
xlaude add

• 使用自定义名称添加：

xlaude add hotfix

5. 列出所有工作空间

xlaude list

显示所有托管的 worktree，包括：

• 名称、仓库和路径
• 创建时间
• 最近的 Claude 会话（最多 3 个）
• 每个会话的最后一条用户消息

6. 删除工作空间

• 删除当前工作空间：

xlaude delete

• 删除特定的工作空间：

xlaude delete feature-auth

执行安全检查：

• 未提交的更改
• 未推送的提交
• 分支合并状态

必要时在删除前确认。

7. 清理无效的工作空间

xlaude clean

从状态管理中删除已使用 git worktree remove 手动删除的 worktree。

8. 重命名工作空间

xlaude rename <old_name> <new_name>

在 xlaude 管理中重命名 worktree。这只会更新 xlaude 状态，不会影响实际的 git worktree 或目录。

9. 获取 worktree 目录路径

• 获取特定 worktree 的路径：

xlaude dir feature-auth

• 交互式选择：

xlaude dir

返回 worktree 的绝对路径。用于与其他工具集成：

# 快速目录切换
cd $(xlaude dir feature-auth)

# 添加 shell 函数以方便使用 (在 .bashrc/.zshrc 中)
xcd() { cd $(xlaude dir "$@"); }
xcd feature-auth

# 在编辑器中打开
code $(xlaude dir feature-auth)
vim $(xlaude dir feature-auth)/src/main.rs

10. 交互式仪表盘（需要 tmux）

xlaude dashboard

启动一个交互式 TUI 仪表盘，用于管理多个 Claude 会话：

• 查看所有 worktree： 查看所有项目和 Claude 会话的状态
• 后台会话： 同时运行多个 Claude 实例
• 快速切换： 按 Enter 连接到会话，Ctrl+Q 返回仪表盘
• 会话预览： 查看来自后台会话的最新输出
• 键盘快捷键：
  • ↑/↓ 或 j/k: 导航项目列表
  • Enter: 连接到选定的项目
  • Ctrl+Q: 从 Claude 中分离并返回到仪表盘
  • n: 创建新的 worktree
  • d: 停止选定的 Claude 会话
  • r: 刷新列表
  • ?: 显示帮助
  • q: 退出仪表盘

注意： 仪表盘需要 tmux。 使用以下命令安装：

• macOS: brew install tmux
• Ubuntu/Debian: apt-get install tmux
• Fedora: dnf install tmux

典型工作流程：

1. 开始一个新功能：

xlaude create auth-system
xlaude open auth-system

2. 在 Claude 的帮助下开发功能。
3. 切换上下文：

xlaude open # 选择另一个工作区
# 或者，如果你已经在 worktree 目录中：
cd ../project-feature
xlaude open # 直接打开当前 worktree

4. 完成后清理：

xlaude delete auth-system
# 或者清理所有无效的 worktree：
xlaude clean

管道输入和自动化：

xlaude 支持管道输入，用于自动化和与其他 Unix 工具集成：

• 基本管道输入：

# 通过管道提供分支名称
echo "feature-x" | xlaude create
# 通过管道选择 worktree
echo "feature-x" | xlaude open
echo "feature-x" | xlaude dir

• 自动确认：

# 使用 yes 自动确认删除
yes | xlaude delete feature-x
# 使用环境变量强制 yes
XLAUDE_YES=1 xlaude delete feature-x

• 与其他工具集成：

# 与 fzf 结合使用进行模糊选择
xlaude list | fzf | xlaude open
# 用于分支的批处理操作
for branch in feature-1 feature-2; do echo $branch | xlaude create; done
# 与其他命令链接
echo "hotfix" | xlaude create && xlaude open hotfix

优先级顺序：

当有多个输入源可用时：

1. 命令行参数（最高优先级）
2. 管道输入
3. 交互式提示（最低优先级）

# CLI 参数优先于管道
echo "wrong-name" | xlaude open correct-name # 打开 "correct-name"

配置：

状态保存在特定于平台的位置：

• macOS: ~/Library/Application Support/com.xuanwo.xlaude/state.json
• Linux: ~/.config/xlaude/state.json
• Windows: %APPDATA%\xuanwo\xlaude\config\state.json

Worktree 键使用格式：<repo-name>/<worktree-name> (v0.3+)

自动从旧格式迁移。

跟踪创建时间和 Claude 会话历史记录。

环境变量：

• XLAUDE_YES: 设置为 “1” 以自动确认所有提示
• XLAUDE_NON_INTERACTIVE: 设置为 “1” 以禁用交互式提示
• XLAUDE_CLAUDE_CMD: 覆盖 Claude 命令 (默认: “claude”)

要求：

• Git with worktree support
• Claude CLI installed
• Rust (for building from source)
• tmux (optional, for dashboard mode)

许可：

Licensed under the Apache License, Version 2.0. See LICENSE for details.

总结

xlaude 是一款强大的工具，可以帮助开发者更有效地使用 Claude 进行并行开发。通过隔离工作空间、简化切换和提供智能清理功能，xlaude 提高了开发效率并减少了潜在的错误。如果你经常需要同时处理多个 Claude 实例，那么 xlaude 绝对值得一试。

---

Xuanwo/xlaude: A CLI tool for managing Claude instances with git worktree
https://github.com/Xuanwo/xlaude