CCManager - AI 代码助手会话管理器

CCManager 是一个命令行应用程序，用于跨多个 Git 工作树和项目管理多个 AI 编码助手会话（Claude Code、Gemini CLI、Codex CLI、Cursor Agent、Copilot CLI、Cline CLI、OpenCode、Kimi CLI）。

https://github.com/user-attachments/assets/15914a88-e288-4ac9-94d5-8127f2e19dbf

功能特性

• 在不同的 Git 工作树中并行运行多个 AI 助手会话
• 多项目支持：通过单一界面管理多个 Git 仓库
• 支持多种 AI 编码助手（Claude Code、Gemini CLI、Codex CLI、Cursor Agent、Copilot CLI、Cline CLI、OpenCode、Kimi CLI）
• 无缝切换会话
• 可视化的会话状态指示器（忙碌、等待、空闲）
• 在应用内创建、合并和删除工作树
• 复制 Claude Code 会话数据到其他工作树以保持对话上下文
• 可配置的快捷键
• 带有自动回退支持的命令预设
• 针对不同 CLI 工具的可配置状态检测策略
• 状态变化钩子，用于自动化和通知
• Devcontainer 集成
• 自动批准（实验性功能）：使用 AI 验证自动批准安全提示

为什么选择 CCManager 而不是 Claude Squad？

这两个工具解决了相同的问题——管理多个 Claude Code 会话——但采用了不同的方法。

如果你喜欢基于 tmux 的工作流，请继续使用 Claude Squad！ 它是一个利用 tmux 强大功能进行会话管理的优秀工具。

CCManager 适合那些想要以下特性的开发者：

🚀 无 tmux 依赖

CCManager 完全独立。无需安装或配置 tmux——开箱即用。非常适合不使用 tmux 或希望将 tmux 设置与 Claude Code 管理分开的用户。

👁️ 实时会话监控

CCManager 直接在菜单中显示每个 Claude Code 会话的实际状态：

• 等待中：Claude 正在请求用户输入
• 忙碌中：Claude 正在处理
• 空闲中：准备接受新任务

Claude Squad 不会在其菜单中显示会话状态，因此很难知道哪些会话需要关注。虽然 Claude Squad 提供了 AutoYes 功能，但这绕过了 Claude Code 内置的安全确认——不推荐用于安全操作。

🎯 简单直观的界面

遵循 Claude Code 的理念，CCManager 保持简洁直观。界面简单到你可以在几秒钟内理解——无需手册。

安装

npm install -g ccmanager

本地开发

npm install
npm run build
npm start

使用方法

ccmanager

或者在不安装的情况下运行：

npx ccmanager

快捷键

默认快捷键

• Ctrl+E：从活动会话返回菜单
• Escape：取消/返回对话框

自定义快捷键

你可以通过两种方式自定义快捷键：

1. 通过 UI：从主菜单选择 全局配置 → 配置快捷键
2. 配置文件：编辑 ~/.config/ccmanager/config.json 或 .ccmanager.json 以进行每个项目的设置（参见 每项目配置）

示例配置：

// config.json (新格式)
{
  "shortcuts": {
    "returnToMenu": {
      "ctrl": true,
      "key": "r"
    },
    "cancel": {
      "key": "escape"
    }
  }
}

注意：首次使用时，shortcuts.json 中的快捷键将自动迁移到 config.json。

限制

