Shell and Coding agent for Claude and other mcp clients

Claude 和其他 MCP 客户端的 Shell 与编码 Agent

赋能聊天应用在本地机器上编写代码、构建和运行程序。

wcgw 是一个深度集成 Shell 和代码编辑工具的 MCP 服务。

⚠️ 警告：此 MCP 服务可不受限制地访问你机器上的 Shell 和文件。它不会限制大模型执行任意命令或进行意外更改。攻击者可能滥用此工具；如果 AI 产生幻觉，也可能运行危险命令。只有在充分了解并接受运行不受限制的 AI Agent 所带来的风险后，才运行此代码库。

截至 2026 年，你可以使用 wcgw，是因为它提供了完全交互式的 Shell 体验，你和 Agent 都可以控制 Shell（包括发送按键）。 结合 wcgw VS Code 扩展（它可以将 Agent 的 Shell 接入编辑器），你可以获得目前最出色的 Agent 式 Shell 体验。 文件编辑技巧和整体的极简设计也有助于提升 Agent 的效率。

演示

更新

• [6 Oct 2025] 模型现在可以在后台运行多个命令。现已支持 ZSH Shell。改进了多路复用。

• [27 Apr 2025] 移除了通过中继服务支持 GPT 的功能。版本 >= 5 仅支持 MCP 服务。

• [24 Mar 2025] 改进了 sonnet 3.7 的编写和编辑体验，CLAUDE.md 现在会自动加载。

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

• [15 Jan 2025] 引入了多种模式：architect、code-writer 和功能强大的 wcgw 模式。

• [8 Jan 2025] 新增上下文保存工具，可将相关文件路径及其说明保存到单个文件中。可用作任务检查点或用于知识交接。

• [29 Dec 2024] 文件写入和编辑时的语法检查现已稳定。改进了 initialize 工具调用的实用性；如果引用了仓库，会向 claude 发送智能生成的仓库结构。大文件处理也得到了改进。

• [9 Dec 2024] 用于在 Claude 应用中粘贴上下文的 Vscode 扩展

🚀 亮点

• ⚡ 创建、执行、迭代：让 claude 持续运行编译器检查，直到修复所有错误；也可以让它持续检查长时间运行的命令状态，直到命令完成。
• ⚡ 编辑大文件：支持对大文件进行增量编辑，避免令牌限制问题。根据需要更改的内容占比，智能选择小范围编辑或大规模重写。
• ⚡ 编辑时检查语法：如果编辑存在语法错误，会向大模型提供反馈，以便其重新编辑。
• ⚡ 交互式命令处理：支持使用方向键、interrupt 和 ansi 转义序列处理交互式命令。
• ⚡ 文件保护：
  • AI 必须至少读取过一次文件，才能编辑或重写该文件。这可以避免意外覆盖。
  • 读取超大文件时避免上下文被填满。文件会根据令牌长度分块。
  • 初始化时，选择重要文件后会返回所提供工作区的目录结构（依据 .gitignore 和统计方法选择）。
  • 基于搜索-替换的文件编辑如果遇到多个匹配项，会根据之前的搜索块尝试找到正确的搜索块；否则会失败（以确保正确性）。
  • 文件编辑支持空格差异容错匹配，并会针对缩进不匹配等问题发出警告。如果没有匹配项，会将最接近的匹配项返回给 AI，以便修正错误。
  • 使用类似 Aider 的搜索和替换方式，其性能优于基于工具调用的搜索和替换。
• ⚡ Shell 优化：
  • 每次执行 Shell 命令后都会返回当前工作目录，避免 AI 迷失方向。
  • 命令轮询会在短暂超时后退出，避免反馈延迟。不过，状态检查的等待容差会根据命令输出的实时流进行调整。两种方式结合，可提供良好的 Shell 交互体验。
  • 除主交互式 Shell 外，还支持多个并发后台命令。
• ⚡ 将仓库上下文保存到单个文件中：使用“ContextSave”工具进行任务检查点保存，可将详细上下文保存到单个文件中。之后可以在新的聊天中发送“Resume task id”来恢复任务。保存的文件也可用于其他类型的知识转移，例如向另一个 AI 寻求帮助。
• ⚡ 轻松切换不同模式：
  • 让它以“architect”模式运行以进行规划。该模式受 adier 的 architect 模式启发，先与 Claude 一起制定计划，可提高准确性并避免过早编辑文件。
  • 让它以“code-writer”模式运行以编辑代码和构建项目。你可以指定路径，并使用通配符支持，避免编辑其他文件。
  • 默认以“wcgw”模式运行，不受限制并拥有完整授权。
  • 更多详情请参阅 Modes section
• ⚡ 在多路复用终端中运行 使用 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），内容如下。

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

然后重启 claude 应用。

可选：指定 shell

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

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

可选：Streamable HTTP 传输

wcgw_mcp 默认使用 stdio 作为传输方式。对于更适合使用长期运行的 HTTP MCP 端点的客户端或网关，请运行：

uvx --python 3.12 wcgw@latest --transport streamable-http --host 127.0.0.1 --port 8765

