Shell 和编码代理 for Claude 和 Chatgpt

赋予聊天应用程序在您的本地机器上编码、构建和运行的能力。

• Claude - 集成紧密的 shell 和代码编辑工具的 MCP 服务器。
• Chatgpt - 允许自定义 gpt 通过中继服务器与您的 shell 通信。（支持 Linux、Mac 以及 WSL 上的 Windows）

⚠️ 警告：在审查命令之前，不要允许 BashCommand 工具执行，这可能导致数据丢失。

演示

更新

• [2025年3月24日] 改进了 sonnet 3.7 的编写和编辑体验，CLAUDE.md 将自动加载。

• [2025年2月16日] 现在您可以连接到 AI 使用的工作终端。请参阅下面的“attach-to-terminal”部分。

• [2025年1月15日] 引入了模式：架构师、代码编写者以及全能的 wcgw 模式。

• [2025年1月8日] 上下文保存工具，用于将相关文件路径及其描述保存在一个文件中。可以用作任务检查点或知识转移。

• [2024年12月29日] 文件写入和编辑时的语法检查现已稳定。使 initialize 工具调用变得有用；如果引用了任何仓库，则向 Claude 发送智能仓库结构。大文件处理也得到了改进。

• [2024年12月9日] Vscode 扩展以在 Claude 应用程序上粘贴上下文

🚀 亮点

• ⚡ Create, Execute, Iterate: Ask claude to keep running compiler checks till all errors are fixed, or ask it to keep checking for the status of a long running command till it's done.
• ⚡ Large file edit: Supports large file incremental edits to avoid token limit issues. Smartly selects when to do small edits or large rewrite based on % of change needed.
• ⚡ Syntax checking on edits: Reports feedback to the LLM if its edits have any syntax errors, so that it can redo it.
• ⚡ Interactive Command Handling: Supports interactive commands using arrow keys, interrupt, and ansi escape sequences.
• ⚡ File protections:
  • The AI needs to read a file at least once before it's allowed to edit or rewrite it. This avoids accidental overwrites.
  • Avoids context filling up while reading very large files. Files get chunked based on token length.
  • On initialisation the provided workspace's directory structure is returned after selecting important files (based on .gitignore as well as a statistical approach)
  • File edit based on search-replace tries to find correct search block if it has multiple matches based on previous search blocks. Fails otherwise (for correctness).
  • File edit has spacing tolerant matching, with warning on issues like indentation mismatch. If there's no match, the closest match is returned to the AI to fix its mistakes.
  • Using Aider-like search and replace, which has better performance than tool call based search and replace.
• ⚡ Shell optimizations:
  • Only one command is allowed to be run at a time, simplifying management and avoiding rogue processes. There's only single shell instance at any point of time.
  • Current working directory is always returned after any shell command to prevent AI from getting lost.
  • Command polling exits after a quick timeout to avoid slow feedback. However, status checking has wait tolerance based on fresh output streaming from a command. Both of these approach combined provides a good shell interaction experience.
• ⚡ Saving repo context in a single file: Task checkpointing using "ContextSave" tool saves detailed context in a single file. Tasks can later be resumed in a new chat asking "Resume task id". The saved file can be used to do other kinds of knowledge transfer, such as taking help from another AI.
• ⚡ Easily switch between various modes:
  • Ask it to run in 'architect' mode for planning. Inspired by adier's architect mode, work with Claude to come up with a plan first. Leads to better accuracy and prevents premature file editing.
  • Ask it to run in 'code-writer' mode for code editing and project building. You can provide specific paths with wild card support to prevent other files getting edited.
  • By default it runs in 'wcgw' mode that has no restrictions and full authorisation.
  • More details in Modes section
• ⚡ Runs in multiplex terminal Run screen -x to attach to the terminal that the AI runs commands on. See history or interrupt process or interact with the same terminal that AI uses.

主要用例示例

