terminal-use

terminal-use

AI エージェントが人間と同じように実際のターミナルを使えるようにする MCP サーバーです。入力、キー操作、クリック、画面の読み取り、スクリーンショットの撮影ができます。

上の各フレームは terminal-use 独自のスクリーンショットレンダラーで描画されており、それぞれに、そのフレームを生成したツール呼び出しのキャプションが付いています。

多くのエージェント用シェルツールは、コマンドを実行して出力を返します。これでは、vim、htop、REPL、質問に答える必要のあるインストーラー、git rebase -i、SSH セッションなどの対話的な操作には対応できません。terminal-use は、実際のターミナルエミュレーターで描画される実際の疑似端末上のシェルをエージェントに提供します。そのため、全画面プログラムや対話型プログラムが動作し、エージェントは人間が見るのと同じ画面を確認できます。

• 実際の PTY、実際のエミュレーター — 色、カーソル移動、代替画面をエスケープコードとしてそのまま渡すのではなく、解釈します。
• テキストとピクセル — 画面をプレーンテキストで読み取ることも、レイアウトや色が重要な場合に PNG として読み取ることもできます。
• 適切な待機 — コマンドが実際に終了するまで、または特定のテキストが表示されるまで待機します。
• 一緒に操作 — 任意のセッションに自分のターミナルを接続し、エージェントと並行して入力できます。

クイックスタート

macOS、Linux、Windows では Node.js 22.12 以降が必要です。

クライアントを選択してください。

クライアント	追加方法
Claude Code	claude mcp add terminal-use --scope user -- npx -y terminal-use
Cursor	Cursor に追加
VS Code	VS Code に追加
Codex	codex mcp add terminal-use -- npx -y terminal-use
Gemini CLI	gemini mcp add -s user terminal-use npx -y terminal-use

Claude Desktop、およびコマンドを指定できるその他のクライアント：MCP 設定に以下を追加してください（Claude Desktop の場合：Settings → Developer → Edit Config）。

{
  "mcpServers": {
    "terminal-use": {
      "command": "npx",
      "args": ["-y", "terminal-use"]
    }
  }
}

クライアントで新しいセッションを開始し、ターミナルで何かを行うよう依頼してください。たとえば、次のように指示できます。「vim を開いて、/tmp/haiku.txt に俳句を書いて保存して終了し、cat で表示したスクリーンショットを見せてください。」

サーバーオプションはコマンドの後に指定します：npx -y terminal-use --cols 100 --rows 40。

オプション	デフォルト
--shell <path>	$SHELL または /bin/bash。Windows では PowerShell	新しいセッションで実行するシェル
--cwd <path>	サーバーの起動場所	新しいセッションの作業ディレクトリ
--cols <n> / --rows <n>	120 / 30	ターミナルのサイズ
--scrollback <n>	5000	保持する履歴の行数
--login	オフ	ログインシェルとしてシェルを起動します（下記参照）

セッション内で「command not found」と表示される場合

自分のターミナルでは使えるプログラム（node、brew、pyenv…）がセッション内で見つからない場合、サーバーが最小限の環境を引き継いでいる可能性があります。これは、MCP クライアントをターミナルではなく Dock やランチャーから起動した場合に起こります。PATH はシェルのプロファイルファイル（~/.zprofile、~/.bash_profile、~/.profile）で設定されますが、それらが読み込まれていないためです。

ログインシェルはこれらのファイルを読み込みます。--login サーバーフラグを使えば、すべてのセッションで有効にできます。また、terminal_create に login: true を指定すれば、個別のセッションで有効にできます。シェルの起動が遅くなり、プロファイルに記述された処理も実行されるため、デフォルトではオフになっています。ログインモードのない PowerShell や cmd.exe には影響しません。

ツール

terminal_create と terminal_list 以外のすべてのツールは、terminal_create が返す sessionId を受け取ります。

