Claude Crew 🤖

English | 日本語

Claude Crew 是一个使用 Claude Desktop 和模型上下文协议 (MCP) 创建像 OpenHands 这样的自主编码代理的工具。与专注于实时协作的编码助手（如 Cline）不同，Claude Crew 旨在创建可以自主处理任务的代理。它擅长委派低复杂度的任务，并使非工程师仅使用自然语言即可实现功能。

概念

Claude Crew 专注于三个关键要素，以最大限度地提高 Claude Desktop 的性能：

• 🎯 通过高效的上下文窗口使用来最大化成本效率
• 🧪 优先考虑通过单元测试进行操作验证，而不是通过浏览器集成，以获得更好的 token 成本性能
• 🔄 提供项目优化的 MCP 和上下文信息，而不是通用的文件系统操作和 shell MCP

要求

• Claude Desktop
• 用于嵌入的 OpenAI API 密钥（可选 - 但建议用于更好地理解上下文）
• Docker 和 Docker Compose（使用自定义数据库时不需要）
• Node.js >= v20

工作原理

Claude Crew 提供了一个配置 CLI 和 MCP 服务器。

CLI 以交互方式配置项目信息，并提供反映项目信息的 MCP 工具和自定义指令。

任务按以下流程处理：

1. 任务接收

   • 接收来自用户的任务请求

2. 项目信息提供

   • 自动调用 prepare 工具来：
     • 更新依赖项
     • 更新 RAG 索引
     • 拉取最新的 Git 更改（如果已配置）
   • 向 LLM 提供：
     • 项目结构
     • 相关源代码
     • 相关文档
     • 记忆库知识

3. 自主任务执行

   • Linter 和单元测试会自动执行文件操作并提供反馈
   • 根据反馈结果实施必要的更正

在每个步骤中获得的信息都经过优化，以有效利用 LLM 的上下文窗口。

快速开始

项目设置

移动到您的项目目录并运行设置：

$ cd /path/to/your-project
$ npx claude-crew@latest setup

配置文件将在 .claude-crew 下通过交互式设置过程生成。

注意: Claude Crew 可以同时用于多个项目。每个项目都会生成自己唯一的配置，并且工具设置会使用特定于项目的命名来创建，以防止冲突。例如：

// 项目 A: /path/to/project-a/.claude-crew/mcp.json
{
  "tools": {
    "project_a_run_test": { ... },
    "project_a_check_types": { ... }
  }
}

// 项目 B: /path/to/project-b/.claude-crew/mcp.json
{
  "tools": {
    "project_b_run_test": { ... },
    "project_b_check_types": { ... }
  }
}

提示: 为了更轻松地进行项目管理，我们建议将使用 Claude Crew 的项目克隆到单独的存储库中。这使您可以独立管理每个项目的配置和状态。

Claude Desktop 设置

1. 将 MCP 设置从 .claude-crew/mcp.json 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json
2. 启动 Claude Desktop 并创建一个新项目
3. 将 .claude-crew/instruction.md 的内容添加到项目的自定义指令中

设置完成！🎉

故障排除

如果您在使用 Claude Crew 时遇到问题，以下是一些常见的解决方案：

MCP 服务器无法启动

如果 MCP 服务器无法启动，可能是由于使用了过时的配置格式。尝试以下操作：

1. 检查您的 claude_desktop_config.json 是否与 .claude-crew/mcp.json 中的格式匹配
2. 使用 .claude-crew/mcp.json 中的最新格式更新 Claude Desktop 中的 MCP 配置
3. 如果问题仍然存在，请参阅项目根目录中的 config.example.json 中的示例配置，并相应地调整您的设置

配置示例

有关 Claude Crew 配置的完整示例，包括所有可用选项和集成设置，请参阅项目根目录中的 config.example.json。

数据库问题

如果您遇到与数据库相关的问题，您可以重置并重新初始化数据库：

# 清理现有数据库容器和卷
$ npx claude-crew clean

# 重新初始化数据库
$ npx claude-crew setup-db

配置

以下设置可以在 .claude-crew/config.json 中自定义：

类别	设置	默认值	描述
基本
	name	项目名称	项目名称
	directory	当前目录	项目根目录
	language	"日本語"	Claude 交互的语言
Git
	git.defaultBranch	"main"	默认 Git 分支名称
	git.autoPull	true	是否在 prepare 期间自动拉取最新更改
命令
	commands.install	"pnpm i"	安装依赖项的命令
	commands.build	"pnpm build"	构建命令
	commands.test	"pnpm test"	测试执行命令
	commands.testFile	"pnpm vitest run <file>"	单个文件测试命令。 <file> 替换为绝对路径
	commands.checks	["pnpm tsc -p . --noEmit"]	验证命令，如类型检查
	commands.checkFiles	["pnpm eslint <files>"]	特定于文件的验证命令。 <files> 替换为路径列表
