# 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)

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

### Windows (PowerShell)

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

### From source

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

---

## Usage

### Run a command (buffered)

```sh
shellproxy run "echo hello world"
```

Output:
```json
{
  "exit_code": 0,
  "stdout": "hello world\n",
  "stderr": "",
  "duration_ms": 12,
  "shell": "wsl",
  "truncated": false
}
```

### Run with plain text output

```sh
shellproxy run --output text "ls -la"
```

### Stream output line by line

```sh
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

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

### Specify a shell explicitly

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

### Inject environment variables

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

### Set a timeout

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

### Truncate large output

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

---

## MCP Server Mode

Start shellproxy as an MCP server over stdio:

```sh
shellproxy serve
```

### AI Client Configuration

Add shellproxy to your AI client's MCP config:

```json
{
  "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`

```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
# 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