Skip to content

Run command

run_command

RunCommandTool — execute shell commands with timeout and output truncation.

Registered as run_command via the axm.tools entry point.

RunCommandTool

Execute shell commands with timeout and output truncation.

Runs commands via subprocess.run with configurable timeout, output size caps, and a blocked-command safety list. Registered as run_command via axm.tools entry point.

Source code in packages/axm-edit/src/axm_edit/tools/run_command.py
Python
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
class RunCommandTool:
    """Execute shell commands with timeout and output truncation.

    Runs commands via ``subprocess.run`` with configurable timeout,
    output size caps, and a blocked-command safety list.
    Registered as ``run_command`` via axm.tools entry point.
    """

    agent_hint: str = (
        "Run a shell command in cwd. No cd/pipes/&&."
        " Returns stdout+stderr truncated to 4K chars."
        " Use for tests, builds, scripts."
    )

    @property
    def name(self) -> str:
        """Tool name used for MCP registration."""
        return "run_command"

    def execute(
        self,
        *,
        command: str | None = None,
        path: str = ".",
        cwd: str | None = None,
        timeout: int = _DEFAULT_TIMEOUT,
        **kwargs: object,
    ) -> ToolResult:
        """Execute a shell command.

        Args:
            command: Shell command string (required).
            path: Project root directory (default ".").
            cwd: Working directory, relative to root (optional).
            timeout: Timeout in seconds (default 30).

        Returns:
            ToolResult with stdout, stderr, exit_code, and timed_out.
        """
        root_str = path
        cwd_rel = cwd

        # ── Validate inputs ──────────────────────────────────────────
        if not command or not command.strip():
            return ToolResult(
                success=False,
                error="Missing required argument: command",
            )

        if _is_blocked(command):
            return ToolResult(
                success=False,
                error="Blocked command: this command is not allowed",
            )

        root = Path(root_str).resolve()
        if not root.is_dir():
            return ToolResult(
                success=False,
                error=f"Root is not a directory: {root_str}",
            )

        # Resolve cwd within the sandbox
        if cwd_rel:
            resolved_cwd = _resolve_safe(root, cwd_rel)
            if resolved_cwd is None:
                return ToolResult(
                    success=False,
                    error=f"cwd escapes project root: {cwd_rel}",
                )
            if not resolved_cwd.is_dir():
                return ToolResult(
                    success=False,
                    error=f"cwd is not a directory: {cwd_rel}",
                )
            work_dir = resolved_cwd
        else:
            work_dir = root

        # ── Execute ──────────────────────────────────────────────────
        return _run(command, work_dir, timeout)
name property

Tool name used for MCP registration.

execute(*, command=None, path='.', cwd=None, timeout=_DEFAULT_TIMEOUT, **kwargs)

Execute a shell command.

Parameters:

Name Type Description Default
command str | None

Shell command string (required).

 None
path str

Project root directory (default ".").

 '.'
cwd str | None

Working directory, relative to root (optional).

 None
timeout int

Timeout in seconds (default 30).

 _DEFAULT_TIMEOUT

Returns:

Type Description
ToolResult

ToolResult with stdout, stderr, exit_code, and timed_out.
Source code in packages/axm-edit/src/axm_edit/tools/run_command.py
Python
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def execute(
    self,
    *,
    command: str | None = None,
    path: str = ".",
    cwd: str | None = None,
    timeout: int = _DEFAULT_TIMEOUT,
    **kwargs: object,
) -> ToolResult:
    """Execute a shell command.

    Args:
        command: Shell command string (required).
        path: Project root directory (default ".").
        cwd: Working directory, relative to root (optional).
        timeout: Timeout in seconds (default 30).

    Returns:
        ToolResult with stdout, stderr, exit_code, and timed_out.
    """
    root_str = path
    cwd_rel = cwd

    # ── Validate inputs ──────────────────────────────────────────
    if not command or not command.strip():
        return ToolResult(
            success=False,
            error="Missing required argument: command",
        )

    if _is_blocked(command):
        return ToolResult(
            success=False,
            error="Blocked command: this command is not allowed",
        )

    root = Path(root_str).resolve()
    if not root.is_dir():
        return ToolResult(
            success=False,
            error=f"Root is not a directory: {root_str}",
        )

    # Resolve cwd within the sandbox
    if cwd_rel:
        resolved_cwd = _resolve_safe(root, cwd_rel)
        if resolved_cwd is None:
            return ToolResult(
                success=False,
                error=f"cwd escapes project root: {cwd_rel}",
            )
        if not resolved_cwd.is_dir():
            return ToolResult(
                success=False,
                error=f"cwd is not a directory: {cwd_rel}",
            )
        work_dir = resolved_cwd
    else:
        work_dir = root

    # ── Execute ──────────────────────────────────────────────────
    return _run(command, work_dir, timeout)