gPTY

gPTY - Rust と Godot を基盤とするデスクトップワークスペースです。ターミナル、コードビューアー、ファイルツリー、Wiki、メディアなどのペインをタイル状に配置できるグリッド、コンセプトキャプチャエンジン、そして JSON-RPC/MCP 制御インターフェースを備えています。これにより、AI エージェントや自動化ツールはペインを起動したり、テキストを入力したり、TUI をスクレイピングすることなくターミナルの出力を確認したりできます。すべてのペインは、単一の公開 API を通じてシェル、スクリプト、エージェントから操作できます。

概要

機能

ペイン

• タイル状グリッド - 独立したシェルセッションを分割、サイズ変更、並べ替えできます。名前付きレイアウト、ワークスペース（タブのセット）、プロファイルを保存して再読み込みできます。
• エミュレーション - alacritty_terminal グリッドに対応し、16／256／true color、正規表現検索付きのスクロールバック、折り返しテキストの選択を利用できます。
• メモリ - 再起動後もスクロールバック、設定、ワークスペースが復元され、各ペインの履歴を全文検索できます。
• ファイルツリー - Godot ネイティブの OS ファイルツリーブラウザーです。
• コードビューアー - テキストと Markdown を表示します。
• Wiki - 全文検索、ライブプレビューエディター、[[wikilinks]]、バックリンク、リンクグラフを備えたプレーンな Markdown ノートの保管庫です。最後に閲覧していた場所から再開できます。付属の ナレッジベース プロファイルでは、リリースに同梱された Wiki が開きます。ペインの紹介を見る。
• メディア - 固定バージョンの最小構成 FFmpeg バックエンド（v0.7）を使って、ペイン内でローカルの音声と動画を再生できます。
• cli_view - 任意のコマンドの出力をペインにストリーミングできるため、プラグインは Godot SDK を使わずに UI を追加できます。

エージェントと自動化

• 1 つの API、3 つの接続方法 - 同じ操作を JSON-RPC ソケット、gpty CLI、MCP サーバーから利用できます。ペインの起動、入力の送信、出力の読み取り、コマンドの実行とパターンの待機、タグ付きペインへのブロードキャストが可能です。このサーバーは、公式 MCP レジストリに io.github.godot-pty/gpty として登録されています。
• エージェント状態バッジ - エージェントは自身のペインから working または needs attention を宣言でき、タブに表示されます。表示専用です。
• 可観測性ペイン - Reasoning は、文書化されたエージェントのライフサイクルイベントを受動的に表示します（現在は OMP、アダプターに依存しない用語を使用）。Inspector は非公開でツールを使わない Q&A セッションです。gPTY がエージェントの状態をオーケストレーションすることはありません。
• コンセプト - ターミナル出力に対する正規表現トリガーで返信を取得し、隣接するペインに送れます。設定で手動、またはビジュアルグラフエディターを使って独自のコンセプトを作成できます。コンセプトは表示専用で、シェルに入力することはありません。

拡張可能、ただし制限あり

• プラグイン - マニフェストベースで、インストール前に GUI でレビューできるほか、公開レジストリもあります。
• 文書化された脅威モデル - SECURITY.md を参照してください。リリースには SHA256SUMS とビルド来歴の証明書が同梱され、制御ソケットは所有者のみが利用できます。

ステータス

gPTY は現在も活発に開発されているサイドプロジェクトです。このコードベースの大部分、Godot の UI レイアウトの大半や Rust（gpty-core）の GDExtension ブリッジを含め、人間によるレビューのもとで LLM を使用して生成されました。そのため、基盤となるコードには慣用的でないパターンやバグが含まれている可能性があります。ロードマップとドキュメント：https://gpty.dev/

