run_shell_command - Execute Shell Commands

Overview

The run_shell_command tool executes shell commands as bash -c <command>. Commands can start background processes using &. Commands are executed as subprocesses that lead their own process group.

Tool Name

• Internal Name: run_shell_command
• Display Name: Shell
• Icon: Terminal

Parameters

Required Parameters

Parameter	Type	Description
command	string	Exact bash command to execute as bash -c <command>.

Optional Parameters

Parameter	Type	Description
description	string	Brief description of the command for the user. Be specific and concise. Ideally a single sentence. Can be up to 3 sentences for clarity. No line breaks.
directory	string	(OPTIONAL) Directory to run the command in, if not the project root directory. Must be relative to the project root directory and must already exist.

Features

1. Command Execution:

   • Executes commands as bash -c
   • Supports all bash syntax and features
   • Can execute complex command pipelines

2. Background Processes:

   • Start background processes using &
   • Returns background process PIDs
   • Can manage processes with kill command

3. Process Management:

   • Commands execute in independent process groups
   • Can terminate process groups with kill -- -PGID
   • Can send signals with kill -s SIGNAL -- -PGID

4. Real-time Output:

   • Supports real-time streaming output
   • Can see command execution progress
   • Output updates every second

Return Information

The tool returns the following information:

• Command: Executed command
• Directory: Directory where command was executed (relative to project root), or (root)
• Stdout: Output on stdout stream. Can be (empty) or partial on error and for any unwaited background processes
• Stderr: Output on stderr stream. Can be (empty) or partial on error and for any unwaited background processes
• Error: Error or (none) if no error was reported for the subprocess
• Exit Code: Exit code or (none) if terminated by signal
• Signal: Signal number or (none) if no signal was received
• Background PIDs: List of background processes started or (none)
• Process Group PGID: Process group started or (none)

Usage Examples

Basic Command

{
  "command": "ls -la",
  "description": "List all files in current directory"
}

Execute in Specific Directory

{
  "command": "npm install",
  "directory": "frontend",
  "description": "Install frontend dependencies"
}

Background Process

{
  "command": "node server.js &",
  "description": "Start development server"
}

Command Pipeline

{
  "command": "cat package.json | grep version",
  "description": "Find version in package.json"
}

Complex Command

{
  "command": "find . -name '*.ts' -type f | xargs wc -l | sort -n",
  "description": "Count lines in all TypeScript files and sort"
}

Conditional Execution

{
  "command": "npm run build && npm run test",
  "description": "Build project and run tests"
}

Security Features

1. Command Confirmation:

   • Shows command preview before execution
   • User can approve or cancel execution
   • Can set to always allow specific commands

2. Command Whitelist:

   • Certain commands can be whitelisted
   • Whitelisted commands don't require confirmation
   • Improves efficiency for common commands

3. Directory Restrictions:

   • Directory must be relative to project root
   • Cannot use absolute paths
   • Directory must already exist

4. Command Validation:

   • Validates command syntax
   • Checks for potentially dangerous operations
   • Provides security warnings

Error Handling

Possible error scenarios:

1. Command Errors:

   • Command not found
   • Command syntax error
   • Command execution failed

2. Directory Errors:

   • Directory does not exist
   • Directory is absolute path
   • No access permission

3. Execution Errors:

   • Process terminated
   • Timeout
   • Insufficient resources

Background Process Management

Start Background Process

node server.js &

View Background Processes

The tool returns background process PIDs:

Background PIDs: 12345
Process Group PGID: 12340

Terminate Background Process

# Terminate specific process
kill 12345

# Terminate entire process group
kill -- -12340

# Send specific signal
kill -s SIGTERM -- -12340

Command Examples

Development Tasks

# Start development server
npm run dev &

# Run tests
npm test

# Build project
npm run build

# Code linting
npm run lint

File Operations

# Find files
find . -name "*.ts"

# Search content
grep -r "TODO" src/

# Count lines
wc -l src/**/*.ts

# Copy files
cp config.example.json config.json

Git Operations

# View status
git status

# Commit changes
git add . && git commit -m "Update"

# Push code
git push origin main

# View log
git log --oneline -10

System Information

# View disk usage
df -h

# View memory usage
free -h

# View processes
ps aux | grep node

# View port usage
lsof -i :3000

Notes

1. Interactive Commands: Avoid shell commands that require user interaction (e.g., git rebase -i). Use non-interactive versions (e.g., npm init -y instead of npm init) when available. Interactive commands may cause hangs until canceled by the user.

2. Background Processes: Use background processes for commands unlikely to stop on their own (e.g., node server.js &). If unsure, ask the user.

3. Command Description: Provide clear command descriptions to help users understand what the command does.

4. Error Handling: Check command exit codes and error output, handle errors appropriately.

5. Resource Management: Be aware of resources (CPU, memory, disk) that commands may consume.

Related Tools

• read_file: Read command output files
• write_file: Write command input files
• search_file_content: Search command output
• glob: Find files to process