Shell Tool

Status: Planned

Execute shell commands on the host machine.

Capabilities

• Run any shell command
• Capture stdout/stderr
• Set working directory
• Set environment variables
• Timeout long-running commands

Interface

interface ShellTool extends Tool {
  name: "shell";

  execute(input: {
    command: string;
    cwd?: string;
    timeout?: number;
    env?: Record<string, string>;
  }): Promise<{
    stdout: string;
    stderr: string;
    exitCode: number;
  }>;
}

Example Usage

// Simple command
await shell.execute({ command: "ls -la" });

// With working directory
await shell.execute({
  command: "npm install",
  cwd: "/path/to/project"
});

// With timeout
await shell.execute({
  command: "npm run build",
  timeout: 60000  // 60 seconds
});

Security Considerations

Dangerous Commands

Some commands require extra confirmation:

• rm -rf
• sudo anything
• chmod/chown
• Package managers with --force

Sandboxing Options

• Run in Docker container
• Use firejail on Linux
• Restrict to certain directories

Logging

All commands are logged with:

• Timestamp
• Full command
• Working directory
• Exit code
• Truncated output

Open Questions

1. Should we support interactive commands?
2. How to handle commands that need user input?
3. Should we have a whitelist/blacklist of commands?