execute_shell_command
Run shell commands securely within the Serena MCP Server environment to execute tasks directly on your codebase. Capture stdout and stderr outputs while ensuring safe command execution practices to protect your system.
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 |
|---|---|---|---|
| capture_stderr | No | Whether to capture and return stderr output. | |
| 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. | |
| 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 core handler function that executes a shell command using subprocess, handling Windows specifics, capturing output and error streams based on parameters, and returning structured result.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 input/output schema for shell command results, including stdout, stderr, return code, and current working directory.class ShellCommandResult(BaseModel): stdout: str return_code: int cwd: str stderr: str | None = None