• 使用 Python 解决问题 X，创建并运行测试用例，并修复任何问题。在临时目录中进行
• 在我的仓库中查找具有 X 行为的代码实例
• 在我的主目录中 git 克隆 https://github.com/my/repo，然后理解项目，设置环境并构建
• 创建一个 golang htmx tailwind 网页应用，然后打开浏览器查看是否正常工作（使用 puppeteer mcp）
• 编辑或更新一个大文件
• 在一个单独的分支中创建功能 Y，然后使用 GitHub CLI 为原始分支创建 PR
• 命令 X 在 Y 目录中失败，请运行并修复问题
• 使用 X 虚拟环境运行 Y 命令
• 使用 CLI 工具创建、构建和测试一个 Android 应用程序。最后使用模拟器运行它以便我使用
• 修复我在 X 路径下的 repo 中的所有 mypy 问题
• 使用 'screen' 在后台运行我的服务器，然后在后台运行另一个 API 服务器，最后运行前端构建。持续检查这三个服务的日志以发现任何问题
• 创建全库范围的单元测试用例。遍历文件并创建测试用例。每次更新后继续运行测试。不要修改原始代码。

Claude 设置 (使用 mcp)

Mac 和 Linux

首先使用 Homebrew 安装 uv：brew install uv

（重要提示： 请使用 Homebrew 安装 uv。否则，请确保 uv 存在于全局位置如 /usr/bin/）

然后创建或更新 claude_desktop_config.json (~\Library\Application Support\Claude\claude_desktop_config.json) 文件，内容如下：

{
  "mcpServers": {
    "wcgw": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "wcgw@latest",
        "--python",
        "3.12",
        "wcgw_mcp"
      ]
    }
  }
}

之后重启 Claude 应用。

如果设置过程中遇到错误

• 如果出现类似 "uv ENOENT" 的错误，请确保已安装 uv。然后在终端中运行 'which uv'，并将其输出替换配置中的 "uv"。
• 如果仍然存在问题，请检查 uv tool run --from wcgw@latest --python 3.12 wcgw_mcp 是否能在您的终端中运行。它应该没有输出并且不退出。
• 尝试删除 ~/.cache/uv 文件夹
• 尝试使用 uv 版本 0.6.0，该版本是经过测试的。
• 使用 npx @modelcontextprotocol/inspector@0.1.7 uv tool run --from wcgw@latest --python 3.12 wcgw_mcp 调试 mcp 服务器

Windows on WSL

此 mcp 服务器仅适用于 Windows 上的 WSL。

要设置它，请安装 uv

然后添加或更新 Claude 配置文件 %APPDATA%\Claude\claude_desktop_config.json 内容如下：

{
  "mcpServers": {
    "wcgw": {
      "command": "wsl.exe",
      "args": [
        "uv",
        "tool",
        "run",
        "--from",
        "wcgw@latest",
        "--python",
        "3.12",
        "wcgw_mcp"
      ]
    }
  }
}

使用方法

等待几秒钟。如果一切顺利，你应该能看到这个图标。

在这里

然后让 Claude 执行 shell 命令、读取文件、编辑文件、运行你的代码等。

任务检查点或知识转移

• 您可以通过点击“从MCP附加”按钮并附加“KnowledgeTransfer”提示来执行任务检查点或知识转移。
• 运行“KnowledgeTransfer”提示时，将调用“ContextSave”工具，将任务描述和所有文件内容一起保存在一个文件中。系统会为该任务生成一个ID。
• 在新的聊天中，您可以输入“Resume ''”，AI随后将使用任务ID调用“Initialize”并从那里加载上下文。
• 或者，您可以直接打开生成的文件，并与另一个AI分享以获取帮助。

模式

内置有三种模式。您可以要求Claude在其中一种模式下运行，例如“使用'architect'模式”

模式	描述	允许	禁止	调用提示
Architect	旨在让您与Claude合作调查并理解您的仓库。	只读命令	文件编辑和写入工具	以mode='architect'模式运行
Code-writer	用于代码编写和开发	指定路径通配符进行编辑或写入，指定命令	不匹配指定通配符路径的文件编辑，不匹配指定通配符路径的写入	以代码编写者模式运行，仅允许'tests/**'，仅允许uv命令
wcgw**	默认模式，允许一切操作	所有操作	无	无需提示，或“以wcgw模式运行”

