Skip to main content

execute_command

The execute_command tool runs CLI commands on the user's system. It allows AI Cockpit Reasoning 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 AI CockpitCodeIgnore system for file access control
  • Handles terminal escape sequences for clean output

Limitations​

  • Command access may be restricted by AI CockpitCodeIgnore 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 AI CockpitCodeIgnore 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 AI CockpitCodeIgnore 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, AI Cockpit Reasoning runs initialization commands like npm init -y followed by installing dependencies.
  • When building a web application, AI Cockpit Reasoning executes build commands like npm run build to compile assets.
  • When deploying code, AI Cockpit Reasoning runs git commands to commit and push changes to a repository.
  • When troubleshooting, AI Cockpit Reasoning executes diagnostic commands to gather system information.
  • When starting a development server, AI Cockpit Reasoning launches the appropriate server command (e.g., npm start).
  • When running tests, AI Cockpit Reasoning 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>