# execute_command

The `execute_command` tool runs CLI commands on the user's system. It allows Roo to perform system operations, install dependencies, build projects, start servers, and execute other terminal-based tasks needed to accomplish user objectives.

## Parameters

The tool accepts these parameters:

- `command` (required): The CLI command to execute. Must be valid for the user's operating system.
- `cwd` (optional): The working directory to execute the command in. If not provided, the current working directory is used.

## What It Does

This tool executes terminal commands directly on the user's system, enabling a wide range of operations from file manipulations to running development servers. Commands run in managed terminal instances with real-time output capture, integrated with VS Code's terminal system for optimal performance and security.

## When is it used?

- When installing project dependencies (npm install, pip install, etc.)
- When building or compiling code (make, npm run build, etc.)
- When starting development servers or running applications
- When initializing new projects (git init, npm init, etc.)
- When performing file operations beyond what other tools provide
- When running tests or linting operations
- When needing to execute specialized commands for specific technologies

## Key Features

- Integrates with VS Code shell API for reliable terminal execution
- Reuses terminal instances when possible through a registry system
- Captures command output line by line with real-time feedback
- Supports long-running commands that continue in the background
- Allows specification of custom working directories
- Maintains terminal history and state across command executions
- Handles complex command chains appropriate for the user's shell
- Provides detailed command completion status and exit code interpretation
- Supports interactive terminal applications with user feedback loop
- Shows terminals during execution for transparency
- Validates commands for security using shell-quote parsing
- Blocks potentially dangerous subshell execution patterns
- Integrates with RooIgnore system for file access control
- Handles terminal escape sequences for clean output

## Limitations

- Command access may be restricted by RooIgnore rules and security validations
- Commands with elevated permission requirements may need user configuration
- Behavior may vary across operating systems for certain commands
- Very long-running commands may require specific handling
- File paths should be properly escaped according to the OS shell rules
- Not all terminal features may work with remote development scenarios

## How It Works

When the `execute_command` tool is invoked, it follows this process:

1. **Command Validation and Security Checks**:
   - Parses the command using shell-quote to identify components
   - Validates against security restrictions (subshell usage, restricted files)
   - Checks against RooIgnore rules for file access permissions
   - Ensures the command meets system security requirements

2. **Terminal Management**:
   - Gets or creates a terminal through TerminalRegistry
   - Sets up the working directory context
   - Prepares event listeners for output capture
   - Shows the terminal for user visibility

3. **Command Execution and Monitoring**:
   - Executes via VS Code's shellIntegration API
   - Captures output with escape sequence processing
   - Throttles output handling (100ms intervals)
   - Monitors for command completion or errors
   - Detects "hot" processes like compilers for special handling

4. **Result Processing**:
   - Strips ANSI/VS Code escape sequences for clean output
   - Interprets exit codes with detailed signal information
   - Updates working directory tracking if changed by command
   - Provides command status with appropriate context

## Terminal Implementation Details

The tool uses a sophisticated terminal management system:

1. **First Priority: Terminal Reuse**
   - The TerminalRegistry tries to reuse existing terminals when possible
   - This reduces proliferation of terminal instances and improves performance
   - Terminal state (working directory, history) is preserved across commands

2. **Second Priority: Security Validation**
   - Commands are parsed using shell-quote for component analysis
   - Dangerous patterns like `$(...)` and backticks are blocked
   - Commands are checked against RooIgnore rules for file access control
   - A prefix-based allowlist system validates command patterns

3. **Performance Optimizations**
   - Output is processed in 100ms throttled intervals to prevent UI overload
   - Zero-copy buffer management uses index-based tracking for efficiency
   - Special handling for compilation and "hot" processes
   - Platform-specific optimizations for Windows PowerShell

4. **Error and Signal Handling**
   - Exit codes are mapped to detailed signal information (SIGTERM, SIGKILL, etc.)
   - Core dump detection for critical failures
   - Working directory changes are tracked and handled automatically
   - Clean recovery from terminal disconnection scenarios

## Examples When Used

- When setting up a new project, Roo runs initialization commands like `npm init -y` followed by installing dependencies.
- When building a web application, Roo executes build commands like `npm run build` to compile assets.
- When deploying code, Roo runs git commands to commit and push changes to a repository.
- When troubleshooting, Roo executes diagnostic commands to gather system information.
- When starting a development server, Roo launches the appropriate server command (e.g., `npm start`).
- When running tests, Roo executes the test runner command for the project's testing framework.

## Usage Examples

Running a simple command in the current directory:
```
<execute_command>
<command>npm run dev</command>
</execute_command>
```

Installing dependencies for a project:
```
<execute_command>
<command>npm install express mongodb mongoose dotenv</command>
</execute_command>
```

Running multiple commands in sequence:
```
<execute_command>
<command>mkdir -p src/components && touch src/components/App.js</command>
</execute_command>
```

Executing a command in a specific directory:
```
<execute_command>
<command>git status</command>
<cwd>./my-project</cwd>
</execute_command>
```

Building and then starting a project:
```
<execute_command>
<command>npm run build && npm start</command>
</execute_command>
```