Claude和其他MCP客户端的Shell和编码代理

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

wcgw是一个MCP服务器，集成了紧密的shell和代码编辑工具。

截至2026年，您可以使用wcgw的原因是它提供了完全交互式的shell体验，您可以和代理共同控制（包括发送按键操作）。 结合wcgw的VSCode扩展，将代理的shell附加到您的编辑器中，您可以获得市面上最佳的代理shell体验。 文件编辑技巧和整体的极简主义也有助于代理提高生产力。

演示

更新

• [2025年10月6日] 模型现在可以在后台运行多个命令。ZSH现在是一个受支持的shell。多路复用功能得到改进。
• [2025年4月27日] 移除了通过中继服务器对GPTs的支持。版本号大于等于5时仅支持MCP服务器。
• [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应用中粘贴上下文

🚀 突出功能

• ⚡ 创建、执行、迭代：要求claude持续运行编译器检查，直到所有错误都修复；或者要求它持续检查长时间运行命令的状态，直到完成。
• ⚡ 大文件编辑：支持大文件的增量编辑，以避免token限制问题。智能地选择何时进行小编辑或大重写，基于所需变更的百分比。
• ⚡ 编辑时的语法检查：如果其编辑存在语法错误，会向LLM报告反馈，以便它可以重做。
• ⚡ 交互式命令处理：支持使用箭头键、中断和ANSI转义序列进行交互式命令。
• ⚡ 文件保护：
  • AI至少需要读取一次文件，才能允许编辑或重写它。这避免了意外覆盖。
  • 避免在读取非常大的文件时上下文填满。文件会根据token长度进行分块。
  • 初始化时，在选择重要文件后（基于.gitignore以及统计方法），会返回提供的工 作区目录结构。
  • 基于搜索替换的文件编辑，如果它有多个匹配项，会尝试根据先前的搜索块找到正确的搜索块。否则失败（为了正确性）。
  • 文件编辑具有间距容错匹配，对缩进不匹配等问题发出警告。如果没有匹配，会向AI返回最接近的匹配项以修正其错误。
  • 使用类似Aider的搜索和替换，其性能优于基于工具调用的搜索和替换。
• ⚡ Shell优化：
  • 当前工作目录在执行任何shell命令后都会返回，以防止AI迷失方向。
  • 命令轮询会在快速超时后退出，以避免慢反馈。然而，状态检查具有基于命令的新鲜输出流等待容忍度。这两种方法的结合提供了良好的shell交互体验。
  • 支持在主交互shell旁边运行多个并发后台命令。
• ⚡ 将仓库上下文保存在单个文件中：使用"ContextSave"工具进行任务检查点，将详细上下文保存在单个文件中。稍后可以在新的聊天中输入"Resume ''"，AI应该使用任务ID调用"Initialize"并从那里加载上下文。
• ⚡ 轻松切换各种模式：
  • 要求它在'架构师'模式下运行，用于规划。受adier的架构师模式启发，先与Claude一起制定计划。这可以带来更高的准确性，并防止过早的文件编辑。
  • 要求它在'代码编写者'模式下运行，用于代码编辑和项目构建。您可以提供带有通配符支持的具体路径，以防止其他文件被编辑。
  • 默认情况下，它以没有限制和完全授权的'wcgw'模式运行。
  • 更多细节请参阅模式部分
• ⚡ 在多路复用终端中运行 使用VSCode扩展或运行screen -x附加到AI运行命令的终端。查看历史记录或中断进程或与AI使用的相同终端交互。
• ⚡ 自动加载CLAUDE.md/AGENTS.md 在项目根目录加载"CLAUDE.md"或"AGENTS.md"文件，并在初始化期间作为指令发送。全局"/.wcgw/CLAUDE.md"或"/.wcgw/AGENTS.md"文件中的指令会被加载并添加到项目特定的CLAUDE.md中。文件名区分大小写。如果存在CLAUDE.md，则附加它；否则附加AGENTS.md。

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）使用以下json。

{
  "mcpServers": {
    "wcgw": {
      "command": "uvx",
      "args": ["wcgw@latest"]
    }
  }
}

然后重启claude应用。

可选：强制指定特定shell

要使用特定shell（bash或zsh），请添加--shell参数：

{
  "mcpServers": {
    "wcgw": {
      "command": "uvx",
      "args": ["wcgw@latest", "--shell", "/bin/bash"]
    }
  }
}

如果设置出错

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

Windows上的WSL

此MCP服务器仅在Windows上的WSL中工作。

要设置它，请安装uv

然后添加或更新claude配置文件%APPDATA%\Claude\claude_desktop_config.json使用以下内容

{
  "mcpServers": {
    "wcgw": {
      "command": "wsl.exe",
      "args": ["uvx", "wcgw@latest"]
    }
  }
}

当您遇到错误时，在命令提示符中执行命令wsl uv --python 3.12 wcgw。如果您得到error /bin/bash: line 1: uv: command not found，这意味着uv没有被全局安装，您需要指向uv的正确路径。

1. 找到uv的安装位置：

whereis uv

示例输出： uv: /home/mywsl/.local/bin/uv

2. 测试完整路径是否有效：

wsl /home/mywsl/.local/bin/uv tool run --python 3.12 wcgw

3. 使用完整路径更新配置：

{
  "mcpServers": {
    "wcgw": {
      "command": "wsl.exe",
      "args": ["/home/mywsl/.local/bin/uv", "tool", "run", "--python", "3.12", "wcgw"]
    }
  }
}

将/home/mywsl/.local/bin/uv替换为步骤1中您的实际uv路径。

使用

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

在这里

然后要求claude执行shell命令、读取文件、编辑文件、运行您的代码等。

任务检查点或知识迁移

• 您可以通过使用"Attach from MCP"按钮附加"KnowledgeTransfer"提示来进行任务检查点或知识迁移。
• 运行"KnowledgeTransfer"提示时，"ContextSave"工具将被调用，将任务描述和所有文件内容一起保存在单个文件中。将生成一个任务ID。
• 您可以在新的聊天中输入"Resume ''"，AI应该然后使用任务ID调用"Initialize"并从那里加载上下文。
• 或者您可以直接打开生成的文件并与另一个AI共享以寻求帮助。

模式

有三个内置模式。您可以要求Claude运行其中一种模式，例如"Use 'architect' mode"

注意：在代码编写者模式下，目前要么允许所有命令，要么不允许任何命令。如果您给出一个允许的命令列表，Claude会被指示只运行那些命令，但不会进行实际检查。（WIP）

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

NEW: VSCode扩展现在会自动附加正在运行的终端 如果工作区路径匹配。

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

screen -ls

并记下wcgw screen名称，它将类似于93358.wcgw.235521，其中最后一位是小时-分钟-秒格式。

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

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

您可以安全地与终端交互，例如输入密码或输入一些文本。（警告：如果您运行新命令，任何新的LLM命令将中断它。）

您不应使用exit 或Ctrl-d退出会话，而是应使用ctrl+a+d安全地分离，而不会销毁screen会话。

在~/.screenrc中包含以下内容以获得更好的滚动体验

defscrollback 10000
termcapinfo xterm* ti@:te@

[可选] VS code扩展

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

命令：

• 选择文本并按cmd+'，然后输入指令。这将切换到Claude并粘贴包含您的指令、文件路径、工作区目录和所选文本的文本。

示例

使用docker的mcp服务器

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

然后您可以更新/Users/username/Library/Application Support/Claude/claude_desktop_config.json以包含

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

工具

服务器提供以下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规范。