ツール	機能
terminal_create	セッションを開始します。対話型シェル、または command を指定して単一のプログラムを実行します。label、cols、rows、shell、cwd、env、login、scrollback、theme は省略可能です。
terminal_list	セッションを一覧表示します。
terminal_destroy	セッションを終了します。
terminal_type	テキストを入力します。\n は Enter キーを押します。paste: true を指定すると、テキストをまとめて貼り付けます。
terminal_press	キーまたはキーの組み合わせを押します。例：Enter、Ctrl+C、ArrowUp、Shift+Tab、Alt+Enter、F5…
terminal_wait	実行中のコマンドの終了、正規表現に一致する文字列の表示、または出力が止まるまで待ちます。
terminal_read	画面またはスクロールバックをテキストとして読み取ります。
terminal_screenshot	画面を PNG として描画します。
terminal_click	プレビューを経て、セルを左クリックします。
terminal_scroll	セル上でマウスホイールを回します。
terminal_batch	1 回の呼び出しで複数の入力を送り、画面を一度だけ取得します。
terminal_resize	ターミナルのサイズを変更します。
terminal_reset	画面とスクロールバックを消去するか、hardReset: true でシェルを再起動します。

Docker

リポジトリには、サーバーをコンテナ内で実行するための Dockerfile があります。

docker build -t terminal-use .
docker run -i --rm -v "$PWD":/workspace terminal-use

MCP クライアントでは、コマンドに docker を指定し、引数として run -i --rm terminal-use を使用してください。エージェントが使用するターミナルは、マシン上ではなくコンテナ内のシェルになります。マウントしたものだけが見えるため、隔離したい場合に役立ちます。この構成では、自分のターミナルから接続することはできません。

スキル

terminal-use には Agent Skill が付属しています。ツールをうまく使うためのエージェント向けガイドで、コマンドセッションを使うタイミング、待機方法、選択中の内容の読み取り方に加え、vim、ページャー、REPL、メニュー形式のプログラム、ssh プロンプト、TUI のエンドツーエンドテストのレシピが含まれています。場所は skills/terminal-use です。

• MCP サーバーからスキルを読み込むホストでは、自動的に利用できます。サーバーは MCP Skills 拡張機能（io.modelcontextprotocol/skills）を実装しており、スキルは skills/list に表示され、そのファイルは skill://terminal-use/... リソースとして提供されます。現時点では、これに対応しているホストはほとんどありません。

• ディスクからスキルを読み込むホストでは、同じファイルをインストールできます。Claude Code の場合：

  cp -r "$(npx -y terminal-use skills-dir)/terminal-use" ~/.claude/skills/
  

スキルは任意です。スキルがなくても、エージェントはツールの説明とサーバーに組み込まれた指示を利用できます。

シェルセッションとコマンドセッション

デフォルトでは、セッションは対話型シェルです。プロンプトに対して行うのと同じように、コマンドを入力します。

ターミナル内で単一のプログラムを実行するには、terminal_create に command を渡します。

{"command": "npm test -- --watch", "cwd": "/path/to/project", "env": {"CI": "1"}}

コマンドはセッションのシェル（sh -c、PowerShell の -Command、または cmd /c）を経由するため、引用符、パイプ、リダイレクトはそのシェルのプロンプトと同じように機能します。入力はプログラムに直接送られます。プログラムの終了時には、次のようになります。

• 終了ステータスが報告されます（実行中だった呼び出し、terminal_wait、terminal_list で確認できます）。
• 最終画面は terminal_read と terminal_screenshot で引き続き読み取れます。
• 入力ツールは、何かを再起動するのではなく、終了ステータスを含むエラーを返します。
• hardReset: true を指定した terminal_reset ではプログラムが再実行され、terminal_destroy ではプログラムが削除されます。

CLI や TUI のテストにはこのモードを使います。起動し、操作し、終了時の状態を確認します。

画面を見ながら入力する

terminal_create は、セッションに参加するために自分のターミナルで実行できるコマンドを返します。

node /path/to/terminal-use/bin/terminal-use.js attach 3 --socket /tmp/terminal-use-501/41234-3.sock

エージェントが見ている画面を確認し、同じシェルに入力できます。共有 tmux セッションのように動作し、複数人が同時に接続できます。Ctrl+] で切断します。