• 快捷键必须使用修饰键（Ctrl），特殊键如 Escape 除外
• 以下组合键被保留，无法使用：
  • Ctrl+C
  • Ctrl+D
  • Ctrl+[（等同于 Escape）

每项目配置

CCManager 支持通过在 Git 仓库根目录放置 .ccmanager.json 文件来进行每项目配置。项目设置将与全局配置（~/.config/ccmanager/config.json）合并，项目设置始终优先。

有关详细的配置选项和示例，请参阅 docs/project-config.md。

支持的 AI 助手

CCManager 支持多种 AI 编码助手，并为每个助手定制了状态检测：

助手	命令	安装
Claude Code（默认）	claude	code.claude.com
Gemini CLI	gemini	github.com/google-gemini/gemini-cli
Codex CLI	codex	github.com/openai/codex
Cursor Agent	cursor-agent	cursor.com/cli
Copilot CLI	copilot	github.com/github/copilot-cli
Cline CLI	cline	github.com/cline/cline
OpenCode	opencode	opencode.ai/docs
Kimi CLI	kimi	kimi-cli.com

每个助手都有自己的状态检测策略，以正确跟踪：

• 空闲：准备好接受新输入
• 忙碌：正在处理请求
• 等待：等待用户确认

有关 CCManager 特定配置，请参阅 Gemini 支持文档。

命令配置

CCManager 支持配置用于运行 Claude Code 会话的命令和参数，并提供自动回退选项以确保可靠性。

功能特性

• 配置主命令（默认：claude）
• 设置主要参数（例如，--resume）
• 如果主配置失败，则定义回退参数
• 自动重试时不带参数作为最终回退

快速入门

1. 导航至 全局配置 → 配置命令预设
2. 设置所需的参数（例如，--resume 用于恢复会话）
3. （可选）设置回退参数
4. 保存更改

有关详细的配置选项和示例，请参阅 docs/command-config.md。

Claude Code 团队模式

当使用默认的（claude）检测策略运行 claude 命令时，CCManager 会自动将 --teammate-mode in-process 添加到 CLI 参数中。这可以防止 Claude Code 的代理团队功能与 ccmanager 基于 PTY 的会话管理之间发生冲突。

• 自动：无需配置。CCManager 会为所有 claude 命令会话注入该标志。
• 覆盖：如果在预设参数中明确指定了 --teammate-mode，则以您的值优先。
• 非 claude 命令：其他 AI 助手（如 Gemini、Codex 等）不受影响。

仅在 Claude Code 的 settings.json 中设置 "teammateMode": "in-process" 是不够的，尤其是在类似 tmux 的环境中运行时，因此 CCManager 通过 CLI 参数来控制此行为。

会话数据复制

CCManager 可以在创建新的工作树（worktree）时复制 Claude Code 的会话数据（对话历史、上下文和项目状态），从而帮助您在不同分支间保持上下文。

功能

• 无缝上下文转移：在新工作树中继续对话而不会丢失上下文
• 可配置默认值：设置是否默认复制会话数据
• 每次创建时选择：在每次创建工作树时决定是否复制数据
• 安全操作：即使复制失败，工作树创建仍会成功

工作原理

在创建新工作树时，CCManager 会：

1. 询问是否从当前工作树复制会话数据
2. 将所有会话文件从 ~/.claude/projects/[source-path] 复制到 ~/.claude/projects/[target-path]
3. 保留对话历史、项目上下文和 Claude Code 状态
4. 允许在新工作树中立即继续对话

配置

1. 导航至 全局配置 → 配置工作树
2. 切换 复制会话数据 以设置默认行为
3. 保存更改

默认选项（复制或重新开始）将在创建新工作树时预先选择。

使用场景

• 功能开发：在创建功能分支时复制会话数据以保持项目上下文
• 实验：在测试无关更改时重新开始
• 协作：在团队工作树之间共享会话状态
• 上下文保留：在多个开发分支中维持长时间对话

状态变更钩子

CCManager 可以在 Claude Code 会话状态发生变化时执行自定义命令。这使得强大的自动化工作流成为可能，例如桌面通知、日志记录或与其他工具的集成。

概述

状态钩子允许您：

• 在 Claude 需要输入时收到通知
• 跟踪在不同状态中花费的时间
• 根据会话活动触发自动化
• 与 noti 等通知系统集成

有关详细设置说明，请参阅 docs/state-hooks.md。

工作树钩子

工作树钩子在创建工作树时执行自定义命令，从而实现开发环境设置的自动化。

功能

• 后创建钩子：在工作树创建后运行命令
• 环境变量：访问工作树路径、分支名称和 git 根目录
• 非阻塞执行：钩子异步运行，不会延迟操作
• 错误恢复能力：钩子失败不会阻止工作树创建

使用场景

• 设置开发依赖项（如 npm install、bundle install）
• 按分支配置 IDE 设置
• 在创建工作树时发送通知
• 初始化分支特定配置

有关配置和示例，请参阅 docs/worktree-hooks.md。

自动工作树目录生成

CCManager 可以根据分支名称自动生成工作树目录路径，从而简化工作树创建过程。

• 自动生成路径：无需手动指定目录
• 可定制模式：在模式中使用 {branch} 等占位符
• 智能清理：分支名称会自动转换为文件系统安全格式

有关详细配置和示例，请参阅 docs/worktree-auto-directory.md。

自动批准（实验性）

CCManager 可以自动批准不需要用户权限的 Claude Code 提示，从而减少手动干预，同时对敏感操作保持安全性。

功能

• 自动决策：使用 Claude（Haiku）分析提示并确定是否需要手动批准
• 自定义命令：用您自己的脚本或不同的 AI 模型替换默认验证器
• 安全回退：在发生错误或超时时始终默认手动批准
• 可中断：按任意键取消自动批准并手动审查

快速开始

1. 导航至 全局配置 → 其他与实验性功能
2. 启用 自动批准（实验性）
3. （可选）为验证配置自定义命令

有关详细配置和使用，请参阅 docs/auto-approval.md。

Devcontainer 集成

CCManager 支持在 devcontainer 内运行 AI 助理会话，同时将管理器本身保留在主机上。这使得沙盒开发环境能够限制网络访问，同时保持主机级别的通知和自动化。

功能

• 基于主机的管理：CCManager 在主机上运行，管理工作容器内的会话
• 无缝集成：所有现有功能（预设、状态钩子等）均可与 devcontainer 一起使用
• 安全导向：兼容 Anthropic 推荐的 devcontainer 配置
• 持久状态：配置和历史记录在容器重建后仍然存在

使用方法

# 启动支持 devcontainer 的 CCManager
npx ccmanager --devc-up-command "<your devcontainer up command>" \
              --devc-exec-command "<your devcontainer exec command>"

devcontainer 集成需要以下两个命令：

• --devc-up-command：启动 devcontainer 的任何命令
• --devc-exec-command：在容器内执行的任何命令

优势

• 安全实验：运行如 claude --dangerously-skip-permissions 等命令时无风险

有关详细设置和配置，请参阅 docs/devcontainer.md。

多项目模式

CCManager 可以从单个界面管理多个 git 仓库，从而帮助您高效地组织和导航不同项目及其工作树。

快速开始

# 设置包含您的 git 项目的根目录
export CCMANAGER_MULTI_PROJECT_ROOT="/path/to/your/projects"

# 在多项目模式下运行 CCManager
npx ccmanager --multi-project

功能特性

• 自动项目发现：递归查找所有 git 仓库
• 最近项目：频繁使用的项目会显示在顶部
• 类 Vi 搜索：按 / 键过滤项目或工作树（worktrees）
• 会话持久性：切换项目时会话保持活动状态
• 可视化指示器：查看每个项目的会话计数 [活动/忙碌/等待]

导航

1. 项目列表：从所有已发现的 git 仓库中选择
2. 工作树菜单：管理所选项目的 worktrees（Git 工作树）
3. 会话视图：与您的 AI 助手交互

使用 B 键从工作树导航返回到项目列表。

有关详细配置和使用方法，请参阅 docs/multi-project.md。

Git 工作树配置

当启用 Git 的工作树配置扩展时，CCManager 可以为每个工作树显示增强的 git 状态信息。

# 启用增强的状态跟踪
git config extensions.worktreeConfig true

启用后，您将看到：

• 文件更改：+10 -5（添加/删除）
• 提交跟踪：↑3 ↓1（领先/落后于父分支）
• 父分支上下文：显示工作树创建自哪个分支

完整的设置说明和故障排除，请参阅 docs/git-worktree-config.md。

开发

# 安装依赖
npm install

# 以开发模式运行
npm run dev

# 构建
npm run build

# 运行测试
npm test

# 运行代码检查工具
npm run lint

# 运行类型检查
npm run typecheck

CCManager 快速上手指南

CCManager 是一个 CLI 工具，用于在多个 Git 工作区中管理多种 AI 编码助手会话（如 Claude Code、Gemini CLI 等）。以下是快速入门指南。

---

环境准备

系统要求

• 支持的操作系统：macOS、Linux 或 Windows（WSL2 推荐）
• Node.js 版本：16.x 或更高版本
• Git 已安装并配置

前置依赖

确保已安装以下工具：

• Node.js：推荐使用 nvm 安装和管理 Node.js。
• AI 编码助手：根据需求安装支持的 AI 工具（如 Claude Code、Gemini CLI 等）。具体安装方法请参考 Supported AI Assistants 部分。

国内用户可以通过淘宝镜像加速 npm 安装：

npm config set registry https://registry.npmmirror.com

---

安装步骤

全局安装 CCManager：

npm install -g ccmanager

验证安装是否成功：

ccmanager --version

如果需要本地开发或调试，可以克隆代码并运行：

git clone https://github.com/user-attachments/ccmanager.git
cd ccmanager
npm install
npm run build
npm start

---

基本使用

启动 CCManager：

ccmanager

或者直接通过 npx 运行（无需全局安装）：

npx ccmanager

快速开始示例

1. 启动 CCManager 后，选择要管理的 Git 仓库。
2. 创建一个新的工作区（Worktree）：
   • 在菜单中选择 Create Worktree。
   • 输入分支名称，按提示完成创建。
3. 启动 AI 编码助手会话：
   • 选择目标工作区。
   • 按默认配置启动会话（如 claude）。
4. 使用快捷键切换会话：
   • Ctrl+E：返回主菜单。
   • Escape：取消当前操作或返回上一级。

---

更多高级功能（如自定义快捷键、状态钩子等）请参考官方文档。