数据库
	database.url	"postgresql://postgres:postgres@127.0.0.1:6432/claude-crew-embeddings"	PostgreSQL 连接 URL。 当 customDb 为 true 时，使用您自己的 DB URL
	database.port	6432	内置 Docker DB 的端口号（当 customDb 为 true 时忽略）
	database.customDb	false	设置为 true 以使用您自己的 PostgreSQL 数据库而不是 Docker

集成

Claude Crew 提供了几个作为扩展的集成。这些可以在配置文件的 integrations 部分启用和配置。

与其他 MCP 工具的协作

虽然 Claude Crew 可以与其他 MCP 工具一起使用，但我们建议遵循以下准则：

推荐：禁用类似的工具

我们建议禁用类似的工具，例如 filesystem 和 claude-code。

原因：

• 当选择较少时，AI 代理可以更有效地完成任务
• 具有重复的功能可能会导致 AI 代理在选择最佳工具时消耗额外的上下文

浏览器操作工具

虽然您可以使用浏览器操作工具（如 playwright-mcp）来执行基于浏览器的任务，但请考虑以下事项：

• 与单元测试相比，基于浏览器的操作验证往往会消耗更多的上下文
• 当单元测试可以提供足够的验证时，不建议使用浏览器操作工具
• 当单元测试具有挑战性时（例如，可视化 UI 验证、复杂的用户交互测试），请考虑使用浏览器操作工具

添加自定义指令

目前，没有内置功能可以自动集成其他工具的自定义指令。

替代方案：

• 手动附加到 CLI 生成的指令 (.claude-crew/instruction.md)
• 将其他工具的指令直接添加到您项目的自定义指令中

可用集成

TypeScript 集成

一种增强对 TypeScript 项目支持的集成。

{
  "name": "typescript",
  "config": {
    "tsConfigFilePath": "./tsconfig.json"
  }
}

设置	描述
tsConfigFilePath	TypeScript 配置文件的路径

提供的工具：

• {project_name}-search-typescript-declaration - 按标识符（函数名称、类名称、接口名称等）搜索 TypeScript 声明

RAG 集成（检索增强生成）

一种用于搜索项目中相关文档和信息的扩展。

{
  "name": "rag",
  "config": {
    "provider": {
      "type": "openai",
      "apiKey": "your-openai-api-key",
      "model": "text-embedding-ada-002"
    }
  }
}

设置	默认值	描述
provider.type	"openai"	嵌入提供程序的类型（目前仅支持 "openai"）
provider.apiKey	-	OpenAI API 密钥
provider.model	"text-embedding-ada-002"	要使用的嵌入模型

提供的工具：

• {project_name}-find-relevant-documents - 根据查询查找相关文档
• {project_name}-find-relevant-resources - 根据查询查找相关资源

记忆库

Claude Crew 创建一个 .claude-crew/memory-bank.md 文件来存储持久的项目知识。此文件在每个任务开始时自动加载，并包含以下部分：

• 项目简介
• 产品背景
• 系统模式
• 编码指南

记忆库旨在在整个项目开发过程中进行更新，作为 AI 代理的知识库。

代码片段

由于 Claude Desktop 没有自动 MCP 批准功能，因此我们提供了一个用于自动批准的脚本。这是可选的，不是强制性的。

该代码片段提供以下功能：

主要特点

• 自动工具批准：自动批准执行受信任的工具（那些以 claude-crew- 为前缀的工具）
• 消息发送控制：特别推荐用于非英语输入。 启用使用 Ctrl+Enter 发送消息（可选）

用法

1. 生成代码片段：

# 基本用法
npx claude-crew@latest create-snippet

# 禁用 Enter 键消息发送
npx claude-crew@latest create-snippet --disable-send-enter

# 指定输出文件
npx claude-crew@latest create-snippet --outfile path/to/snippet.js

2. 在 Claude Desktop 中应用：
   • 启动 Claude Desktop
   • 按 Cmd + Alt + Shift + i 打开开发者控制台
   • 将生成的代码片段内容粘贴并执行到控制台中

选项

选项	默认值	描述
--disable-send-enter	false	当为 true 时，禁用在 Enter 键按下时发送消息
--outfile	claude_crew_snippet.js	生成的代码片段的输出文件路径

CLI 命令

Claude Crew 提供以下 CLI 命令：

• setup - 交互式项目设置
• setup-db - 手动数据库设置（对重新安装很有用）
• clean - 删除 Docker 容器和卷以重置为预设置状态
• serve-mcp - 运行 MCP 服务器以进行 Claude Desktop 集成
• create-snippet - 创建 Claude Desktop 的辅助脚本
  • --disable-send-enter - 禁用在 Enter 键按下时发送消息（默认值：false）
  • --outfile - 输出文件路径（默认值：claude_crew_snippet.js）

贡献

欢迎贡献！您可以通过以下方式参与：

• 通过 Issues 报告错误和功能请求
• 通过 Pull Requests 提交改进

有关更多详细信息，请查看 /docs/contribute/README.md。

许可证

本项目根据 MIT 许可证发布。 有关详细信息，请参见 LICENSE 文件。