execute_shell_command
Execute shell commands directly from the Serena MCP Server to run system operations, manage files, and perform terminal tasks with output capture.
Instructions
Execute a shell command and return its output.
IMPORTANT: you should always consider the memory about suggested shell commands before using this tool.
If this memory was not loaded in the current conversation, you should load it using the read_memory tool
before using this tool.
You should have at least once looked at the suggested shell commands from the corresponding memory
created during the onboarding process before using this tool.
Never execute unsafe shell commands like rm -rf / or similar! Generally be very careful with deletions. Returns a JSON object containing the command's stdout and optionally stderr output.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The shell command to execute. | |
| cwd | No | The working directory to execute the command in. If None, the project root will be used. | |
| capture_stderr | No | Whether to capture and return stderr output. | |
| max_answer_chars | No | If the output is longer than this number of characters, no content will be returned. Don't adjust unless there is really no other way to get the content required for the task. |
Implementation Reference
- src/serena/util/shell.py:15-42 (handler)The handler function that executes the given shell command in the specified directory, optionally capturing stderr, and returns structured output including stdout, stderr, return code, and cwd.
def execute_shell_command(command: str, cwd: str | None = None, capture_stderr: bool = False) -> ShellCommandResult: """ Execute a shell command and return the output. :param command: The command to execute. :param cwd: The working directory to execute the command in. If None, the current working directory will be used. :param capture_stderr: Whether to capture the stderr output. :return: The output of the command. """ if cwd is None: cwd = os.getcwd() is_windows = platform.system() == "Windows" process = subprocess.Popen( command, shell=not is_windows, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE if capture_stderr else None, creationflags=subprocess.CREATE_NO_WINDOW if is_windows else 0, # type: ignore text=True, encoding="utf-8", errors="replace", cwd=cwd, ) stdout, stderr = process.communicate() return ShellCommandResult(stdout=stdout, stderr=stderr, return_code=process.returncode, cwd=cwd) - src/serena/util/shell.py:8-12 (schema)Pydantic BaseModel defining the output schema for the shell command execution result.
class ShellCommandResult(BaseModel): stdout: str return_code: int cwd: str stderr: str | None = None