コンポーネント	選択	理由
PTY ライブラリ	portable-pty	Linux の /dev/ptmx と Windows の ConPTY に対応し、単一の API でクロスプラットフォームを実現
ANSI 解析	vte クレート	高速な Rust 製 ANSI ステートマシン
非同期ランタイム	tokio	ターミナルごとのタスクと、チャネル駆動型のキャプチャ状態マシン
I/O スレッド処理	PTY ごとの専用 std::thread	予測可能なブロッキング読み取りを実現し、mpsc 経由で tokio にブリッジ
コンセプトキャプチャ	解析済み LineParser 出力に対する Rust の regex	線形時間でのマッチング（ReDoS 対策済み）。グリッドに忠実な再生のため、キャプチャは生バイトをバッファリング
グリッド描画	alacritty_terminal	完全な DEC STD 070 グリッド状態マシン。配列を Godot の _draw() に渡します
Godot ブリッジ	gdext 0.5	Godot 4.7 以降向けのネイティブ GDExtension
Rust エディション	2024	Rust >= 1.85 が必要です

---

インストールと使用方法

Godot のインストールが不要なスタンドアロンバイナリは、Linux、macOS、Windows 向けに GitHub Releases で公開されています。

プラットフォーム	パッケージ
Linux	gpty-v<version>-linux-x86_64.tar.gz - 展開します。./gpty-gui.sh で GUI が起動し、./gpty は CLI です
macOS	gpty-v<version>-macos.zip - 解凍し、.app を右クリックして「開く」を選択します。その隣にある gpty が CLI です
Windows	gpty-v<version>-windows-x86_64.zip - 展開します。gpty-gui.exe で GUI が起動し、gpty.exe は CLI です

各リリースには gPTY のナレッジベースもバンドルされています。サイドバーの Knowledge Base プロファイルを開くと、ユーザーデータにバンドルされた Wiki が開きます。

ファイル名の <version> は、ダウンロードしたリリースタグです（例：v0.7.0）。

各リリースには、すべてのアセットを一覧にした SHA256SUMS が含まれます。実行前に、ダウンロードしたファイルを確認してください。

sha256sum -c SHA256SUMS            # Linux
shasum -a 256 -c SHA256SUMS        # macOS
certutil -hashfile <asset> SHA256  # Windows

チェックサムにより、転送中にダウンロードが破損または改ざんされていないか確認できます。各アセットには、ビルドしたワークフロー実行に紐付けるビルド来歴の証明書も付属します。

gh attestation verify <asset> --repo godot-pty/gpty

バイナリにはコード署名がありません（SECURITY.md を参照）。

CLI