• 接続すると、空のターミナルではなく、現在の画面と最近のスクロールバックが表示されます。
• --resize を指定すると、セッションがウィンドウサイズに合わせて変化します。デフォルトでは、セッションは独自のサイズを維持します。
• --socket でサーバーを選択します。各 MCP クライアントはそれぞれ独自の terminal-use を実行し、すべてセッション番号を 1 から割り当てます。--socket を指定しない場合、attach <id> はその ID を持つ実行中のサーバーが 1 つだけなら接続し、複数ある場合は候補を一覧表示します。
• Windows では、ソケットファイルの代わりに名前付きパイプを介してセッションに接続します。提示されるコマンドは同じように使えます。
• ソケットはユーザーごとに作成されます（0600。システムの一時ディレクトリ内にある 0700 のディレクトリ内）。接続できる人は誰でもあなたのユーザーとしてシェルを使えるため、それ以上に公開されることはありません。

仕組み

agent ──MCP──▶ terminal-use ──▶ node-pty ──▶ your shell
                  │
                  └─ @xterm/headless  ◀── everything the shell prints
                        │
                        ├─ terminal_read        (text)
                        └─ terminal_screenshot  (PNG)

node-pty は疑似端末上でシェルを実行します。出力はすべてヘッドレスの xterm.js エミュレーターに渡され、そのエミュレーターのバッファーが唯一の信頼できる情報源となります。読み取りとスクリーンショットはどちらもこのバッファーから取得されるため、エージェントにはエスケープコードのストリームではなく、描画された画面が渡されます。

詳細

処理の待機

terminal_type、terminal_press、terminal_click は、出力がしばらく静かになった時点（idleMs。デフォルトは 200 ms）で戻り、待機時間は最大 10 秒です。これはキー入力には適していますが、完了まで長い間出力が止まることもあるビルドには適していません。時間のかかる処理では、続けて terminal_wait を使ってください。

• デフォルト — コマンドの終了を待機します。 terminal-use は、ターミナルのフォアグラウンドをどのプロセスが所有しているかをカーネルに問い合わせます。シェルは実行する各コマンドにターミナルを渡し、コマンドの終了後に取り戻します。そのため、シェルが再び所有していれば、プロンプトが戻っています。シェルとの連携やプロンプトの解析は不要で、何も出力しないコマンドでも機能します。
• pattern — 画面上で正規表現に一致するまで待機します。 終了しない処理（Listening on port）、REPL のプロンプト、または TUI の特定の状態を待つ場合に使います。^ と $ は行頭と行末に一致します。先頭に (?i) または (?s) を付けると、追加のフラグを設定できます。
• until: "quiet" — 出力が止まるまで待機します。 quietMs（デフォルトは 1 s）の間、出力が止まるまで待ちます。タイピング用ツールと同じルールですが、10 秒の上限はありません。

コマンドセッションでは、デフォルトのモードはプログラムの終了を待ち、終了ステータスを報告します。

timeoutMs のデフォルトは 30 秒で、最大 10 分です。タイムアウトはエラーではありません。応答にはコマンドがまだ実行中であることが示されるため、再度待機できます。

Windows ではターミナルの所有者を確認する方法がないため、シェルセッションでデフォルトのモードを使うと、代わりに 2 秒間出力がない状態を待ち、推定であることが示されます。Windows では pattern を使うか、すべてのプラットフォームで終了を待てるコマンドセッションとしてプログラムを実行してください。

把握しておきたい制限事項：バックグラウンドジョブ（cmd &）は実行中として扱われません。ssh や REPL のようなネストされたプログラム内では、そのプログラムが終了するまで外側のシェルにフォアグラウンドが戻らないため、pattern または until: "quiet" を使ってください。終了ステータスは報告されません。echo $? を実行してください。

画面を読み取る

terminal_read は、画面サイズごとに分割したテキストを返します。page: 0 は現在の画面、page: 1 はその前の画面を表し、スクロールバックをさかのぼって取得できます。

端末の右端で折り返された行は、プログラムが出力した1行につなぎ直されます（joinWrapped: false にすると、画面上の各行が1行ずつ返されます）。

テキストでは色を表示できないため、選択中のメニュー項目はわかりません。そのため、読み取り結果の末尾には、画面上で反転表示または背景色付きでハイライトされている項目の一覧が、terminal_click で使う行と列とともに表示されます。

Highlighted on screen (reverse video or background color; screen row, columns):
  row 7, cols 3-18: "Unstaged changes"

画面の大部分が色付きのパネルで占められている場合、この一覧の代わりに terminal_screenshot への案内が表示されます。highlights: false を指定すると無効になります。

