Shell Proxy

What is Shell Proxy?

Shell Proxy is a clean command execution proxy for AI agents that solves "terminal blindness" — garbage characters, ANSI escape codes, shell init noise, and encoding issues that prevent AI agents from reading terminal output. It sits between AI agents and terminals, executing commands in a controlled environment and returning structured JSON output.

How to use Shell Proxy?

Install Shell Proxy via a one-line script (curl for Unix, irm for Windows) or build from source using Go. Use shellproxy run "<command>" to execute commands locally, or run shellproxy serve to start the MCP server over stdio. Configure behavior via CLI flags, environment variables, or a JSON config file at ~/.shellproxy.json.

Key features of Shell Proxy

• Strips ANSI escape codes and control sequences from output
• Bypasses shell init files (bash --norc --noprofile, PowerShell -NoProfile)
• Automatically detects the best available shell (WSL on Windows, bash/sh on Unix)
• Returns structured JSON output with exit_code, stdout, stderr, duration_ms, shell, truncated
• Supports streaming mode for line-by-line output of long-running commands
• Provides MCP tools run_command and run_command_stream for AI agent integration

Use cases of Shell Proxy

• AI agents executing shell commands and needing clean, parseable output
• Running commands in automated workflows where ANSI codes would interfere with parsing
• Integrating shell command execution into MCP-compatible AI clients like Claude Desktop

FAQ from Shell Proxy

How does Shell Proxy differ from running a shell directly?

Shell Proxy strips ANSI escape codes, bypasses shell init files, and returns structured JSON instead of raw terminal output, making it ideal for AI agents that cannot parse garbled terminal text.

What shells does Shell Proxy support?

It supports auto-detection and explicit selection of cmd, bash, wsl, pwsh, sh, and falls back to cmd on Windows and bash/sh on Unix.

What runtime or dependencies are required?

Shell Proxy is a standalone binary that can be installed via install scripts or built from source with Go. No external runtime dependencies are needed beyond the target shell itself.

Where does command output and configuration live?

Output is printed to stdout (or written to a file with --file). Configuration lives in environment variables or the JSON config file at ~/.shellproxy.json.

What are the known limits of Shell Proxy?

Commands can be configured with a timeout (default 60 seconds) and output can be truncated at a specified byte limit. Streaming mode returns data line-by-line for long-running commands.