Permite que las aplicaciones de chat codifiquen, compilen y ejecuten en tu máquina local.
wcgw es un servidor MCP con herramientas de shell y edición de código estrechamente integradas.
⚠️ Advertencia: Este servidor MCP proporciona acceso sin filtrar al shell y a los archivos de tu máquina. No restringe a los LLM de ejecutar comandos arbitrarios o realizar cambios no deseados. Esta herramienta puede ser utilizada indebidamente por atacantes o ejecutar comandos peligrosos si la IA alucina. Ejecuta este repositorio solo si comprendes y aceptas completamente los riesgos asociados con la ejecución de agentes de IA sin restricciones.
A partir de 2026, la razón por la que podrías usar wcgw es que proporciona una experiencia de shell totalmente interactiva que tanto tú como el agente pueden controlar (incluyendo el envío de pulsaciones de teclas).
Combinado con la extensión de VS Code de wcgw que adjunta el shell del agente en tu editor, puedes obtener la mejor experiencia de shell agéntica que existe.
Los trucos de edición de archivos y el minimalismo general también ayudan a que el agente sea más productivo.
Related MCP server: Claude Code Control MCP
[6 oct 2025] El modelo ahora puede ejecutar múltiples comandos en segundo plano. ZSH es ahora un shell compatible. Mejoras en la multiplexación.
[27 abr 2025] Se eliminó el soporte para GPTs a través de servidor de retransmisión. Solo se admite el servidor MCP en la versión >= 5.
[24 mar 2025] Experiencia de escritura y edición mejorada para sonnet 3.7, CLAUDE.md se carga automáticamente.
[16 feb 2025] Ahora puedes adjuntarte a la terminal de trabajo que utiliza la IA. Consulta la sección "attach-to-terminal" a continuación.
[15 ene 2025] Modos introducidos: arquitecto, escritor de código y el modo wcgw todopoderoso.
[8 ene 2025] Herramienta de guardado de contexto para guardar rutas de archivos relevantes junto con una descripción en un solo archivo. Se puede usar como punto de control de tareas o para transferencia de conocimientos.
[29 dic 2024] La comprobación de sintaxis en la escritura y edición de archivos es ahora estable. Se hizo útil la llamada a la herramienta initialize; enviando una estructura de repositorio inteligente a Claude si se hace referencia a algún repositorio. El manejo de archivos grandes también ha mejorado.
[9 dic 2024] Extensión de VS Code para pegar contexto en la aplicación Claude
⚡ Crear, Ejecutar, Iterar: Pídele a Claude que siga ejecutando comprobaciones del compilador hasta que se corrijan todos los errores, o pídele que siga comprobando el estado de un comando de larga duración hasta que termine.
⚡ Edición de archivos grandes: Admite ediciones incrementales de archivos grandes para evitar problemas de límite de tokens. Selecciona inteligentemente cuándo realizar ediciones pequeñas o una reescritura completa según el % de cambio necesario.
⚡ Comprobación de sintaxis en ediciones: Informa al LLM si sus ediciones tienen errores de sintaxis, para que pueda rehacerlas.
⚡ Manejo de comandos interactivos: Admite comandos interactivos usando teclas de flecha, interrupción y secuencias de escape ANSI.
⚡ Protecciones de archivos:
La IA necesita leer un archivo al menos una vez antes de que se le permita editarlo o reescribirlo. Esto evita sobrescrituras accidentales.
Evita que el contexto se llene al leer archivos muy grandes. Los archivos se dividen en fragmentos según la longitud del token.
En la inicialización, se devuelve la estructura de directorios del espacio de trabajo proporcionado después de seleccionar archivos importantes (basado en .gitignore así como en un enfoque estadístico).
La edición de archivos basada en buscar-reemplazar intenta encontrar el bloque de búsqueda correcto si tiene múltiples coincidencias basadas en bloques de búsqueda anteriores. De lo contrario, falla (por corrección).
La edición de archivos tiene una coincidencia tolerante al espaciado, con advertencia sobre problemas como la falta de coincidencia de sangría. Si no hay coincidencia, se devuelve la coincidencia más cercana a la IA para que corrija sus errores.
Utiliza buscar y reemplazar al estilo Aider, que tiene un mejor rendimiento que buscar y reemplazar basado en llamadas a herramientas.
⚡ Optimizaciones de shell:
El directorio de trabajo actual siempre se devuelve después de cualquier comando de shell para evitar que la IA se pierda.
El sondeo de comandos sale después de un tiempo de espera rápido para evitar una retroalimentación lenta. Sin embargo, la comprobación de estado tiene tolerancia de espera basada en la transmisión de salida nueva de un comando. Ambos enfoques combinados proporcionan una buena experiencia de interacción con el shell.
Admite múltiples comandos en segundo plano simultáneos junto con el shell interactivo principal.
⚡ Guardar contexto del repositorio en un solo archivo: El punto de control de tareas mediante la herramienta "ContextSave" guarda un contexto detallado en un solo archivo. Las tareas se pueden reanudar más tarde en un nuevo chat pidiendo "Resume task id". El archivo guardado se puede usar para realizar otros tipos de transferencia de conocimientos, como pedir ayuda a otra IA.
⚡ Cambiar fácilmente entre varios modos:
Pídele que se ejecute en modo 'arquitecto' para la planificación. Inspirado en el modo arquitecto de Aider, trabaja con Claude para elaborar un plan primero. Conduce a una mayor precisión y evita la edición prematura de archivos.
Pídele que se ejecute en modo 'escritor de código' para la edición de código y la construcción de proyectos. Puedes proporcionar rutas específicas con soporte de comodines para evitar que se editen otros archivos.
Por defecto, se ejecuta en modo 'wcgw' que no tiene restricciones y tiene autorización completa.
Más detalles en la sección de Modos
⚡ Se ejecuta en terminal multiplex: Usa la extensión de VS Code o ejecuta screen -x para adjuntarte a la terminal en la que la IA ejecuta comandos. Consulta el historial, interrumpe el proceso o interactúa con la misma terminal que usa la IA.
⚡ Cargar automáticamente CLAUDE.md/AGENTS.md: Carga el archivo "CLAUDE.md" o "AGENTS.md" en la raíz del proyecto y lo envía como instrucciones durante la inicialización. Las instrucciones en un archivo global "/.wcgw/CLAUDE.md" o "/.wcgw/AGENTS.md" se cargan y añaden junto con el CLAUDE.md específico del proyecto. El nombre del archivo distingue entre mayúsculas y minúsculas. CLAUDE.md se adjunta si está presente, de lo contrario se adjunta AGENTS.md.
Primero instala uv usando homebrew brew install uv
(Importante: usa homebrew para instalar uv. De lo contrario, asegúrate de que uv esté presente en una ubicación global como /usr/bin/)
Luego crea o actualiza claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json) con el siguiente json.
{
"mcpServers": {
"wcgw": {
"command": "uvx",
"args": ["--python", "3.12", "wcgw@latest"]
}
}
}Luego reinicia la aplicación Claude.
Opcional: Forzar un shell específico
Para usar un shell específico (bash o zsh), añade el argumento --shell:
{
"mcpServers": {
"wcgw": {
"command": "uvx",
"args": ["--python", "3.12", "wcgw@latest", "--shell", "/bin/bash"]
}
}
}Si hay un error en la configuración
Si hay un error como "uv ENOENT", asegúrate de que uv esté instalado. Luego ejecuta 'which uv' en la terminal y usa su salida en lugar de "uv" en la configuración.
Si el problema persiste, comprueba que uv tool run --python 3.12 wcgw se ejecute en tu terminal. No debería tener salida y no debería salir.
Intenta eliminar la carpeta ~/.cache/uv
Intenta usar la versión 0.6.0 de uv, con la cual se probó esta herramienta.
Depura el servidor mcp usando npx @modelcontextprotocol/inspector@0.1.7 uv tool run --python 3.12 wcgw
Este servidor mcp funciona solo en WSL en Windows.
Para configurarlo, instala uv
Luego añade o actualiza el archivo de configuración de Claude %APPDATA%\Claude\claude_desktop_config.json con lo siguiente
{
"mcpServers": {
"wcgw": {
"command": "wsl.exe",
"args": ["uvx", "--python", "3.12", "wcgw@latest"]
}
}
}Cuando encuentres un error, ejecuta el comando wsl uv --python 3.12 wcgw en el símbolo del sistema. Si obtienes el error /bin/bash: line 1: uv: command not found, significa que uv no se instaló globalmente y necesitas apuntar a la ruta correcta de uv.
Encuentra dónde está instalado uv:
whereis uvSalida de ejemplo:
uv: /home/mywsl/.local/bin/uv
Prueba que la ruta completa funcione:
wsl /home/mywsl/.local/bin/uv tool run --python 3.12 wcgwActualiza la configuración con la ruta completa:
{
"mcpServers": {
"wcgw": {
"command": "wsl.exe",
"args": ["/home/mywsl/.local/bin/uv", "tool", "run", "--python", "3.12", "wcgw"]
}
}
}Reemplaza /home/mywsl/.local/bin/uv con tu ruta real de uv del paso 1.
Espera unos segundos. Deberías poder ver este icono si todo sale bien.
por aquí
Luego pídele a Claude que ejecute comandos de shell, lea archivos, edite archivos, ejecute tu código, etc.
Puedes realizar un punto de control de tareas o una transferencia de conocimientos adjuntando el prompt "KnowledgeTransfer" usando el botón "Attach from MCP".
Al ejecutar el prompt "KnowledgeTransfer", se llamará a la herramienta "ContextSave", guardando la descripción de la tarea y todo el contenido del archivo juntos en un solo archivo. Se generará un ID para la tarea.
Puedes decir en un nuevo chat "Resume ''", la IA debería entonces llamar a "Initialize" con el ID de la tarea y cargar el contexto desde allí.
O puedes abrir directamente el archivo generado y compartirlo con otra IA para obtener ayuda.
Hay tres modos integrados. Puedes pedirle a Claude que se ejecute en uno de los modos, como "Use 'architect' mode"
Modo | Descripción | Permite | Deniega | Prompt de invocación |
Architect | Diseñado para que trabajes con Claude para investigar y entender tu repositorio. | Comandos de solo lectura | Herramientas FileEdit y Write | Run in mode='architect' |
Code-writer | Para escritura de código y desarrollo | Globs de ruta especificados para editar o escribir, comandos especificados | FileEdit para rutas que no coinciden con el glob especificado, Write para rutas que no coinciden con el glob especificado | Run in code writer mode, only 'tests/**' allowed, only uv command allowed |
wcgw | Modo predeterminado con todo permitido | Todo | Nada | Sin prompt, o "Run in wcgw mode" |
Nota: en el modo code-writer, por ahora, o todos los comandos están permitidos o ninguno. Si das una lista de comandos permitidos, se le indica a Claude que ejecute solo esos comandos, pero no ocurre ninguna comprobación real. (En desarrollo)
NUEVO: la extensión de VS Code ahora adjunta automáticamente la terminal en ejecución si la ruta del espacio de trabajo coincide.
Si tienes instalado el comando screen, wcgw se ejecuta automáticamente en una instancia de screen. Si has iniciado el servidor mcp wcgw, puedes listar las sesiones de screen:
screen -ls
Y anota el nombre de la pantalla wcgw que será algo como 93358.wcgw.235521 donde el último número está en formato hora-minuto-segundo.
Puedes adjuntarte a la sesión usando screen -x 93358.wcgw.235521
Puedes interrumpir cualquier comando en ejecución de forma segura.
Puedes interactuar con la terminal de forma segura, por ejemplo, para introducir contraseñas o introducir algún texto. (Advertencia: Si ejecutas un nuevo comando, cualquier comando nuevo del LLM lo interrumpirá.)
No deberías salir de la sesión usando exit o Ctrl-d, en su lugar deberías usar ctrl+a+d para desconectarte de forma segura sin destruir la sesión de screen.
Incluye lo siguiente en ~/.screenrc para una mejor experiencia de desplazamiento
defscrollback 10000
termcapinfo xterm* ti@:te@https://marketplace.visualstudio.com/items?itemName=AmanRusia.wcgw
Comandos:
Selecciona un texto y presiona cmd+' y luego introduce las instrucciones. Esto cambiará la aplicación a Claude y pegará un texto que contiene tus instrucciones, la ruta del archivo, el directorio del espacio de trabajo y el texto seleccionado.
Primero construye la imagen de docker docker build -t wcgw https://github.com/rusiaaman/wcgw.git
Luego puedes actualizar /Users/username/Library/Application Support/Claude/claude_desktop_config.json para tener
{
"mcpServers": {
"wcgw": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount",
"type=bind,src=/Users/username/Desktop,dst=/workspace/Desktop",
"wcgw"
]
}
}
}El servidor proporciona las siguientes herramientas MCP:
Operaciones de Shell:
Initialize: Restablecer shell y configurar el entorno del espacio de trabajo
Parámetros: any_workspace_path (string), initial_files_to_read (string[]), mode_name ("wcgw"|"architect"|"code_writer"), task_id_to_resume (string)
BashCommand: Ejecutar comandos de shell con control de tiempo de espera
Parámetros: command (string), wait_for_seconds (int, opcional)
Parámetros: send_text (string) o send_specials (["Enter"|"Key-up"|...]) o send_ascii (int[]), `wait_for
Execute a bash command. This is stateful (beware with subsequent calls).
Status of the command and the current working directory will always be returned at the end.
The first or the last line might be (...truncated) if the output is too long.
Always run pwd if you get any file or directory not found error to make sure you're not lost.
Do not run bg commands using "&", instead use this tool.
You must not use echo/cat to read/write files, use ReadFiles/FileWriteOrEdit
In order to check status of previous command, use status_check with empty command argument.
Only command is allowed to run at a time. You need to wait for any previous command to finish before running a new one.
Programs don't hang easily, so most likely explanation for no output is usually that the program is still running, and you need to check status again.
Do not send Ctrl-c before checking for status till 10 minutes or whatever is appropriate for the program to finish.
Only run long running commands in background. Each background command is run in a new non-reusable shell.
On running a bg command you'll get a bg command id that you should use to get status or interact.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | type of action. | |
| command | No | Set only if type="command" | |
| send_text | No | Set only if type="send_text" | |
| thread_id | Yes | ||
| send_ascii | No | Set only if type="send_ascii" | |
| status_check | No | Set only if type="status_check" | |
| bg_command_id | No | Set only if type!="command" and doing action on a running background command | |
| is_background | No | Set only if type="command" and running the command in background | |
| send_specials | No | Set only if type="send_specials" | |
| wait_for_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with annotations already signalling open and destructive behavior, the description adds substantial operational detail: commands are stateful, status and cwd are always returned, output may be truncated, background commands run in new non-reusable shells, and status must be polled before interrupting. These behaviors go well beyond what the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The bulleted format is front-loaded with the most critical caveat (statefulness) and each subsequent bullet carries actionable information for a high-complexity tool. There is minor redundancy between the one-command-at-a-time and wait-for-previous bullets, but overall the length is warranted by the tool's parameter count and interactive modes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with no output schema, the description does well to state that status and cwd are returned and to cover truncation, backgrounding, and status polling. The main gap is that the interactive input modes (send_text, send_ascii, send_specials) and wait_for_seconds are never explained in context, so an agent may not know how to drive an already-running command.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With roughly 80% schema coverage the baseline is 3, but the description adds useful parameter semantics: status_check must be called with an empty command argument, bg_command_id is the handle for interacting with a background command, and only one command may run at a time. However, it does not explain wait_for_seconds or how send_text/send_ascii/send_specials should be used with a running process.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Execute a bash command', a specific verb+resource, and immediately distinguishes the tool from file-focused siblings by forbidding echo/cat and directing the agent to ReadFiles/FileWriteOrEdit. It also clarifies stateful execution, which sets expectations beyond what the name alone implies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly names ReadFiles/FileWriteOrEdit as the alternatives for file I/O and instructs against shell backgrounding with '&'. It lacks an explicit 'when not to use' statement for the other sibling tools, and the background instruction ('instead use this tool') is slightly ambiguous, though the intent is recoverable from the schema's is_background field.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Saves provided description and file contents of all the relevant file paths or globs in a single text file.
Use the thread_id returned by Initialize when available; legacy clients may omit it.
Provide random 3 word unique id or whatever user provided.
Leave project path as empty string if no project path
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| thread_id | No | ||
| description | Yes | ||
| project_root_path | Yes | ||
| relevant_file_globs | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation Contradiction: the annotations declare readOnlyHint=true, yet the description says the tool 'saves' content into a single text file, implying a file-writing side effect. This directly contradicts the read-only hint. The description also does not clarify whether it reads from disk, writes a new file, overwrites anything, or what side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and uses bullets for parameter-specific guidance. It earns its length, but the sentence 'Provide random 3 word unique id or whatever user provided' is slightly informal and could be clearer about whether the id is required or user-supplied.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and a read/write ambiguity, the description omits important context: where the text file is saved, what happens after saving, how globs are resolved relative to project_root_path, and whether this is a mutating action. The contradiction with readOnlyHint makes the overall behavior especially incomplete for an agent deciding whether to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate, and it does: it explains thread_id as coming from Initialize, id as a random 3-word unique identifier, project_root_path as optional/empty when no project path, and relevant_file_globs as file paths or globs. It does not fully define every parameter's format, but adds substantial meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: saving a description and file contents into a single text file. It clearly identifies the inputs (description, file paths/globs) and output artifact. However, it does not explicitly distinguish itself from FileWriteOrEdit or explain exactly what 'save' produces or where, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The bullets give conditional usage hints such as using the thread_id from Initialize and leaving project_root_path empty when absent. However, there is no explicit guidance on when to use this tool versus sibling tools like ReadFiles or FileWriteOrEdit, and no exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes or edits a file based on the percentage of changes.
Use absolute path only (~ allowed).
First write down percentage of lines that need to be replaced in the file (between 0-100) in percentage_to_change
percentage_to_change should be low if mostly new code is to be added. It should be high if a lot of things are to be replaced.
If percentage_to_change > 50, provide full file content in text_or_search_replace_blocks
If percentage_to_change <= 50, text_or_search_replace_blocks should be search/replace blocks.
Instructions for editing files.
import numpy as np
from impls import impl1, impl2
def hello():
"print a greeting"
print("hello")
def call_hello():
"call hello"
hello()
print("Called")
impl1()
hello()
impl2()
<<<<<<< SEARCH
from impls import impl1, impl2
=======
from impls import impl1, impl2
from hello import hello as hello_renamed
>>>>>>> REPLACE
<<<<<<< SEARCH
def hello():
"print a greeting"
print("hello")
=======
>>>>>>> REPLACE
<<<<<<< SEARCH
def call_hello():
"call hello"
hello()
=======
def call_hello_renamed():
"call hello renamed"
hello_renamed()
>>>>>>> REPLACE
<<<<<<< SEARCH
impl1()
hello()
impl2()
=======
impl1()
hello_renamed()
impl2()
>>>>>>> REPLACEEvery "<<<<<<< SEARCH" section must EXACTLY MATCH the existing file content, character for character, including all comments, docstrings, whitespaces, etc.
Including multiple unique SEARCH/REPLACE blocks if needed. Include enough and only enough lines in each SEARCH section to uniquely match each set of lines that need to change.
Keep SEARCH/REPLACE blocks concise. Break large SEARCH/REPLACE blocks into a series of smaller blocks that each change a small portion of the file. Include just the changing lines, and a few surrounding lines (0-3 lines) if needed for uniqueness. Other than for uniqueness, avoid including those lines which do not change in search (and replace) blocks. Target 0-3 non trivial extra lines per block.
Preserve leading spaces and indentations in both SEARCH and REPLACE blocks.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | #1: absolute file path | |
| thread_id | Yes | #4: thread_id | |
| percentage_to_change | Yes | #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 | Yes | #3: content/edit blocks. Must be after #2 in the tool xml |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations specify destructiveHint: true, and the description details the editing process (full content replacement or search/replace). It explains the behavior regarding percentage threshold and formatting rules. No contradiction with annotations. The description adds context beyond annotations, such as the SEARCH/REPLACE format requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is quite long but well-structured with bullet points, headings, and an example. It is front-loaded with the main action and then details. While every part serves a purpose, it could be slightly more concise without losing necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, destructive behavior, no output schema), the description covers the editing method, percentage calculation, and formatting rules thoroughly. It lacks information on error handling, file creation behavior (if file doesn't exist), and return values, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema descriptions cover all parameters (100% coverage), the description significantly enhances meaning by explaining how percentage_to_change is calculated, the two modes for text_or_search_replace_blocks, and providing a full example with search/replace block rules. This goes well beyond the schema's brief descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes or edits a file, with specific instructions on using percentage-based changes. It distinguishes itself from siblings like BashCommand (shell commands) and ReadFiles/ReadImage (reading), leaving no ambiguity about its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidelines on when to use full file content vs. search/replace blocks based on percentage_to_change (>50 vs <=50). It also includes a detailed example and rules for SEARCH/REPLACE blocks. However, it does not explicitly state when to avoid using this tool in favor of siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Always call this at the start of the conversation before using any of the shell tools from wcgw.
Use any_workspace_path to initialize the shell in the appropriate project directory.
If the user has mentioned a workspace or project root or any other file or folder use it to set any_workspace_path.
If user has mentioned any files use initial_files_to_read to read, use absolute paths only (~ allowed)
By default use mode "wcgw"
In "code-writer" mode, set the commands and globs which user asked to set, otherwise use 'all'.
Use type="first_call" if it's the first call to this tool.
Use type="user_asked_mode_change" if in a conversation user has asked to change mode.
Use type="reset_shell" if in a conversation shell is not working after multiple tries.
Use type="user_asked_change_workspace" if in a conversation user asked to change workspace
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | ||
| mode_name | Yes | ||
| thread_id | Yes | Use the thread_id created in first_call, leave it as empty string if first_call | |
| allowed_globs | No | File globs that are allowed to be edited. Set to 'all' to allow all files, or provide a list of glob patterns. Only required when mode_name is 'code_writer'. | |
| allowed_commands | No | Shell commands that are allowed to be executed. Set to 'all' to allow all commands, or provide a list of command patterns. Only required when mode_name is 'code_writer'. | |
| task_id_to_resume | Yes | ||
| any_workspace_path | Yes | Workspace to initialise in. Don't use ~ by default, instead use empty string | |
| initial_files_to_read | Yes | Array of one or more files to read. Provide [] if no files mentioned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by detailing the initialization steps (setting workspace, reading files, configuring mode). It does not contradict the readOnlyHint=true annotation, as no destructive actions are mentioned. The description could mention if any session state is persisted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and uses a bulleted list format that is easy to scan. Each sentence carries clear instructions. It could be slightly more organized by grouping related parameters, but overall it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, no output schema, and annotations, the description covers main usage scenarios but lacks information about what the agent receives or any side effects. It assumes prior knowledge of the wcgw shell tools. This is adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema for key parameters like any_workspace_path, initial_files_to_read, mode_name, and allowed_globs. It explains default values and usage context. However, task_id_to_resume and thread_id are not elaborated, but schema coverage is high enough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is an initialization tool to be called at the start of the conversation before using shell tools. It specifies the resource (shell) and distinguishes from sibling tools by being a prerequisite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidelines for different call types (first_call, user_asked_mode_change, etc.) and explains when to set parameters like mode_name and allowed_globs. However, it does not explicitly say when not to use this tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read full file content of one or more files.
Use the thread_id returned by Initialize for this conversation when available; legacy clients may omit it.
Provide absolute paths only (~ allowed)
Only if the task requires line numbers understanding:
You may extract a range of lines. E.g., /path/to/file:1-10 for lines 1-10. You can drop start or end like /path/to/file:1- or /path/to/file:-10
| Name | Required | Description | Default |
|---|---|---|---|
| thread_id | No | ||
| file_paths | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only and closed-world, so no further safety disclosure is needed. The description adds useful operational behavior: path expectations, line-range syntax, and thread_id sourcing. It does not cover error or return behavior, but this is a minor gap for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight bullet points lead with the core purpose, and the conditional line-range rule is clearly nested. There is no filler; every sentence contributes to correct invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, read-only tool with no output schema, the description is nearly complete: it covers paths, line ranges, and thread_id. It does not specify how multiple file contents are returned, but the simple nature of the tool makes the output inferable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning, and it does. It explains file_paths as absolute paths with optional range syntax and clarifies thread_id availability ('returned by Initialize', 'legacy clients may omit it'), adding real semantics beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Read full file content of one or more files,' a specific verb-resource pair with clear scope (full content, multiple files). This distinguishes it from siblings such as FileWriteOrEdit, ReadImage, and BashCommand without needing to open schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete guidance: absolute paths only with ~ allowed, line-range extraction only when line numbers are needed, and reuse of thread_id from Initialize. It does not explicitly state when not to use this tool or name alternatives, but the conditional usage is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read an image from the shell. Use the thread_id returned by Initialize when available; legacy clients may omit it.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| thread_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, and the description does not contradict them. The added note about thread_id and legacy clients is useful behavioral context beyond the structured fields, but the description does not disclose other behaviors such as error cases or what happens when the image cannot be read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The primary action is front-loaded, and the optional parameter guidance is placed in the second sentence where it belongs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with minimal schema, the description covers the main input and the key optional parameter. Still, it lacks an explicit distinction from ReadFiles and does not mention what the tool returns, which would help an agent use it more reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It adds meaningful semantics for thread_id ('returned by Initialize... legacy clients may omit it'), but it says nothing about file_path beyond the schema's name and type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Read an image') and a resource/context ('from the shell'), so an agent can generally tell what the tool does. However, it does not explicitly distinguish ReadImage from the sibling ReadFiles, leaving some ambiguity about when the image-specific tool is preferred.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only guidance is about the thread_id parameter: use the one from Initialize when available, and legacy clients may omit it. There is no guidance about when to use ReadImage versus alternatives like ReadFiles or BashCommand, so tool-selection context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v5.6.6BashCommand1 field changedInput schema / additionalPropertiesRemoved value: -falseContextSave1 field changedInput schema / properties / thread_idAdded value: +{
+ "default": "",
+ "type": "string"
+}ReadFiles1 field changedInput schema / properties / thread_idAdded value: +{
+ "default": "",
+ "type": "string"
+}ReadImage1 field changedInput schema / properties / thread_idAdded value: +{
+ "default": "",
+ "type": "string"
+}v5.6.2BashCommand11 fields changedInput schema / $defsRemoved value: -{
- "ActionJsonSchema": {
- "additionalProperties": false,
- "properties": {
- "bg_command_id": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Set only if type!=\"command\" and doing action on a running background command"
- },
- "command": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Set only if type=\"command\""
- },
- "is_background": {
- "default": false,
- "description": "Set only if type=\"command\" and running the command in background",
- "type": "boolean"
- },
- "send_ascii": {
- "anyOf": [
- {
- "items": {
- "type": "integer"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Set only if type=\"send_ascii\""
- },
- "send_specials": {
- "anyOf": [
- {
- "items": {
- "enum": [
- "Enter",
- "Key-up",
- "Key-down",
- "Key-left",
- "Key-right",
- "Ctrl-c",
- "Ctrl-d"
- ],
- "type": "string"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Set only if type=\"send_specials\""
- },
- "send_text": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Set only if type=\"send_text\""
- },
- "status_check": {
- "anyOf": [
- {
- "const": true,
- "type": "boolean"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Set only if type=\"status_check\""
- },
- "type": {
- "description": "type of action.",
- "enum": [
- "command",
- "status_check",
- "send_text",
- "send_specials",
- "send_ascii"
- ],
- "type": "string"
- }
- },
- "required": [
- "type"
- ],
- "type": "object"
- }
-}Input schema / properties / action_jsonRemoved value: -{
- "$ref": "#/$defs/ActionJsonSchema"
-}Input schema / properties / bg_command_idAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Set only if type!=\"command\" and doing action on a running background command"
+}Input schema / properties / commandAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Set only if type=\"command\""
+}Input schema / properties / is_backgroundAdded value: +{
+ "default": false,
+ "description": "Set only if type=\"command\" and running the command in background",
+ "type": "boolean"
+}Input schema / properties / send_asciiAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Set only if type=\"send_ascii\""
+}Input schema / properties / send_specialsAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "enum": [
+ "Enter",
+ "Key-up",
+ "Key-down",
+ "Key-left",
+ "Key-right",
+ "Ctrl-c",
+ "Ctrl-d"
+ ],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Set only if type=\"send_specials\""
+}Input schema / properties / send_textAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Set only if type=\"send_text\""
+}Input schema / properties / status_checkAdded value: +{
+ "anyOf": [
+ {
+ "const": true,
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Set only if type=\"status_check\""
+}Input schema / properties / typeAdded value: +{
+ "description": "type of action.",
+ "enum": [
+ "command",
+ "status_check",
+ "send_text",
+ "send_specials",
+ "send_ascii"
+ ],
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "action_json",
- "thread_id"
-]New value: +[
+ "type",
+ "thread_id"
+]Initialize4 fields changedInput schema / $defsRemoved value: -{
- "CodeWriterMode": {
- "additionalProperties": false,
- "properties": {
- "allowed_commands": {
- "anyOf": [
- {
- "const": "all",
- "type": "string"
- },
- {
- "items": {
- "type": "string"
- },
- "type": "array"
- }
- ]
- },
- "allowed_globs": {
- "anyOf": [
- {
- "const": "all",
- "type": "string"
- },
- {
- "items": {
- "type": "string"
- },
- "type": "array"
- }
- ]
- }
- },
- "required": [
- "allowed_globs",
- "allowed_commands"
- ],
- "type": "object"
- }
-}Input schema / properties / allowed_commandsAdded value: +{
+ "anyOf": [
+ {
+ "const": "all",
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Shell commands that are allowed to be executed. Set to 'all' to allow all commands, or provide a list of command patterns. Only required when mode_name is 'code_writer'."
+}Input schema / properties / allowed_globsAdded value: +{
+ "anyOf": [
+ {
+ "const": "all",
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "File globs that are allowed to be edited. Set to 'all' to allow all files, or provide a list of glob patterns. Only required when mode_name is 'code_writer'."
+}Input schema / properties / code_writer_configRemoved value: -{
- "anyOf": [
- {
- "$ref": "#/$defs/CodeWriterMode"
- },
- {
- "type": "null"
- }
- ],
- "default": null
-}v1.0.0BashCommand2 fields changedInput schema / $defs / ActionJsonSchema / properties / bg_command_idAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Set only if type!=\"command\" and doing action on a running background command"
+}Input schema / $defs / ActionJsonSchema / properties / is_backgroundAdded value: +{
+ "default": false,
+ "description": "Set only if type=\"command\" and running the command in background",
+ "type": "boolean"
+}Initialize2 fields changedInput schema / properties / any_workspace_path / descriptionPrevious value: -"Workspce to initialise in. Don't use ~ by default, instead use empty string"New value: +"Workspace to initialise in. Don't use ~ by default, instead use empty string"Input schema / properties / initial_files_to_read / descriptionAdded value: +"Array of one or more files to read. Provide [] if no files mentioned."BashCommandContextSaveFileWriteOrEditInitializeReadFilesReadImageScored across 6 tools
Each tool serves a clearly distinct role: initialize the session, run shell commands, read text files, read images, write/edit files, and save context. The small amount of overlap between BashCommand and the file tools is explicitly resolved by usage rules that forbid echo/cat for reading and writing.
All names are PascalCase and generally readable, but the pattern is mixed: ReadFiles and ReadImage are verb-noun, ContextSave and FileWriteOrEdit are noun-verb, BashCommand is noun-like, and Initialize is a bare verb. The inconsistency is noticeable but not chaotic.
Six tools is a well-scoped count for a shell/file-oriented MCP server. Each tool earns its place, and the set is neither bloated nor too thin for its apparent purpose.
The server covers the core workspace lifecycle: initialization, command execution, file reading, image reading, file writing/editing, and context saving. Generic operations like listing, deleting, or renaming are delegated to BashCommand, which works but makes for a slight indirectness rather than a true gap.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