カーソルは ▌ で示されます。空白セルでは、その位置に表示されます。文字上にある場合は、その文字の前に挿入されるため、その行の残りの文字が1列右にずれます。ヘッダーにはカーソルが重なっている文字が示されます。プログラムがカーソルを非表示にしている間（ほとんどの全画面プログラムが該当します）は、このマーカーは表示されません。また、cursor: false を指定すると、テキストは変更されずに返されます。

スクリーンショット

terminal_screenshot は、同梱の JetBrains Mono を使って画面を描画します。以下は、vim で範囲を視覚的に選択した状態での呼び出し結果です。

セッションの作成時に theme を指定できます。選択肢は dark（デフォルト）、light、solarized-dark、solarized-light です。

JetBrains Mono は、ラテン文字、ギリシャ文字、キリル文字、罫線文字、一般的な記号に対応しています。絵文字、中国語・日本語、韓国語のテキストはシステムに既にインストールされているフォントにフォールバックします。これらのフォントを同梱すると、サイズが数十メガバイト増えるためです。

	絵文字	CJK	ハングル
macOS	Apple Color Emoji	Hiragino Sans GB / PingFang	Apple SD Gothic Neo
Windows	Segoe UI Emoji	Microsoft YaHei / Yu Gothic	Malgun Gothic
Linux	Noto Color Emoji	Noto Sans CJK	Noto Sans CJK

macOS ではこれらのフォントが標準でインストールされており、Windows には絵文字フォントが含まれています（東アジア言語用のフォントは、対応する言語機能とともにインストールされます）。Debian または Ubuntu では、apt install fonts-noto-color-emoji fonts-noto-cjk でインストールできます。これらのフォントがない環境（最小構成の Docker イメージなど）では、スクリーンショット上で該当する文字が空白の四角形として表示されます。Nerd Font と Powerline のアイコンは、どの環境でも四角形として表示されます。terminal_read には影響せず、常に実際の文字が返されます。

入力、貼り付け、バッチ処理

terminal_type は文字をキー入力として送信します。エディター、REPL、シェルのプロンプトに複数行のテキストを入力する場合は、paste: true を追加してください。ブラケット付き貼り付けに対応しているプログラムでは、テキスト全体が1回の貼り付けとして送られ、自動インデントや行ごとの実行を行わずにそのまま挿入されます。対応していないプログラムには、通常の文字が送信されます。

terminal_batch は、1回の呼び出しで入力のリストを送信し、最後に1回だけ画面を返します。手順があらかじめわかっている場合、キー入力ごとの往復を省けます。

{
  "sessionId": 1,
  "actions": [
    {"type": "press", "key": "ArrowDown", "count": 3},
    {"type": "press", "key": "Enter"},
    {"type": "wait", "pattern": "Commit message"},
    {"type": "type", "text": "Fix typo"},
    {"type": "press", "key": "Ctrl+S"}
  ]
}

アクションには type、paste、press、click、scroll、wait があります。wait では固定の ms または表示を待つ pattern を指定します。バッチは送信前に検証され、最初に失敗したアクションで停止し、どこまで実行できたかが報告されます。

クリックとスクロール

• 左ボタンのみです。座標は1始まりで、(1, 1) が左上のセルです。
• preview はデフォルトで有効です。 プレビューでは、対象セルを囲むリングが描かれたスクリーンショットが返され、クリックは送信されません。クリックするには、preview: false を指定して再度呼び出します。全画面プログラムでは、破壊的な操作がワンクリック先にあることが多いため、このひと手間をかける価値があります。
• terminal_scroll はセルの上でホイールを動かします。マウスを追跡するプログラムにはその位置でホイールイベントが送られるため、ポインターの下にあるペインがスクロールします。マウスを追跡しない全画面プログラム（less、man）では、通常のターミナルと同じように矢印キーが送られます。シェルプロンプトではスクロールするものがありません。以前の出力を読むには、terminal_read と page を使ってください。
• 実際にクリックするには、プログラム側でマウスレポートを有効にしている必要があります。set mouse=a を設定した vim、fzf、lazygit、htop、およびほとんどの最新の TUI では有効になっています。通常のシェルプロンプトでは、コマンドラインにエスケープコードを出力する代わりに、呼び出しはエラーを返します。

セッションのライフサイクル