gpty バイナリは、実行中の GUI を JSON-RPC IPC 経由で制御します。各リリースのバンドルには GUI と並べて同梱されています。また crates.io でも入手でき、cargo install gpty を実行すると同じバイナリが PATH にインストールされます（バンドルされた SQLite のため、Rust ツールチェーンと C コンパイラーが必要です）。MCP クライアントが gpty mcp を起動する際には、このバイナリが使われます。CLI は、新しいワークスペースだけで実行できるコマンド（new-pane と layout load）に限り、必要に応じて起動します。一方、gpty daemon start は明示的に起動し、--no-daemon は起動しません。その他のコマンドは、すでに存在するワークスペースを必要とするため、利用できないウィンドウを開くのではなく、no gpty GUI is running (start one with \gpty daemon start`) というエラーになります。ソースからのビルド（cargo build -p gptyまたはcargo build --workspace）が必要なのは、CLI 自体を開発する場合だけです。その方法でインストールした場合は、**バージョンを上げた後に再インストールしてください**（cargo install --path crates/gpty-cli --force）。PATH上で前方にある古いgpty` がリリース版の CLI より優先されると、原因が分かりにくい形で失敗します（存在しないサブコマンドは、IPC が始まる前に clap で終了します）。そのため、CLI は実行中の GUI のバージョンまたは IPC プロトコルが自身と異なることを検出すると、標準エラー出力に一度だけ警告を表示します。警告には双方の情報が記載されますが、解決するには再インストールが必要です。

GUI を Godot またはリリースバイナリから起動すると、CLI は Unix ソケット（Linux では $XDG_RUNTIME_DIR/gpty.sock、または GPTY_SOCKET 環境変数）経由で接続します。

# Check if the GUI is running (exit 1 when it is not)
gpty daemon status

# Print the bundled agent skill (for coding agents running inside a pane)
gpty --skill

# Declare this pane's agent state, from inside the pane (display only)
gpty state working

# Spawn a new terminal pane
gpty new-pane --pane-type terminal

# List all active panes
gpty list-panes

# Send text to a pane (by label, e.g. T1)
gpty inject T1 --text "echo hello"

# Read a pane's screen and scrollback; run a command in a new pane and wait for its output
gpty pane-read T1 --lines 200
gpty pane-run --command "cargo test"
gpty pane-wait T1 --pattern "tests passed" --timeout-ms 30000

# Search and read a wiki vault
gpty vault search <vault> <pattern>
gpty vault read <vault> <path>

# Close a pane
gpty kill-pane T1

# Save and load named layouts
gpty layout save my-setup
gpty layout load my-setup
gpty layout list

# Install a plugin (reviewed in the GUI - its actions run as you)
gpty plugin install godot-pty/gpty-omp
gpty plugin list

# Manage the GUI daemon
gpty daemon start
gpty daemon status
gpty daemon stop

# Generate AI tool manifests (no GUI needed)
gpty schema
gpty schema --format mcp

# Run as MCP server over stdio (no GUI needed)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | gpty mcp

すべてのサブコマンドとフラグについては、gpty --help を参照してください。

MCP 統合

gpty には MCP（Model Context Protocol）サーバーが付属しており、AI エージェントやコーディングハーネスからワークスペースを操作できます。リポジトリのルートにある mcp.json で定義されているため、自動検出されます。

{"mcpServers": {"gpty": {"command": "gpty", "args": ["mcp"]}}}

• 直接実行：gpty mcp を stdio 経由で実行すると、CLI の各サブコマンド（new-pane、list-panes、kill-pane、focus-pane、inject、pane-read、pane-status、pane-run、pane-wait、broadcast、vault-search、vault-read、vault-weight、layout-*、daemon-*、concept-*、version）ごとにツールを公開します。
• マニフェスト：gpty schema --format mcp を実行すると、エージェントの設定に引き継ぐための MCP ツールマニフェスト（JSON Schema）が出力されます（GUI が起動していなくても動作します）。

ツールのスキーマは CLI と同じ clap 定義（crates/gpty-cli/src/commands/schema.rs）から生成されるため、gpty --help と食い違うことはありません。

---

ロードマップ

リリース済み、進行中、計画中の項目については、リリースチェーンごとにまとめられたロードマップをご覧ください。

---

セキュリティ

脅威モデル、報告手順、gpty が防御の対象としない事項については、SECURITY.mdをご覧ください。実装ルール（Concept Engine の ReDoS に対する方針、PTY 環境のサニタイズ、IPC の強化、OSC 52 の制限）は、セキュリティルールに記載されています。

---

コントリビューション

セットアップ手順、ビルドコマンド、テスト、コードスタイル、プルリクエストの手順については、CONTRIBUTING.mdをご覧ください。

---

変更履歴

バージョンごとの変更と履歴の全容については、CHANGELOG.mdをご覧ください。

---

ライセンス

gPTY は、GNU General Public License version 3 以降でライセンスされたフリーソフトウェアです。全文はLICENSEをご覧ください。

LICENSE-EXCEPTIONS.mdでは、このライセンスの第 7 条に基づく 2 つの許可を追加しており、エコシステム側の自由度を維持しています。

• プラグイン、拡張機能、アダプターに GPLv3 は適用されません。 CLI、JSON-RPC、MCP、イベントの各インターフェースを介して gPTY と連携するもの（ネイティブのペインタイプを含む）は、Apache-2.0、MIT、その他任意の条件でライセンスでき、義務なく gPTY と併せて配布できます。
• 設定ファイルとデータファイルにはコピーレフトは適用されません。 プロファイル、ワークスペース、レイアウト、コンセプト、設定は、自由にライセンスできます。gPTY に同梱されるデフォルトの *.json ファイルは Apache-2.0 でライセンスされています。

Copyright (C) 2026 Neil Pathare.

gPTY は有用であることを願って配布されていますが、いかなる保証もなく、エンドユーザーによるあらゆる使用について責任を負いません。商品性または特定目的への適合性に関する黙示的な保証もありません。詳しくは GNU General Public License をご覧ください。