wcgw 5.5.4__py3-none-any.whl

wcgw/types_.py

@@ -0,0 +1,318 @@
+import os
+import re
+from typing import Any, List, Literal, Optional, Protocol, Sequence, Union
+
+from pydantic import BaseModel as PydanticBaseModel
+from pydantic import Field, PrivateAttr
+
+
+def normalize_thread_id(thread_id: str) -> str:
+    """Normalize thread_id by keeping only word characters (alphanumeric and underscore)."""
+    return re.sub(r"[^\w]", "", thread_id)
+
+
+class NoExtraArgs(PydanticBaseModel):
+    class Config:
+        extra = "forbid"
+
+
+BaseModel = NoExtraArgs
+
+
+Modes = Literal["wcgw", "architect", "code_writer"]
+
+
+class CodeWriterMode(BaseModel):
+    allowed_globs: Literal["all"] | list[str]
+    allowed_commands: Literal["all"] | list[str]
+
+    def model_post_init(self, _: Any) -> None:
+        # Patch frequently wrong output trading off accuracy
+        # in rare case there's a file named 'all' or a command named 'all'
+        if len(self.allowed_commands) == 1:
+            if self.allowed_commands[0] == "all":
+                self.allowed_commands = "all"
+        if len(self.allowed_globs) == 1:
+            if self.allowed_globs[0] == "all":
+                self.allowed_globs = "all"
+
+    def update_relative_globs(self, workspace_root: str) -> None:
+        """Update globs if they're relative paths"""
+        if self.allowed_globs != "all":
+            self.allowed_globs = [
+                glob if os.path.isabs(glob) else os.path.join(workspace_root, glob)
+                for glob in self.allowed_globs
+            ]
+
+
+ModesConfig = Union[Literal["wcgw", "architect"], CodeWriterMode]
+
+
+class Initialize(BaseModel):
+    type: Literal[
+        "first_call",
+        "user_asked_mode_change",
+        "reset_shell",
+        "user_asked_change_workspace",
+    ]
+    any_workspace_path: str = Field(
+        description="Workspace to initialise in. Don't use ~ by default, instead use empty string"
+    )
+    initial_files_to_read: list[str] = Field(
+        description="Array of one or more files to read. Provide [] if no files mentioned."
+    )
+    task_id_to_resume: str
+    mode_name: Literal["wcgw", "architect", "code_writer"]
+    thread_id: str = Field(
+        description="Use the thread_id created in first_call, leave it as empty string if first_call"
+    )
+    code_writer_config: Optional[CodeWriterMode] = None
+
+    def model_post_init(self, __context: Any) -> None:
+        self.thread_id = normalize_thread_id(self.thread_id)
+        if self.mode_name == "code_writer":
+            assert self.code_writer_config is not None, (
+                "code_writer_config can't be null when the mode is code_writer"
+            )
+        if self.type != "first_call" and not self.thread_id:
+            raise ValueError(
+                "Thread id should be provided if type != 'first_call', including when resetting"
+            )
+        return super().model_post_init(__context)
+
+    @property
+    def mode(self) -> ModesConfig:
+        if self.mode_name == "wcgw":
+            return "wcgw"
+        if self.mode_name == "architect":
+            return "architect"
+        assert self.code_writer_config is not None, (
+            "code_writer_config can't be null when the mode is code_writer"
+        )
+        return self.code_writer_config
+
+
+class Command(BaseModel):
+    command: str
+    type: Literal["command"] = "command"
+    is_background: bool = False
+
+
+class StatusCheck(BaseModel):
+    status_check: Literal[True] = True
+    type: Literal["status_check"] = "status_check"
+    bg_command_id: str | None = None
+
+
+class SendText(BaseModel):
+    send_text: str
+    type: Literal["send_text"] = "send_text"
+    bg_command_id: str | None = None
+
+
+Specials = Literal[
+    "Enter", "Key-up", "Key-down", "Key-left", "Key-right", "Ctrl-c", "Ctrl-d"
+]
+
+
+class SendSpecials(BaseModel):
+    send_specials: Sequence[Specials]
+    type: Literal["send_specials"] = "send_specials"
+    bg_command_id: str | None = None
+
+
+class SendAscii(BaseModel):
+    send_ascii: Sequence[int]
+    type: Literal["send_ascii"] = "send_ascii"
+    bg_command_id: str | None = None
+
+
+class ActionJsonSchema(BaseModel):
+    type: Literal[
+        "command", "status_check", "send_text", "send_specials", "send_ascii"
+    ] = Field(description="type of action.")
+    command: Optional[str] = Field(
+        default=None, description='Set only if type="command"'
+    )
+    status_check: Optional[Literal[True]] = Field(
+        default=None, description='Set only if type="status_check"'
+    )
+    send_text: Optional[str] = Field(
+        default=None, description='Set only if type="send_text"'
+    )
+    send_specials: Optional[Sequence[Specials]] = Field(
+        default=None, description='Set only if type="send_specials"'
+    )
+    send_ascii: Optional[Sequence[int]] = Field(
+        default=None, description='Set only if type="send_ascii"'
+    )
+    is_background: bool = Field(
+        default=False,
+        description='Set only if type="command" and running the command in background',
+    )
+    bg_command_id: str | None = Field(
+        default=None,
+        description='Set only if type!="command" and doing action on a running background command',
+    )
+
+
+class BashCommandOverride(BaseModel):
+    action_json: ActionJsonSchema
+    wait_for_seconds: Optional[float] = None
+    thread_id: str
+
+
+class BashCommand(BaseModel):
+    action_json: Command | StatusCheck | SendText | SendSpecials | SendAscii
+    wait_for_seconds: Optional[float] = None
+    thread_id: str
+
+    def model_post_init(self, __context: Any) -> None:
+        self.thread_id = normalize_thread_id(self.thread_id)
+        return super().model_post_init(__context)
+
+    @staticmethod
+    def model_json_schema(*args, **kwargs) -> dict[str, Any]:  # type: ignore
+        return BashCommandOverride.model_json_schema(*args, **kwargs)
+
+
+class ReadImage(BaseModel):
+    file_path: str
+
+
+class WriteIfEmpty(BaseModel):
+    file_path: str
+    file_content: str
+
+
+class ReadFiles(BaseModel):
+    file_paths: list[str]
+    _start_line_nums: List[Optional[int]] = PrivateAttr(default_factory=lambda: [])
+    _end_line_nums: List[Optional[int]] = PrivateAttr(default_factory=lambda: [])
+
+    @property
+    def show_line_numbers_reason(self) -> str:
+        return "True"
+
+    @property
+    def start_line_nums(self) -> List[Optional[int]]:
+        """Get the start line numbers."""
+        return self._start_line_nums
+
+    @property
+    def end_line_nums(self) -> List[Optional[int]]:
+        """Get the end line numbers."""
+        return self._end_line_nums
+
+    def model_post_init(self, __context: Any) -> None:
+        # Parse file paths for line ranges and store them in private attributes
+        self._start_line_nums = []
+        self._end_line_nums = []
+
+        # Create new file_paths list without line ranges
+        clean_file_paths = []
+
+        for file_path in self.file_paths:
+            start_line_num = None
+            end_line_num = None
+            path_part = file_path
+
+            # Check if the path ends with a line range pattern
+            # We're looking for patterns at the very end of the path like:
+            #  - file.py:10      (specific line)
+            #  - file.py:10-20   (line range)
+            #  - file.py:10-     (from line 10 to end)
+            #  - file.py:-20     (from start to line 20)
+
+            # Split by the last colon
+            if ":" in file_path:
+                parts = file_path.rsplit(":", 1)
+                if len(parts) == 2:
+                    potential_path = parts[0]
+                    line_spec = parts[1]
+
+                    # Check if it's a valid line range format
+                    if line_spec.isdigit():
+                        # Format: file.py:10
+                        try:
+                            start_line_num = int(line_spec)
+                            path_part = potential_path
+                        except ValueError:
+                            # Keep the original path if conversion fails
+                            pass
+
+                    elif "-" in line_spec:
+                        # Could be file.py:10-20, file.py:10-, or file.py:-20
+                        line_parts = line_spec.split("-", 1)
+
+                        if not line_parts[0] and line_parts[1].isdigit():
+                            # Format: file.py:-20
+                            try:
+                                end_line_num = int(line_parts[1])
+                                path_part = potential_path
+                            except ValueError:
+                                # Keep original path
+                                pass
+
+                        elif line_parts[0].isdigit():
+                            # Format: file.py:10-20 or file.py:10-
+                            try:
+                                start_line_num = int(line_parts[0])
+
+                                if line_parts[1].isdigit():
+                                    # file.py:10-20
+                                    end_line_num = int(line_parts[1])
+
+                                # In both cases, update the path
+                                path_part = potential_path
+                            except ValueError:
+                                # Keep original path
+                                pass
+
+            # Add clean path and corresponding line numbers
+            clean_file_paths.append(path_part)
+            self._start_line_nums.append(start_line_num)
+            self._end_line_nums.append(end_line_num)
+
+        # Update file_paths with clean paths
+        self.file_paths = clean_file_paths
+
+        return super().model_post_init(__context)
+
+
+class FileEdit(BaseModel):
+    file_path: str
+    file_edit_using_search_replace_blocks: str
+
+
+class FileWriteOrEdit(BaseModel):
+    # Naming should be in sorted order otherwise it gets changed in LLM backend.
+    file_path: str = Field(description="#1: absolute file path")
+    percentage_to_change: int = Field(
+        description="#2: predict this percentage, calculated as number of existing lines that will have some diff divided by total existing lines."
+    )
+    text_or_search_replace_blocks: str = Field(
+        description="#3: content/edit blocks. Must be after #2 in the tool xml"
+    )
+    thread_id: str = Field(description="#4: thread_id")
+
+    def model_post_init(self, __context: Any) -> None:
+        self.thread_id = normalize_thread_id(self.thread_id)
+        return super().model_post_init(__context)
+
+
+class ContextSave(BaseModel):
+    id: str
+    project_root_path: str
+    description: str
+    relevant_file_globs: list[str]
+
+
+class Console(Protocol):
+    def print(self, msg: str, *args: Any, **kwargs: Any) -> None: ...
+
+    def log(self, msg: str, *args: Any, **kwargs: Any) -> None: ...
+
+
+class Mdata(PydanticBaseModel):
+    data: BashCommand | FileWriteOrEdit | str | ReadFiles | Initialize | ContextSave

