python-sdk/docs/mcp/tools/shell.md

Shell & Command Tools

The shell tools (hanzo-tools-shell) provide comprehensive command execution with auto-backgrounding, DAG support, and process management.

cmd - Unified Command Execution

The cmd tool replaces traditional bash/shell commands with intelligent features:

# Simple command
cmd("ls -la")

# Sequential execution
cmd(["mkdir dist", "cp *.js dist/", "zip -r out.zip dist/"])

# Parallel execution
cmd(["npm install", "cargo build"], parallel=True)

# Mixed DAG
cmd([
    "mkdir dist",
    {"parallel": ["cp a dist/", "cp b dist/"]},
    "zip -r out.zip dist/"
])

Parameters

Parameter	Type	Default	Description
command	str	-	Single command to execute
commands	list	-	List of commands for DAG execution
parallel	bool	False	Run all commands in parallel
timeout	int	45	Per-command timeout in seconds
cwd	str	-	Working directory
env	dict	-	Environment variables
shell	str	zsh	Shell to use (zsh, bash, sh)
strict	bool	False	Stop on first error
quiet	bool	False	Suppress stdout

DAG Syntax

Execute complex dependency graphs:

# Named steps with dependencies
cmd([
    {"id": "build", "run": "make build"},
    {"id": "test", "run": "make test", "after": ["build"]},
    {"id": "deploy", "run": "make deploy", "after": ["test"]}
])

# Nested parallel blocks
cmd([
    "prepare",
    {"parallel": ["task_a", "task_b", "task_c"]},
    "finalize"
])

# Tool invocations
cmd([{"tool": "search", "input": {"pattern": "TODO"}}])

Auto-Backgrounding

Commands exceeding 30 seconds automatically background:

# This will auto-background after 30s
cmd("npm install")  # Returns immediately with process ID

# Disable auto-backgrounding
export HANZO_AUTO_BACKGROUND_TIMEOUT=0

ps - Process Management

Manage background processes:

# List all processes
ps()

# Get specific process
ps(id="cmd_abc123")

# View output logs
ps(logs="cmd_abc123", n=100)  # Last 100 lines

# Kill process
ps(kill="cmd_abc123")

# Kill with specific signal
ps(kill="cmd_abc123", sig=9)  # SIGKILL

Parameters

Parameter	Type	Default	Description
id	str	-	Process ID to query
logs	str	-	Process ID to get logs from
kill	str	-	Process ID to kill
sig	int	15	Signal for kill (15=SIGTERM, 9=SIGKILL)
n	int	100	Number of log lines

Shell-Specific Tools

zsh

Execute in zsh (default, most feature-rich):

zsh("echo $ZSH_VERSION")
zsh(["cmd1", "cmd2"], parallel=True)

bash

Execute in bash:

bash("echo $BASH_VERSION")
bash(["cmd1", "cmd2"])

dash

Execute in dash (POSIX-compliant, fastest):

dash("echo 'fast POSIX shell'")

Package Runners

npx

Run npm packages:

npx(package="prettier", args="--write .")
npx(package="http-server", args="-p 8080")  # Auto-backgrounds

uvx

Run Python packages:

uvx(package="ruff", args="check .")
uvx(package="mkdocs", args="serve")  # Auto-backgrounds

open

Open files or URLs in default application:

open(path="https://example.com")
open(path="./document.pdf")
open(path="/path/to/image.png")

Configuration

Environment Variables

Variable	Default	Description
HANZO_AUTO_BACKGROUND_TIMEOUT	45	Seconds before auto-backgrounding (0 to disable)
HANZO_DEFAULT_SHELL	zsh	Default shell for commands

VS Code Settings

{
  "hanzo.mcp.commandTimeout": 45,
  "hanzo.mcp.defaultShell": "zsh"
}

Best Practices

1. Use DAGs for Dependencies

# Good - explicit dependencies
cmd([
    {"id": "install", "run": "npm install"},
    {"id": "build", "run": "npm run build", "after": ["install"]}
])

# Avoid - relies on shell chaining
cmd("npm install && npm run build")

2. Parallel Where Possible

# Good - parallel independent tasks
cmd(["npm install", "cargo build", "go mod download"], parallel=True)

# Avoid - sequential when not needed
cmd("npm install")
cmd("cargo build")
cmd("go mod download")

3. Handle Long-Running Processes

# Start server (auto-backgrounds)
cmd("npm run dev")

# Check if running
ps()

# Get logs
ps(logs="cmd_xxx")

# Stop when done
ps(kill="cmd_xxx")

4. Use Environment Variables

cmd(
    "deploy.sh",
    env={
        "NODE_ENV": "production",
        "API_KEY": "${DEPLOY_KEY}"
    }
)