Shell and Coding agent for Claude and other mcp clients

Claude やその他の MCP クライアント向けシェルおよびコーディングエージェント

チャットアプリケーションを活用して、ローカルマシン上でコードを書き、ビルドし、実行できます。

wcgw は、シェルとコード編集ツールを緊密に統合した MCP サーバーです。

⚠️ 警告：この MCP サーバーは、マシンのシェルとファイルへの無制限のアクセスを提供します。LLM が任意のコマンドを実行したり、意図しない変更を加えたりすることを制限しません。攻撃者に悪用されたり、AI が幻覚を起こして危険なコマンドを実行したりする可能性があります。制限のない AI エージェントを実行するリスクを十分に理解し、受け入れられる場合にのみ、このリポジトリを実行してください。

2026年現在、wcgw を利用する理由は、あなたとエージェントの両方が操作できる、完全にインタラクティブなシェル環境を提供していることです（キー入力の送信も可能です）。 エージェントのシェルをエディターに接続する wcgw の vscode 拡張機能と組み合わせれば、他に類を見ない最高のエージェント型シェル体験が得られます。 ファイル編集の工夫と全体的なミニマリズムも、エージェントの生産性向上に役立ちます。

デモ

更新情報

• [6 Oct 2025] モデルが複数のコマンドをバックグラウンドで実行できるようになりました。ZSH がサポート対象のシェルに加わりました。多重化機能が改善されました。

• [27 Apr 2025] リレーサーバー経由の GPT のサポートを終了しました。バージョン 5 以降でサポートされるのは MCP サーバーのみです。

• [24 Mar 2025] sonnet 3.7 の記述および編集体験が改善され、CLAUDE.md が自動的に読み込まれるようになりました。

• [16 Feb 2025] AI が使用する作業中のターミナルに接続できるようになりました。詳しくは、以下の「ターミナルへの接続」セクションをご覧ください。

• [15 Jan 2025] architect、code-writer、そしてすべての機能を備えた wcgw モードが導入されました。

• [8 Jan 2025] 関連するファイルパスと説明を1つのファイルに保存する、コンテキスト保存ツールが追加されました。タスクのチェックポイントやナレッジ移転に利用できます。

• [29 Dec 2024] ファイルの書き込みと編集時の構文チェックが安定しました。initialize ツール呼び出しが便利になり、リポジトリが参照されている場合は、リポジトリ構造を適切にまとめて Claude に送信するようになりました。大きなファイルの処理も改善されました。

• [9 Dec 2024] Claude アプリにコンテキストを貼り付けるための Vscode 拡張機能

🚀 主な機能

• ⚡ 作成、実行、反復：エラーがすべて修正されるまでコンパイラーチェックを実行し続けるよう Claude に依頼したり、長時間実行されるコマンドが完了するまでステータスを確認し続けるよう依頼したりできます。
• ⚡ 大きなファイルの編集：トークン制限の問題を避けるため、大きなファイルの段階的な編集をサポートします。変更が必要な割合に基づいて、小規模な編集と大規模な書き換えを適切に選択します。
• ⚡ 編集時の構文チェック：編集内容に構文エラーがある場合、そのフィードバックを LLM に報告し、修正をやり直せるようにします。
• ⚡ インタラクティブなコマンド処理：矢印キー、割り込み、ANSI エスケープシーケンスを使ったインタラクティブなコマンドをサポートします。
• ⚡ ファイル保護：
  • AI がファイルを編集または書き換えるには、少なくとも一度そのファイルを読み取る必要があります。これにより、誤って上書きするのを防ぎます。
  • 非常に大きなファイルの読み取り時にコンテキストが埋まるのを防ぎます。ファイルはトークン数に基づいて分割されます。
  • 初期化時に、重要なファイルを選択したうえで（.gitignore と統計的な方法に基づきます）、指定されたワークスペースのディレクトリ構造を返します。
  • 検索と置換によるファイル編集では、検索ブロックが複数箇所に一致する場合、以前の検索ブロックを基に正しいブロックを見つけようとします。見つからない場合は（正確性を保つため）失敗します。
  • ファイル編集では、スペースの違いを許容して照合し、インデントの不一致などの問題があれば警告します。一致する箇所がない場合は、最も近い箇所を AI に返して間違いを修正できるようにします。
  • ツール呼び出しによる検索と置換よりパフォーマンスに優れた、Aider のような検索と置換を使用します。
• ⚡ シェルの最適化：
  • AI が作業場所を見失わないよう、シェルコマンドの実行後は常に現在の作業ディレクトリを返します。
  • 応答が遅くならないよう、コマンドのポーリングは短時間でタイムアウトします。一方、ステータス確認では、コマンドからの新しい出力のストリーミングに基づいて待機時間を調整します。この2つの方法を組み合わせることで、快適なシェル操作を実現します。
  • メインのインタラクティブシェルと並行して、複数のバックグラウンドコマンドを実行できます。
• ⚡ リポジトリのコンテキストを1つのファイルに保存：「ContextSave」ツールを使ったタスクのチェックポイント保存により、詳細なコンテキストを1つのファイルに保存します。後で新しいチャットで「task idを再開して」と依頼すれば、タスクを再開できます。保存したファイルは、別の AI の助けを借りるなど、ほかの種類の知識移転にも使用できます。
• ⚡ さまざまなモードを簡単に切り替え：
  • 計画には「architect」モードで実行するよう依頼します。adier の architect モードに着想を得たこのモードでは、Claude と一緒にまず計画を立てます。精度が向上し、早まったファイル編集を防げます。
  • コード編集やプロジェクトの構築には「code-writer」モードで実行するよう依頼します。ワイルドカードに対応した特定のパスを指定して、ほかのファイルが編集されないようにできます。
  • デフォルトでは、制限がなく、すべての操作が許可された「wcgw」モードで実行されます。
  • 詳細はモードのセクションを参照してください。
• ⚡ 多重化されたターミナルで実行：vscode extensionを使用するか、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

（重要： uv のインストールには homebrew を使用してください。それ以外の方法でインストールする場合は、uv が /usr/bin/ のようなグローバルな場所にあることを確認してください。）

次に、以下の JSON を使って claude_desktop_config.json（~/Library/Application Support/Claude/claude_desktop_config.json）を作成または更新します。

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

その後、Claude アプリを再起動します。

オプション：特定のシェルを指定する

特定のシェル（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（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.