注意：在code-writer模式下，目前要么所有命令都被允许，要么都不被允许。如果您提供了一个允许命令列表，虽然指示Claude只运行这些命令，但实际上并没有进行检查。（开发中）

附加到工作终端以进行调查

如果您安装了screen命令，wcgw将在一个screen实例上自动运行。如果您已启动wcgw MCP服务器，可以列出screen会话：

screen -ls

记下类似于93358.wcgw.235521这样的wcgw屏幕名称，其中最后一个数字是小时-分钟-秒格式。

然后您可以使用screen -x 93358.wcgw.235521附加到该会话。

您可以安全地中断任何正在运行的命令。

您可以与终端交互，但请注意AI可能同时也在运行，这可能会与您的操作发生冲突。建议尽量减少您的交互。

您不应该使用exit或Ctrl-d退出会话，而应该使用ctrl+a+d安全分离而不破坏screen会话。

[可选] Vs code扩展

https://marketplace.visualstudio.com/items?itemName=AmanRusia.wcgw

命令：

• 选择一段文本并按下cmd+'，然后输入指令。这将切换应用程序至Claude，并粘贴包含您的指令、文件路径、工作区目录以及所选文本的内容。

Chatgpt 设置

阅读这里: https://github.com/rusiaaman/wcgw/blob/main/openai.md

示例

使用 Docker 上的 mcp 服务器

首先构建 Docker 镜像 docker build -t wcgw https://github.com/rusiaaman/wcgw.git

然后你可以更新 /Users/username/Library/Application Support/Claude/claude_desktop_config.json 文件以包含以下内容：

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=/Users/username/Desktop,dst=/workspace/Desktop",
        "wcgw",
      ]
    }
  }
}

[可选] 使用 openai API 密钥或 anthropic API 密钥进行本地 shell 访问

Openai

添加 OPENAI_API_KEY 和 OPENAI_ORG_ID 环境变量。

然后运行

uvx --from wcgw@latest wcgw_local --limit 0.1 # 成本限制 $0.1

现在你可以直接写消息，或者按回车键打开 vim 进行多行消息和文本粘贴。

Anthropic

添加 ANTHROPIC_API_KEY 环境变量。

然后运行

uvx --from wcgw@latest wcgw_local --claude

现在你可以直接写消息，或者按回车键打开 vim 进行多行消息和文本粘贴。

工具

服务器提供以下 MCP 工具：

Shell 操作：

• Initialize: 重置 shell 并设置工作区环境
  • 参数: any_workspace_path (字符串), initial_files_to_read (字符串[]), mode_name ("wcgw"|"architect"|"code_writer"), task_id_to_resume (字符串)
• BashCommand: 执行带有超时控制的 shell 命令
  • 参数: command (字符串), wait_for_seconds (整数, 可选)
  • 参数: send_text (字符串) 或 send_specials (["Enter"|"Key-up"|...]) 或 send_ascii (整数[]), wait_for_seconds (整数, 可选)

文件操作：

• ReadFiles: 从一个或多个文件中读取内容
  • 参数: file_paths (字符串[])
• WriteIfEmpty: 创建新文件或将内容写入空文件
  • 参数: file_path (字符串), file_content (字符串)
• FileEdit: 使用搜索/替换块编辑现有文件
  • 参数: file_path (字符串), file_edit_using_search_replace_blocks (字符串)
• ReadImage: 读取图像文件用于显示/处理
  • 参数: file_path (字符串)

项目管理：

• ContextSave: 保存项目上下文和文件以便知识转移或保存任务检查点以备后续恢复
  • 参数: id (字符串), project_root_path (字符串), description (字符串), relevant_file_globs (字符串[])

所有工具都支持绝对路径，并内置了针对常见错误的保护。有关详细协议信息，请参阅 MCP 规范。