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

# Build for current platform
make build

# Build for all platforms
make build-all

# Run tests
make test

# Run specific test suites
make test-strip      # ANSI stripping tests
make test-detect     # Shell detection tests
make test-exec       # Integration exec tests

---

License

MIT