shellproxy

shellproxy is a clean command execution proxy for AI agents, solving the "terminal blindness" problem — garbage characters, ANSI escape codes, shell init noise, and encoding issues that make AI agents unable to read terminal output.

It sits between AI agents and terminals, executing commands in a clean, controlled environment and returning structured JSON output.

---

Features

- ANSI stripping — removes all color codes, cursor movements, and control sequences
- Shell init bypass — runs bash --norc --noprofile, PowerShell with -NoProfile, etc.
- Auto shell detection — prefers WSL bash on Windows, falls back to cmd; bash/sh on Unix
- Structured JSON output — exit_code, stdout, stderr, duration_ms, shell, truncated
- Streaming mode — line-by-line output for long-running commands
- File output — write results to a file in addition to stdout
- MCP server — exposes run_command and run_command_stream as MCP tools
- Configurable — env vars, config file ~/.shellproxy.json, or CLI flags

---

Installation

Unix (Linux, macOS, WSL)

curl -sSL https://raw.githubusercontent.com/aliforever/shellproxy/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/aliforever/shellproxy/main/install.ps1 | iex

From source

git clone https://github.com/aliforever/shellproxy
cd shellproxy
go build -o shellproxy .

---

Usage

Run a command (buffered)

shellproxy run "echo hello world"

Output:

{

  "exit_code": 0,

  "stdout": "hello world\n",

  "stderr": "",

  "duration_ms": 12,

  "shell": "wsl",

  "truncated": false

}

Run with plain text output

shellproxy run --output text "ls -la"

Stream output line by line

shellproxy run --stream "npm install"

Output:

[stdout] added 342 packages in 4.2s

[stdout] found 0 vulnerabilities

--- exit_code: 0 | duration: 4213ms | shell: wsl ---

Write result to file

shellproxy run --file /tmp/result.json "go build ./..."

Specify a shell explicitly

shellproxy run --shell cmd "dir"
shellproxy run --shell bash "cat /etc/os-release"
shellproxy run --shell pwsh "Get-Date"

Inject environment variables

shellproxy run --env "NODE_ENV=production" --env "PORT=8080" "node server.js"

Set a timeout

shellproxy run --timeout 30 "long-running-command"

Truncate large output

shellproxy run --truncate 4096 "cat large-file.log"

---

MCP Server Mode

Start shellproxy as an MCP server over stdio:

shellproxy serve

AI Client Configuration

Add shellproxy to your AI client's MCP config:

{
  "mcpServers": {
    "shellproxy": {
      "command": "shellproxy",
      "args": ["serve"],
      "env": {
        "SHELLPROXY_SHELL": "auto",
        "SHELLPROXY_TIMEOUT": "60"
      }
    }
  }
}

Available MCP Tools

| Tool | Description |
|------|-------------|
| run_command | Execute a command and return complete JSON result |
| run_command_stream | Execute a command and return output line-by-line |

run_command parameters:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| command | string | ✓ | Shell command to execute |
| shell | string | | auto, cmd, bash, wsl, pwsh, sh |
| cwd | string | | Working directory |
| timeout_seconds | number | | Timeout (0 = no limit) |
| env | object | | Extra env vars as {"KEY": "VALUE"} |
| truncate_bytes | number | | Max output size in bytes |

---

Configuration

shellproxy can be configured via environment variables or a JSON config file.

Config file: ~/.shellproxy.json

{
  "shell": "auto",
  "timeout_seconds": 60,
  "strip_ansi": true,
  "output_mode": "buffered",
  "output_file": "",
  "truncate_bytes": 0
}

Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| SHELLPROXY_SHELL | auto | Shell to use |
| SHELLPROXY_TIMEOUT | 60 | Timeout in seconds |
| SHELLPROXY_STRIP_ANSI | true | Strip ANSI codes (0/false to disable) |
| SHELLPROXY_OUTPUT_MODE | buffered | buffered, stream, or file |
| SHELLPROXY_OUTPUT_FILE | | File path for file output mode |
| SHELLPROXY_TRUNCATE_BYTES | 0 | Truncate output at N bytes |
| SHELLPROXY_CONFIG | ~/.shellproxy.json | Override config file path |

---

Global Flags

Flags:
  --shell string    Shell to use: auto, cmd, bash, wsl, pwsh, sh (default "auto")
  --timeout int     Command timeout in seconds 0 = no timeout (default 60)
  --strip-ansi      Strip ANSI escape codes from output (default true)
  -h, --help        help for shellproxy

---

Building from Source

```sh