wcgw-5.5.4.dist-info/METADATA

@@ -0,0 +1,339 @@
+Metadata-Version: 2.4
+Name: wcgw
+Version: 5.5.4
+Summary: Shell and coding agent for Claude and other mcp clients
+Project-URL: Homepage, https://github.com/rusiaaman/wcgw
+Author-email: Aman Rusia <gapypi@arcfu.com>
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.39.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: mcp>=1.7.0
+Requires-Dist: openai>=1.46.0
+Requires-Dist: petname>=2.6
+Requires-Dist: pexpect>=4.9.0
+Requires-Dist: psutil>=7.0.0
+Requires-Dist: pydantic>=2.9.2
+Requires-Dist: pygit2>=1.16.0
+Requires-Dist: pyte>=0.8.2
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: rich>=13.8.1
+Requires-Dist: semantic-version>=2.10.0
+Requires-Dist: syntax-checker==0.4.0
+Requires-Dist: tokenizers>=0.21.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: tree-sitter-bash>=0.23.3
+Requires-Dist: tree-sitter>=0.24.0
+Requires-Dist: typer>=0.12.5
+Requires-Dist: uvicorn>=0.31.0
+Requires-Dist: wcmatch>=10.1
+Requires-Dist: websockets>=13.1
+Description-Content-Type: text/markdown
+
+# Shell and Coding agent for Claude and other mcp clients
+
+Empowering chat applications to code, build and run on your local machine.
+
+wcgw is an MCP server with tightly integrated shell and code editing tools.
+
+⚠️ Warning: do not allow BashCommand tool without reviewing the command, it may result in data loss.
+
+[![Tests](https://github.com/rusiaaman/wcgw/actions/workflows/python-tests.yml/badge.svg?branch=main)](https://github.com/rusiaaman/wcgw/actions/workflows/python-tests.yml)
+[![Mypy strict](https://github.com/rusiaaman/wcgw/actions/workflows/python-types.yml/badge.svg?branch=main)](https://github.com/rusiaaman/wcgw/actions/workflows/python-types.yml)
+[![Build](https://github.com/rusiaaman/wcgw/actions/workflows/python-publish.yml/badge.svg)](https://github.com/rusiaaman/wcgw/actions/workflows/python-publish.yml)
+[![codecov](https://codecov.io/gh/rusiaaman/wcgw/graph/badge.svg)](https://codecov.io/gh/rusiaaman/wcgw)
+
+## Demo
+
+![Workflow Demo](static/workflow-demo.gif)
+
+## Updates
+
+- [6 Oct 2025] Model can now run multiple commands in background. ZSH is now a supported shell. Multiplexing improvements.
+
+- [27 Apr 2025] Removed support for GPTs over relay server. Only MCP server is supported in version >= 5.
+
+- [24 Mar 2025] Improved writing and editing experience for sonnet 3.7, CLAUDE.md gets loaded automatically.
+
+- [16 Feb 2025] You can now attach to the working terminal that the AI uses. See the "attach-to-terminal" section below.
+
+- [15 Jan 2025] Modes introduced: architect, code-writer, and all powerful wcgw mode.
+
+- [8 Jan 2025] Context saving tool for saving relevant file paths along with a description in a single file. Can be used as a task checkpoint or for knowledge transfer.
+
+- [29 Dec 2024] Syntax checking on file writing and edits is now stable. Made `initialize` tool call useful; sending smart repo structure to claude if any repo is referenced. Large file handling is also now improved.
+
+- [9 Dec 2024] [Vscode extension to paste context on Claude app](https://marketplace.visualstudio.com/items?itemName=AmanRusia.wcgw)
+
+## 🚀 Highlights
+
+- ⚡ **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**:
+  - 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.
+  - Supports multiple concurrent background commands alongside the main interactive shell.
+- ⚡ **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](#modes)
+- ⚡ **Runs in multiplex terminal** Use [vscode extension](https://marketplace.visualstudio.com/items?itemName=AmanRusia.wcgw) or 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.
+- ⚡ **Automatically load CLAUDE.md/AGENTS.md** Loads "CLAUDE.md" or "AGENTS.md" file in project root and sends as instructions during initialisation. Instructions in a global "~/.wcgw/CLAUDE.md" or "~/.wcgw/AGENTS.md" file are loaded and added along with project specific CLAUDE.md. The file name is case sensitive. CLAUDE.md is attached if it's present otherwise AGENTS.md is attached.
+
+## Top use cases examples
+
+- Solve problem X using python, create and run test cases and fix any issues. Do it in a temporary directory
+- Find instances of code with X behavior in my repository
+- Git clone https://github.com/my/repo in my home directory, then understand the project, set up the environment and build
+- Create a golang htmx tailwind webapp, then open browser to see if it works (use with puppeteer mcp)
+- Edit or update a large file
+- In a separate branch create feature Y, then use github cli to create a PR to original branch
+- Command X is failing in Y directory, please run and fix issues
+- Using X virtual environment run Y command
+- Using cli tools, create build and test an android app. Finally run it using emulator for me to use
+- Fix all mypy issues in my repo at X path.
+- Using 'screen' run my server in background instead, then run another api server in bg, finally run the frontend build. Keep checking logs for any issues in all three
+- Create repo wide unittest cases. Keep iterating through files and creating cases. Also keep running the tests after each update. Do not modify original code.
+
+## Claude setup (using mcp)
+
+### Mac and linux
+
+First install `uv` using homebrew `brew install uv`
+
+(**Important:** use homebrew to install uv. Otherwise make sure `uv` is present in a global location like /usr/bin/)
+
+Then create or update `claude_desktop_config.json` (~/Library/Application Support/Claude/claude_desktop_config.json) with following json.
+
+```json
+{
+  "mcpServers": {
+    "wcgw": {
+      "command": "uvx",
+      "args": ["wcgw@latest"]
+    }
+  }
+}
+```
+
+Then restart claude app.
+
+**Optional: Force a specific shell**
+
+To use a specific shell (bash or zsh), add the `--shell` argument:
+
+```json
+{
+  "mcpServers": {
+    "wcgw": {
+      "command": "uvx",
+      "args": ["wcgw@latest", "--shell", "/bin/bash"]
+    }
+  }
+}
+```
+
+_If there's an error in setting up_
+
+- If there's an error like "uv ENOENT", make sure `uv` is installed. Then run 'which uv' in the terminal, and use its output in place of "uv" in the configuration.
+- If there's still an issue, check that `uv tool run --python 3.12 wcgw` runs in your terminal. It should have no output and shouldn't exit.
+- Try removing ~/.cache/uv folder
+- Try using `uv` version `0.6.0` for which this tool was tested.
+- Debug the mcp server using `npx @modelcontextprotocol/inspector@0.1.7 uv tool run --python 3.12 wcgw`
+
+### Windows on wsl
+
+This mcp server works only on wsl on windows.
+
+To set it up, [install uv](https://docs.astral.sh/uv/getting-started/installation/)
+
+Then add or update the claude config file `%APPDATA%\Claude\claude_desktop_config.json` with the following
+
+```json
+{
+  "mcpServers": {
+    "wcgw": {
+      "command": "wsl.exe",
+      "args": ["uvx", "wcgw@latest"]
+    }
+  }
+}
+```
+When you encounter an error, execute the command wsl uv --python 3.12 wcgw in command prompt. If you get the `error /bin/bash: line 1: uv: command not found`, it means uv was not installed globally and you need to point to the correct path of uv.
+1. Find where uv is installed:
+```bash
+whereis uv
+```
+Example output:
+```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.
+
+![mcp icon](https://github.com/rusiaaman/wcgw/blob/main/static/rocket-icon.png?raw=true)
+over here
+
+![mcp icon](https://github.com/rusiaaman/wcgw/blob/main/static/claude-ss.jpg?raw=true)
+
+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 '<task id>'", 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](https://marketplace.visualstudio.com/items?itemName=AmanRusia.wcgw) 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
+
+![example](https://github.com/rusiaaman/wcgw/blob/main/static/example.jpg?raw=true)
+
+## 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"
+      ]
+    }
+  }
+}
+```
+
+## [Optional] Local shell access with openai API key or anthropic API key
+
+### Openai
+
+Add `OPENAI_API_KEY` and `OPENAI_ORG_ID` env variables.
+
+Then run
+
+`uvx wcgw wcgw_local --limit 0.1` # Cost limit $0.1
+
+You can now directly write messages or press enter key to open vim for multiline message and text pasting.
+
+### Anthropic
+
+Add `ANTHROPIC_API_KEY` env variable.
+
+Then run
+
+`uvx wcgw wcgw_local --claude`
+
+You can now directly write messages or press enter key to open vim for multiline message and text pasting.
+
+## 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)
+- `BashCommand`: Execute shell commands with timeout control
+  - Parameters: `command` (string), `wait_for_seconds` (int, optional)
+  - 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[])
+- `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)
+
+**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[])
+
+All tools support absolute paths and include built-in protections against common errors. See the [MCP specification](https://modelcontextprotocol.io/) for detailed protocol information.