The run_shell_command tool is your gateway to the operating system's shell, allowing you to execute arbitrary bash commands. This capability is essential for file system operations, running build scripts, installing dependencies, and more.
Basic Usage
To execute a command, provide the command string to the tool. You can also specify a working directory.
Handling Output
The tool returns standard output (stdout), standard error (stderr), and the exit code. Always check the exit code; a non-zero code usually indicates failure. For commands that produce massive output, be mindful of the token limit.
Token Efficiency
Large outputs consume your context window tokens. To maintain efficiency:
- Use flags to reduce verbosity (e.g.,
-qor--silent). - Filter output using
grep,head, ortailwithin the command itself. - Redirect output to a temporary file (e.g.,
command > temp.log) and then read specific lines usingread_fileorgrep.
Background Processes
For long-running tasks like starting a server, use the background operator & (e.g., npm start &). The tool will return the Process ID (PID), allowing you to continue working while the process runs. You can manage these processes using standard shell signals if needed.