Shell Proxy

shellproxy

shellproxy は、AI エージェントの「ターミナルの視認性」の問題を解決する、クリーンなコマンド実行プロキシです。ゴミ文字、ANSI エスケープコード、シェル初期化時のノイズ、エンコーディングの問題によって、AI エージェントがターミナル出力を読み取れなくなる問題に対処します。

AI エージェントとターミナルの間に位置し、クリーンで制御された環境でコマンドを実行して、構造化された JSON 出力を返します。

---

機能

• ANSI の除去 — すべてのカラーコード、カーソル移動、制御シーケンスを削除します
• シェル初期化のバイパス — bash --norc --noprofile、PowerShell の -NoProfile などを使用して実行します
• シェルの自動検出 — Windows では WSL bash を優先し、利用できない場合は cmd にフォールバックします。Unix では bash/sh を使用します
• 構造化 JSON 出力 — exit_code、stdout、stderr、duration_ms、shell、truncated
• ストリーミングモード — 長時間実行されるコマンドの出力を行単位で返します
• ファイル出力 — stdout に加えて、結果をファイルに書き込みます
• MCP サーバー — run_command と run_command_stream を MCP ツールとして公開します
• 設定可能 — 環境変数、設定ファイル ~/.shellproxy.json、または CLI フラグで設定できます

---

インストール

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

ソースからインストール

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

---

使い方

コマンドを実行する（バッファー出力）

shellproxy run "echo hello world"

出力：

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

プレーンテキスト出力で実行する

shellproxy run --output text "ls -la"

出力を行単位でストリーミングする

shellproxy run --stream "npm install"

出力：

[stdout] added 342 packages in 4.2s
[stdout] found 0 vulnerabilities
--- exit_code: 0 | duration: 4213ms | shell: wsl ---

結果をファイルに書き込む

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

シェルを明示的に指定する

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

環境変数を設定する

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

タイムアウトを設定する

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

大きな出力を切り詰める

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

---

MCP サーバーモード

stdio 経由の MCP サーバーとして shellproxy を起動します。

shellproxy serve

AI クライアントの設定

AI クライアントの MCP 設定に shellproxy を追加します。

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

利用可能な MCP ツール

ツール	説明
run_command	コマンドを実行し、完全な JSON 結果を返します
run_command_stream	コマンドを実行し、出力を行単位で返します

run_command のパラメーター：

パラメーター	型	必須	説明
command	string	✓	実行するシェルコマンド
shell	string		auto、cmd、bash、wsl、pwsh、sh
cwd	string		作業ディレクトリ
timeout_seconds	number		タイムアウト（0 = 制限なし）
env	object		{"KEY": "VALUE"} 形式の追加の環境変数
truncate_bytes	number		出力の最大サイズ（バイト単位）

---

設定

shellproxy は、環境変数または JSON 設定ファイルで設定できます。

設定ファイル：~/.shellproxy.json

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

環境変数

変数	デフォルト	説明
SHELLPROXY_SHELL	auto	使用するシェル
SHELLPROXY_TIMEOUT	60	タイムアウト（秒）
SHELLPROXY_STRIP_ANSI	true	ANSI コードを除去します（無効にするには 0/false を指定）
SHELLPROXY_OUTPUT_MODE	buffered	buffered、stream、または file
SHELLPROXY_OUTPUT_FILE		ファイル出力モードで使用するファイルパス
SHELLPROXY_TRUNCATE_BYTES	0	出力を N バイトで切り詰めます
SHELLPROXY_CONFIG	~/.shellproxy.json	設定ファイルのパスを上書きします

---

グローバルフラグ

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

---

ソースからビルドする

# 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

---

ライセンス

MIT