• セッションはそれぞれ独立しています。同一セッションへの呼び出しは順番に実行されますが、異なるセッションへの呼び出しは互いをブロックしません。
• シェルセッションのシェルが終了した場合、セッションが6時間アイドル状態になった場合、または50セッションの上限に達した場合、セッションはシャットダウンされますが、その ID は30日間予約されたままになります。その ID への次の呼び出しでは、同じサイズ、シェル、作業ディレクトリ、テーマで新しいシェルが起動し、何が起きたかを示す通知が返されます。シェルが自ら終了した場合は、古いシェルの最後の画面も含まれます。その呼び出しで指定したコマンドは実行されないため、引き続き実行したい場合は再度送信してください。
• アイドル状態とは、ツール呼び出しも出力もない状態です。出力を続けている開発サーバーはアイドル状態ではありません。
• terminal_destroy はセッションを完全に終了させます。その ID は予約されません。
• MCP クライアントが切断された場合、またはサーバーが停止した場合、すべてのシェルが閉じられ、すべてのアタッチソケットが削除されます。

プロトコルのサポート

公式の MCP TypeScript SDK（v2）を基盤にしています。stdio 経由では、ステートレスなプロトコルの2026-07-28版と、それ以前のハンドシェイク方式の各版の両方に対応しています。どちらを使うかは、クライアントの最初のメッセージで決まります。

ステートレスなのはプロトコルであり、ターミナルではありません。セッションはサーバープロセス内に保持され、各呼び出しで渡す sessionId を使ってアクセスします。またサーバーは、各ツールの使用方法、タイトル、動作に関するヒント、キャンセル、terminal_wait からの進捗更新、および上記の Skills 拡張機能も提供します。

プラットフォームのサポート

macOS (arm64, x64)	対応。CI でテスト済み
Linux (arm64, x64)	対応。Node 22 および 26 で CI テスト済み
Windows (x64)	対応。PowerShell および cmd.exe で CI テスト済み

Windows では、セッションは ConPTY 経由で実行され、デフォルトのシェルは Windows PowerShell です。また、次の2点が異なります。terminal_wait ではシェルコマンドの完了を検出できません（処理の完了を待つを参照）。また、login は何もしません。

ネイティブ依存関係（node-pty、@napi-rs/canvas）にはビルド済みバイナリが同梱されているため、インストールにコンパイラーは不要です。

開発

git clone https://github.com/computer-agent-labs/terminal-use.git
cd terminal-use
yarn install
yarn build      # compile src/ to dist/
yarn test       # build, then run the full suite

その他のスクリプト：

yarn dev            # run the server straight from source
yarn lint           # eslint
yarn typecheck      # tsc, no output
yarn test:unit      # unit tests only
yarn test:windows   # what CI runs on Windows: shell-independent tests + tests/windows
yarn smoke          # quick end-to-end check without an MCP client
yarn demo           # regenerate docs/demo.gif (needs ffmpeg, vim and python3)

ローカルのチェックアウトを MCP クライアントで使うには、ビルドして bin スクリプトへのパスを指定します。

claude mcp add terminal-use --scope user -- node "$PWD/bin/terminal-use.js"

コードはレイヤーごとに構成されています。src/pty（起動、キーとマウスのエンコード）、src/emulator（xterm バッファー、描画、待機）、src/session（1つのターミナル）、src/attach（接続に使うソケット）、src/mcp（ツール）です。エージェントスキルは skills/ にあります。

セキュリティ

terminal-use は、接続されたクライアントに、サンドボックスなしであなたとして実行される、あなたのマシン上のシェルを提供します。ターミナルへのアクセスを信頼できるクライアントにのみ接続し、クライアントのツール承認設定を使って、確認なしで実行される内容を制御してください。ネットワークポートは開かず、アタッチソケットへのアクセスは自分のユーザーに限定されています。詳細と脆弱性の報告方法については、SECURITY.md を参照してください。

貢献

Issue やプルリクエストを歓迎します。CONTRIBUTING.md では、セットアップ方法、テストの実行方法、優れたプルリクエストの条件について説明しています。このプロジェクトはコントリビューター行動規範に従っています。

ライセンス

MIT。同梱の JetBrains Mono フォントは、SIL Open Font License のライセンスで提供されています。