MCP 端点为 http://127.0.0.1:8765/mcp/。绑定到回环地址可使服务保持在本地，同时允许支持 HTTP 的本地网关复用请求，而无需共享同一个 stdio 管道。

如果设置时出现错误

• 如果出现类似“uv ENOENT”的错误，请确保已安装 uv。然后在终端中运行 'which uv'，并在配置中用其输出替换“uv”。
• 如果问题仍然存在，请检查 uv tool run --python 3.12 wcgw 是否能在终端中运行。它应该没有输出，也不应该退出。
• 尝试删除 ~/.cache/uv 文件夹。
• 尝试使用 uv 版本 0.6.0，此工具已针对该版本进行测试。
• 使用 npx @modelcontextprotocol/[email protected] uv tool run --python 3.12 wcgw 调试 MCP 服务。

Windows on wsl

此 MCP 服务只能在 Windows 上的 wsl 中运行。

如需设置，请安装 uv

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

{
  "mcpServers": {
    "wcgw": {
      "command": "wsl.exe",
      "args": ["uvx", "--python", "3.12", "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. Test the full path works:

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

3. Update the config with the full path:

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

Replace /home/mywsl/.local/bin/uv with your actual uv path from step 1.

Usage

Wait for a few seconds. You should be able to see this icon if everything goes right.

over here

Then ask claude to execute shell commands, read files, edit files, run your code, etc.

Task checkpoint or knowledge transfer

• You can do a task checkpoint or a knowledge transfer by attaching "KnowledgeTransfer" prompt using "Attach from MCP" button.
• On running "KnowledgeTransfer" prompt, the "ContextSave" tool will be called saving the task description and all file content together in a single file. An id for the task will be generated.
• You can in a new chat say "Resume ''", the AI should then call "Initialize" with the task id and load the context from there.
• Or you can directly open the file generated and share it with another AI for help.

Modes

There are three built-in modes. You may ask Claude to run in one of the modes, like "Use 'architect' mode"

Mode	Description	Allows	Denies	Invoke prompt
Architect	Designed for you to work with Claude to investigate and understand your repo.	Read-only commands	FileEdit and Write tool	Run in mode='architect'
Code-writer	For code writing and development	Specified path globs for editing or writing, specified commands	FileEdit for paths not matching specified glob, Write for paths not matching specified glob	Run in code writer mode, only 'tests/**' allowed, only uv command allowed
**wcgw**	Default mode with everything allowed	Everything	Nothing	No prompt, or "Run in wcgw mode"

Note: in code-writer mode either all commands are allowed or none are allowed for now. If you give a list of allowed commands, Claude is instructed to run only those commands, but no actual check happens. (WIP)

Attach to the working terminal to investigate

NEW: the vscode extension now automatically attach the running terminal if workspace path matches.

If you've screen command installed, wcgw runs on a screen instance automatically. If you've started wcgw mcp server, you can list the screen sessions:

screen -ls

And note down the wcgw screen name which will be something like 93358.wcgw.235521 where the last number is in the hour-minute-second format.

You can then attach to the session using screen -x 93358.wcgw.235521

You may interrupt any running command safely.

You can interact with the terminal safely, for example for entering passwords, or entering some text. (Warning: If you run a new command, any new LLM command will interrupt it.)

You shouldn't exit the session using exit or Ctrl-d, instead you should use ctrl+a+d to safely detach without destroying the screen session.

Include the following in ~/.screenrc for better scrolling experience

defscrollback 10000
termcapinfo xterm* ti@:te@

[Optional] Vs code extension

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

Commands:

• Select a text and press cmd+' and then enter instructions. This will switch the app to Claude and paste a text containing your instructions, file path, workspace dir, and the selected text.

Examples

Using mcp server over docker

First build the docker image docker build -t wcgw https://github.com/rusiaaman/wcgw.git

Then you can update /Users/username/Library/Application Support/Claude/claude_desktop_config.json to have

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

Tools

The server provides the following MCP tools:

Shell Operations:

• Initialize: Reset shell and set up workspace environment
  • Parameters: any_workspace_path (string), initial_files_to_read (string[]), mode_name ("wcgw"|"architect"|"code_writer"), task_id_to_resume (string), thread_id (string; empty only for the first call)
• BashCommand: Execute shell commands with timeout control
  • Parameters: command (string), wait_for_seconds (int, optional), thread_id (string)
  • Parameters: send_text (string) or send_specials (["Enter"|"Key-up"|...]) or send_ascii (int[]), wait_for_seconds (int, optional)

File Operations:

• ReadFiles: Read content from one or more files
  • Parameters: file_paths (string[]), thread_id (string)
• WriteIfEmpty: Create new files or write to empty files
  • Parameters: file_path (string), file_content (string)
• FileEdit: Edit existing files using search/replace blocks
  • Parameters: file_path (string), file_edit_using_search_replace_blocks (string)
• ReadImage: Read image files for display/processing
  • Parameters: file_path (string), thread_id (string)

Project Management:

• ContextSave: Save project context and files for Knowledge Transfer or saving task checkpoints to be resumed later
  • Parameters: id (string), project_root_path (string), description (string), relevant_file_globs (string[]), thread_id (string)

All tools support absolute paths and include built-in protections against common errors. See the MCP specification for detailed protocol information.