Shell Proxy
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.
Overview
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_commandandrun_command_streamas 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
Server Config
{
"mcpServers": {
"shellproxy": {
"command": "shellproxy",
"args": [
"serve"
],
"env": {
"SHELLPROXY_SHELL": "auto",
"SHELLPROXY_STRIP_ANSI": "true",
"SHELLPROXY_TIMEOUT": "60"
}
}
}
}Project Info
Created At
3 months agoUpdated At
3 months agoAuthor Name
aliforeverStar
-Language
-License
-Recommend Servers
View AllPlaywright Mcp
@microsoft
Playwright MCP server
TypeScript
10 months ago
Amap Maps
@amap
高德地图官方 MCP Server
a year ago
Serper MCP Server
@garymengcom
A Serper MCP Server
Python
a year ago