Unterm

Unterm

AIエージェントが操作できるターミナルです。

Untermが役に立ったら、GitHubで⭐を付けていただくと、ほかの人にも見つけてもらいやすくなります。

Unterm独自のネイティブなnext-coreターミナルエンジンを基盤にした、クロスプラットフォーム対応のターミナル（macOS / Linux / Windows）です。設計の要となるのは、MCPを介してあらゆるAIエージェントがターミナル自体を外部から操作できることです。Claude Code、Codex、Gemini CLI、Cursor、Aider、独自スクリプトなど、すべて同じJSON-RPCインターフェース（認証済みメソッド152個とauth.login）を使って、シェルの起動、コマンドの実行、ペインの状態の読み取り、スクリーンショットの撮影、セッションの記録、エージェントコックピットの実行ができます。（テーマ、言語、unterm.confはMCPの対象外です。Web Settings、unterm-cli、またはファイルから設定します。）

v0.68以降、ターミナルはオーケストレーターが単に呼び出すだけでなく、管理できるものになりました。ターミナルが対応できることと各機能の危険度を公開し、有効期限が切れ、再利用できないリースのもとで動作します。互いの内容が見えないワークスペースにエージェントを隔離でき、タスクの証拠バンドルを渡すことで、その場にいなかった人でも検証できます。

v0.55以降、関係は双方向になりました。エージェントは外部からターミナルを操作し、ターミナルは内部で実行中のエージェントのエージェントコックピットになります。ペインごとのエージェント状態をリアルタイムで表示し、対応待ちを優先する受信トレイを備え、N個のエージェントをそれぞれ独立したgitワークツリーで同じタスクに取り組ませることができます。また、成果物の差分確認、マージ、ロールバックができるレビュー画面もあります。

2026年のほかのターミナルは、それぞれ異なる方向を選んでいます。Warpは閉じたクラウド（Oz）にAIを組み込み、Ghosttyは邪魔をせず、好きなツールを持ち込めるようにし、iTerm2はMac専用です。Untermは3つ目の方向を選びます。ターミナルをMCPで操作できるインターフェースとし、AIによる生成機能をターミナルに意図的に持ち込まず、外部エージェントがAPIを通じて操作できるようにし、すべてのエージェントを人間が一元管理できるコックピットを提供します。

実用上の特徴：

• Untermの各ウィンドウは、ローカルのMCPサーバー（TCP経由の行区切りJSON-RPC）とローカルのHTTP設定サーバー（Web Settingsページ）を自動割り当てポートで起動します。どちらも認証トークンで保護され、127.0.0.1からのみアクセスでき、クラウドとの通信はありません。
• **設定はターミナルではなくブラウザーで行います。**セルグリッド形式のTUIでは、最新のフォーム操作を実現できません（適切なテキスト入力欄、ライブプレビュー、カラーピッカーがありません）。ターミナル内の▼メニューにはクイックアクションとWeb Settingsページへのリンクがあり、設定自体はブラウザーで行います。
• 初期状態で9言語に対応：en / 简体中文 / 繁體中文 / 日本語 / 한국어 / Deutsch / Français / Italiano / हिन्दी。システムのロケールを自動検出します。Web Settingsまたはunterm-cli lang set <code>で変更できます。
• 複数インスタンスの検出：実行中のUntermプロセスにはそれぞれNATOフォネティックコード名のインスタンス（alpha、bravo、charlie…）が割り当てられ、ポートと認証トークンが~/.unterm/instances/<name>.jsonに書き込まれます。複数のウィンドウを同時に操作するエージェントは、このディレクトリを列挙します。
• クロスプラットフォームでの一貫性は正確性の要件です：Windowsで動作する機能がmacOSやLinuxで動作しない場合、それは「まだサポートされていない」のではなく、バグです。
• 装飾よりも引き算を重視：ターミナル内にAIチャットオーバーレイはなく、基本機能にクラウドは不要です。プロキシ設定はデフォルトでシステム設定を自動検出し、HTTP/SOCKSの明示的な上書き、ノードプール、ローテーション、Clash/mihomoコントローラーにも対応します。macOSでのFinder連携には、ネイティブのFinder右クリック拡張機能とサービスを使用します。

GUIとターミナルランタイムは、現在Unterm独自のネイティブなnext-coreエンジンを使用しています。リポジトリには、依存関係として残っている一部の上流コンポーネントとその帰属表示が引き続き含まれていますが、WezTermのマルチプレクサー／ウィンドウ状態は、もはや製品のカーネルではありません。

エージェントコックピット

任意のペインで Claude Code、Codex、Gemini CLI、または Aider を実行すれば、Unterm が検出します。設定もラッパーも不要です。すべてローカルで動作する5つの柱です。

• エージェント状態エンジン — 各ペインのエージェントとその状態（作業中／応答待ち／アイドル／完了）を、OSC の進捗情報とタイトルのシグナル、プロセスのフィンガープリント、任意の公式フックから読み取ります。タブのバッジと、トップバーにウィンドウをまたいで集計するチップが表示されます。
• 受信トレイ（Ctrl+Shift+A） — 応答を待っているすべてのエージェントを、待ち時間が長い順に1つのキューにまとめます。Enter キーで該当するペインに移動でき、もう1回キーを押せばプロンプトに応答できます。
• フリート — 1つのタスク × N 個のエージェント × N 個の分離された Git ワークツリー（../<repo>.fleet/）で、それぞれに1つのタブを割り当てます。同じエージェントを3つ起動して処理量を増やすことも、claude,codex,gemini を起動して比較評価することもできます。
• レビュー — エージェントがリポジトリに触れる前に、チェックポイントを作成します（ぶら下がったコミットのスナップショット。HEAD やインデックスには一切触れません）。Web レビューページにはメンバーごとの差分が表示され、スカッシュマージ（ステージ済みの状態で停止するため、コミットはあなた自身が行います）、破棄、ロールバックができます。v0.57 以降、レビューでは各メンバーを検証（推定または明示的に指定された検証コマンド）し、検証結果と変更規模に基づいてメンバーを順位付けし、検証に成功するまでマージを保留し、失敗したメンバーを既存のワークツリーで再試行できます。
• すべてスクリプト化可能 — コックピット自体が MCP ＋ CLI です。agent.status、cockpit.inbox、fleet.launch、review.merge などを利用できます。オーケストレーションエージェントは、人が介在しなくてもフリートを実行し、差分をレビューできます。

unterm-cli agent status                                  # who's running where, in what state
unterm-cli agent inbox                                   # who's waiting for you
unterm-cli agent enable-hooks                            # exact state via official hooks (merge-only, backed up)
unterm-cli fleet launch --agents claude,codex "fix the flaky auth test"
unterm-cli review verify --fleet <id> --member 1         # run the member's validation
unterm-cli review list && unterm-cli review open         # ranked diffs in the browser

詳細なドキュメント：unterm.app/docs/agent-cockpit。

---

インストール

ビルド済みのアーティファクトは GitHub Releases で公開されています。

https://github.com/zhitongblog/unterm/releases

プラットフォーム	アーティファクト
macOS	Unterm-macos-<version>.dmg（ユニバーサル arm64+x86_64、署名済み＋公証済み）
Linux	unterm-<version>.deb または Unterm-<version>-x86_64.AppImage
Windows	Unterm-<version>-x64.msi または Unterm-windows-x64-<version>.zip

macOS

Unterm-macos-<version>.dmg をダブルクリックし、Unterm.app を Applications のショートカットにドラッグします。DMG は Developer ID で署名され、Apple による公証も受けているため、初回起動時に Gatekeeper の警告なしで開きます。

Finder との連携機能は DMG に同梱されています。初回起動後、Finder の 右クリックメニューにフォルダやファイルの Open in Unterm が表示されます。macOS が拡張機能をすぐに更新しない場合は、DMG から Repair Finder Integration.app を一度実行してください。

Linux（Debian／Ubuntu）

sudo apt install ./unterm-<version>.deb
unterm

その他のディストリビューションでは、AppImage を使用してください。

chmod +x Unterm-<version>-x86_64.AppImage
./Unterm-<version>-x86_64.AppImage

Windows

MSI インストーラーを実行すると、unterm.exe が Program Files\Unterm に配置され、スタートメニューにショートカットが作成されます。

---

新機能

• v0.68 — ターミナルを別の何かが統制できます。 Unterm は、CLI エージェントをシェルから起動して終了コードを待つのではなく、セッションとしてホストするようになりました （agent_session.*：発言内容、実行を求めたコマンド、終了時の状態を記録し、 独自のタスク ID はそのまま引き継ぎます）。Unzoo からブラウザーを リースでき、逆に Unzoo からリースされることもできます。terminal.manifest は、このターミナルでできることと 各カテゴリの危険度を公開します。これはゲートウェイが拒否判定に使うものと同じ一覧に基づいています。承認への回答にも 対応しました。設定画面では、エージェントが何の承認を待っているかを確認し、「今回のみ許可／この タスクの間は許可／常に許可」から選べます。ワークスペースは互いに見えないルートとして扱われ、 cd で外に出たシェルはワークスペース内ではなくなります。監査ログはハッシュチェーンで 保護され、編集すると次の行との整合性が崩れます。unterm-cli provider | scope | artifact | evidence | system — MCP メソッドを46個追加（当時は合計149個、現在は152個）。
• v0.57 — フリート検証ループと新しいブランドマーク。 Review で、フリートの各メンバーを自動で検証できるようになりました（Cargo／Go／npm／pnpm／yarn／Python／Maven／Gradle／.NET を推定するか、独自のコマンドを指定できます）。検証結果と変更規模に基づいてメンバーを順位付けし、検証成功をスクワッシュマージの条件にできます（監査対象の force による上書きも可能です）。失敗したメンバーは作業を失うことなく、既存のワークツリー内で再試行できます — MCP と CLI から review.verify ／ fleet.retry を利用できます。サイドバーには、リポジトリごとにまとめたナビゲーションと、常時使えるあいまい検索が追加されました。ロゴを表示するすべての箇所で、新しいコマンドループのマークを採用しました。
• v0.55 — Agent Cockpit。 ターミナルが内部のエージェントを認識できるようになりました。タブバッジとウィンドウ横断の集計に対応したペインごとのリアルタイム状態表示、承認待ちを優先表示する Agent Inbox（Ctrl+Shift+A）、N 個の分離されたワークツリーで N 個のエージェントが同じタスクを実行するフリート、チェックポイント、差分、ロールバック、スクワッシュマージに対応した Review ページを備えています。MCP メソッドを12個、CLI ファミリーを3個追加しました。
• v0.54 — コールドスタートを2.8倍高速化（約780ms → 約280ms）。起動経路の5つの改善によるもので、Windows の大量出力時に CPU コアを消費する問題も解消しました（約91% → 約4%）。大量出力中も MCP の応答性を維持します。
• v0.53 — Composer と Git パネル。 プロンプトキュー（Ctrl+Shift+J）から、確認プロンプトを賢く自動で進めながら、まとめたプロンプトをエージェントペインに実行できます。また、読み取り専用の Git ステータスパネル（Ctrl+Shift+G）を追加しました。
• v0.52 — 最初から使えるエージェントを拡充。 Kimi Code CLI と Trae Agent が組み込みマニフェストに加わりました（エージェント CLI は合計7種類）。フレームごとの描画経路を見直し、Windows のクリップボードとウィンドウサイズの安定性も向上しました。

---

ドキュメント

Unterm のドキュメント全文は https://unterm.app/docs/ にあります。

• エージェントコックピット — エージェントの状態エンジン、受信トレイ、フリート、レビュー：1 つのターミナルから CLI エージェントを実行、監督できます
• エージェント連携 — Claude Code ／ Cursor ／ Aider ／独自のクライアントから Unterm を操作する方法
• エージェントのレシピ — エージェントでターミナルを操作する一般的なワークフローに使える、コピー＆ペースト用のパターン
• 製品ロードマップ — 現在開発中の機能と今後の開発予定
• 製品要件 — 製品の完全なスコープ、機能要件、MCP ／ CLI の対応範囲、受け入れ基準
• 詳細な製品計画 — ユーザーシナリオ、バージョンロードマップ、優先順位、検証、next-core への移行を網羅した中国語の実行計画
• Next-core の製品計画 — Unterm 独自のターミナルコアを構築しながら、現行エンジンを安定化するための段階的な計画
• Next-core の技術アーキテクチャ — より大規模なターミナルのモノリスへと拡大することなく、WezTerm のコアを置き換えるための中国語のアーキテクチャ計画
• MCP リファレンス — すべての JSON-RPC メソッド、パラメーター、戻り値の形式
• マルチインスタンス — NATO 名、インスタンスディレクトリ、適切なウィンドウの選択
• ID プロファイル — ID ごとに 1 つのウィンドウを使用します。GitHub ／ AWS ／ npm ／ OpenAI のトークン、Git の ID、SSH キーのルーティングを一度に割り当てます。CLI ＋ MCP。
• CLI リファレンス — unterm-cli のサブコマンド、フラグ、終了コード
• 設定 — ~/.unterm/ 配下のすべてのファイル
• 設定ファイルのリファレンス — [env] や [keys] を含む、unterm.conf のすべてのキー
• アーキテクチャ — WezTerm からフォークした部分とその理由

この README は概要版です。詳細版はサイトをご覧ください。

---

機能

• 3 つのプラットフォームすべてで GPU アクセラレーションによるレンダリングを wgpu 経由で実現します。macOS では Metal、Windows では Direct3D 12、Linux では Vulkan を使用します。ハードウェア経由での起動に失敗すると、Unterm は OpenGL を試し、次に同じ 2 つをソフトウェアで試します（Windows では WARP）。Windows では最後に Vulkan を試すため、使用可能なグラフィックスドライバーがないマシンでもウィンドウを開けます。UNTERM_GPU_BACKEND=dx12|vulkan|gl|metal でバックエンドを固定できます。
• ターミナル内の画像表示 — kitty グラフィックスプロトコル、iTerm2 インライン画像（OSC 1337 File=）、sixel に対応しているため、chafa、img2sixel、viu、timg、unterm-cli imgcat で画像そのものを表示できます。画像はテキストとともにスクロールしてスクロールバックに残り、ペインの端でクリップされ、描画された画面（メインまたは代替）内に収まります。screen.images / unterm-cli session images で、エージェント向けに画像を一覧表示できます。
• MCP サーバー（127.0.0.1:<auto-port>、デフォルトは 19876） — TCP 経由の行区切り JSON-RPC で、ループバック接続のみを許可し、認証トークンを必須とします。認証済みメソッド 152 個と auth.login を公開します。meta.surface（または unterm-cli reference）を呼び出すと、現在の正式な一覧を 1 回で取得できます。
• エージェントコックピット — ペインごとのエージェント状態、待機中を優先する受信トレイ、ワークツリーフリート、チェックポイントとレビューに対応します。上のセクションをご覧ください。
• ガバナンスされたエージェント作業 — すべての経路（MCP、CLI、 brain、ワークフロー、未加工の PTY 書き込み）が通過する単一のゲートウェイ、有効期限とリプレイ保護を備えた機能リース、互いを参照できないワークスペース、ハッシュチェーン形式の監査証跡、第三者が検証できる証拠バンドルを提供します。エージェントが正面玄関を迂回してブラウザーを操作することはできません。管理対象セッション内では、生の CDP、Playwright、Puppeteer、Selenium は拒否され、拒否メッセージにサポートされている経路が示されます。
• Web 設定 UI（127.0.0.1:<auto-port>、デフォルトは 19877） — unterm-cli settings open または ▼ メニューの Settings (Web) 項目から、任意のブラウザーで開けます。Tailwind スタイルの SPA で、9 言語に対応し、キーボードとマウスで操作できます。
• プロキシ管理 — macOS のシステム設定、Windows レジストリ、GNOME の gsettings、プロキシ環境変数を読み取り、一般的なローカルポートも確認します。~/.unterm/proxy.json には、手動で設定した HTTP/SOCKS URL、no_proxy、名前付きノード、ローテーション、Clash/mihomo コントローラーの設定も保存されます。
• 範囲を指定したスクリーンショット — ステータスバーから撮影できます（左クリックでは Unterm ウィンドウを除外し、右クリックでは含めます）。PNG は ~/.unterm/screenshots/ のディスク、システムの画像クリップボードに保存され、パスはテキストクリップボードにコピーされます。MCP 経由では、macOS と Windows で capture.screen、capture.window、capture.select（矩形範囲）が動作します。Linux では現在「このプラットフォームではまだ実装されていません」を返します。capture.scrollback と capture.clipboard はすべてのプラットフォームで動作します。
• スクロールする長いスクリーンショット（上下両方向）: capture.scrollback はペインの全履歴をヘッドレスで 1 枚の縦長 PNG に再描画します（正確なフォントとテーマを使用し、ストリーミングエンコードに対応し、ウィンドウが遮られていても動作します）。capture.window_scroll はスクロールイベントを合成し、固定ヘッダー／フッターを検出しながら行ハッシュ照合でフレームをつなぎ合わせ、別のアプリのウィンドウの長いスクリーンショットを撮影します（macOS）。どちらも ▼ メニューと unterm-cli screenshot --scrollback / --scroll-app から利用できます。
• セッションの記録 → Markdown — OSC 133 のブロック分割と組み込みの秘匿化機能に対応します（GitHub トークン、KEY=value、40 文字以上の 16 進数／Base64 パターンをマスクします）。記録はプロジェクトディレクトリの <cwd>/.unterm/sessions/<date>/<tab>-<time>.md に保存されます。書き込み可能なプロジェクトコンテキストがない場合は、~/.unterm/sessions/_orphan/ に保存されます。
• ターミナル内で右クリックすると貼り付け — 選択範囲の有無にかかわらず、また vim や Claude Code などマウス対応プログラムを含むすべてのペインで、右クリックするたびに貼り付けます（クリックはプログラムに渡されません）。コピーするには選択します。ボタンを離すと、選択範囲がクリップボードにコピーされます。macOS では通常の Ctrl+クリックも右クリックとして扱われ、中クリックでも貼り付けられます。タブストリップで右クリックすると、代わりにタブのコンテキストメニュー（新しいタブ、分割、名前変更、移動、閉じる）が開きます。ウィンドウ装飾上の右クリックが貼り付けとして処理されることはありません。
• クイックメニュー — タブバーの ▼ ボタンから、キー割り当てテーブルにある現在のキー操作とともに利用できます。
  • 新しいタブ／右に分割
  • ディレクトリへ移動（現在のペインで cd するか、新しいタブで開く）／ファイルツリー
  • Git パネル／左側のタブストリップを切り替え
  • 検索／コマンドパレット
  • セッション記録を切り替え／現在のセッションをエクスポート／スクロールバックの長いスクリーンショット
  • 設定（Web）、バージョン／ウェブサイトの行
• 独立したタイトルバーに代わる統一トップバー。デスクトップに合わせたボタンを備えます。macOS では信号機、Windows では Fluent キャプションボタン（Windows 11 のスナップレイアウト対応）、Linux では GNOME スタイルの丸いボタンを表示します。

---

ID プロファイル

GitHub PAT、AWS キー、npm トークン、git の作成者情報、SSH キーをまとめて設定し、ウィンドウに一貫した開発者 ID を割り当てます。別の ID を使う場合は、新しいウィンドウを開きます。タブバーのチップで、現在どの ID を使用しているか確認できます。シークレットは OS 標準のボールト（Keychain／Credential Manager／Secret Service）に保存され、~/.unterm/ には保存されません。

unterm-cli profile create "Work — Acme"
unterm-cli profile set-secret "Work" GITHUB_TOKEN
unterm-cli profile spawn "Work"           # → new window bound to Work
unterm-cli profile set-default "Work"     # plain `unterm` now binds to Work
unterm-cli profile import                 # scans gh/aws/npm/ssh/docker/gcloud/netrc
                                          #   for existing credentials, read-only

プロファイルに紐付けられたシェル内では：

$ env | grep UNTERM_PROFILE
UNTERM_PROFILE=work-acme
# GITHUB_TOKEN, GIT_AUTHOR_NAME, AWS_*, etc. all set from the profile

詳しくは、unterm.app/docs/profilesをご覧ください。

マルチインスタンス

実行中の Unterm プロセスはそれぞれ、NATO フォネティックコードに基づく名前（alpha、bravo、charlie、… zulu）を持つインスタンスです。最初のウィンドウには alpha、2 番目には bravo が割り当てられます。26 個すべてが同時に使われている場合、次は alpha2 になります。名前は発音しやすく、AI エージェントも正しく扱えます。UUID も、頭の中でポート番号を覚える必要もありません。

各 GUI インスタンスは、メタデータ（mcp_port、http_port、auth_token、pid、started_at、version、platform）を ~/.unterm/instances/<name>.json に書き込みます。特定のインスタンスを操作する必要があるエージェントは、このディレクトリを列挙し、ID、cwd、またはタイトルで対象を選択します。

ヘッドレスの Core は、~/.unterm ではなくプラットフォームのデータディレクトリ（Windows では %LOCALAPPDATA%\Unterm、Linux では ~/.local/share/Unterm、macOS では ~/Library/Application Support/Unterm）に core.json を書き込みます。（UNTERM_STATE_DIR を設定すると両方の保存先が上書きされます。両者が混同されたのはこのためです。この変数を設定したテストでは、すべて同じ場所を参照していました。）unterm-cli mcp-stdio と MCP を利用する CLI コマンドは、この Core の記録を優先するため、GUI を再起動してもターミナルセッションを引き続き利用できます。また、ウィンドウが開いていないときは instance.list に core というインスタンスとして表示され、unterm-cli --instance core でアクセスできます。

インスタンスはウィンドウではなくフロントエンドです。v0.68 以降は、1 つのプロセスで複数のウィンドウを保持でき、それぞれに独自の ID が割り当てられます。instance.windows でウィンドウを一覧表示し、instance.new_window で新しいウィンドウを開いてその ID を取得し、instance.focus でウィンドウにフォーカスできます。

従来の単一ターゲット型エージェント向けに、~/.unterm/active.json は現在稼働中の GUI インスタンスを示します。また、後方互換性のため、~/.unterm/server.json に同じ記録が複製されます。

MCP の instance.* 名前空間から、これらを直接操作できます：instance.list、instance.info、instance.set_title、instance.focus。使用例と検出プロトコルについては、マルチインスタンスのドキュメントをご覧ください。

---

CLI

unterm-cli バイナリは、ローカル MCP サーバーに透過的にルーティングし、Unterm の製品機能全体を公開します。新しい連携では、unterm-cli mcp-stdio または unterm-cli を直接使用してください。これらは core.json、稼働中の GUI インスタンスの記録、従来のファイルを適切な順序で解決します。CLI を介さないスクリプトでは、Core の MCP エンドポイント用に Core のプラットフォームデータディレクトリ（%LOCALAPPDATA%\Unterm、~/.local/share/Unterm、~/Library/Application Support/Unterm）にある core.json、特定の GUI インスタンス用に ~/.unterm/instances/<name>.json、または従来のアクティブ GUI ポインター用に ~/.unterm/server.json を読み取れます。この 2 つのディレクトリは異なります。~/.unterm の外に保存されるのは Core の記録だけです。

# Settings + Web UI
unterm-cli settings open                       # open the Web Settings page
unterm-cli theme list / set <id>               # agent-inbox / standard / midnight / daylight / classic / notion-dark / notion-light
unterm-cli lang list / set <code> / current    # en-US / zh-CN / zh-TW / ja-JP / ko-KR / de-DE / fr-FR / it-IT / hi-IN

# Proxy
unterm-cli proxy status                        # auto-detect health
unterm-cli proxy nodes / switch <name> / disable / env / rotation

# Agent Cockpit
unterm-cli agent status                        # per-pane agent state (working/waiting/idle/done)
unterm-cli agent inbox                         # agents waiting for you, longest first
unterm-cli agent enable-hooks [--dry-run]      # wire Claude Code / Codex / Aider lifecycle hooks
unterm-cli fleet launch --agents claude,codex "task"   # N agents × N worktrees, one tab each
unterm-cli fleet list / clean
unterm-cli review list / diff / merge / discard / rollback
unterm-cli review open                         # Review page in the browser

# Capability providers — the browser and anything else outside this process
unterm-cli provider list                       # what can be reached, and what conflicts
unterm-cli provider bind unzoo                 # contact it; the first bind pins who answered
unterm-cli provider diagnose unzoo             # handshake, lease, evidence, idempotency, replay
unterm-cli provider acquire browser --ttl 300  # ask for a lease; answers `waiting` when it is not there
unterm-cli provider call <lease> tab_list --seq 1 --capability browser
unterm-cli provider chain <lease>              # lease → grant → approval → the calls made under it
unterm-cli provider approvals                  # what is waiting on you (answer these in Settings)
unterm-cli provider pause / resume / unbind / revoke <lease>

# Workspaces — named roots that cannot see each other
unterm-cli scope create alpha ~/code/alpha
unterm-cli scope check <workspace> <path> [--access write]
unterm-cli scope list / archive <workspace>

# What tasks produced, and proving it to somebody who was not there
unterm-cli artifact list [--task <id>] / usage / verify <id> / forget <id>
unterm-cli evidence export <task> ./bundle     # the whole story as plain files + hashes
unterm-cli evidence verify ./bundle            # recomputes; does not take your word for it
unterm-cli evidence audit                      # walk the audit hash-chain, report the first break

# The processes, and the data behind them
unterm-cli system status                       # core / gui / mcp, and "can work without a window"
unterm-cli system diagnostics [--out FILE]     # redacted: versions and health, no tokens or paths
unterm-cli system snapshot / snapshots / restore <id>
unterm-cli system upgrade --live X --staged Y --to 0.69.0   # rolls back if the new one does not answer
unterm-cli system installs                     # every copy on this machine, and which ones fight
unterm-cli system uninstall-plan [--remove-data]            # describes; never removes

# Sessions / panes
unterm-cli session list                        # list panes in active/latest instance
unterm-cli instance list                       # discover alpha/bravo/... windows
unterm-cli --instance bravo session list       # pin a command to one window
unterm-cli session create [--cwd DIR] [-- CMD] # spawn a new tab
unterm-cli --json session create -- pwsh.exe -NoLogo -NoProfile -Command "Write-Output ok"
unterm-cli session record start [--id N]
unterm-cli session record stop [--id N]
unterm-cli session export [--id N] [-o FILE]
unterm-cli sessions list [--project SLUG]
unterm-cli sessions read <session-id>

# Screenshots
unterm-cli screenshot [--include-window] [-o FILE]
# Long screenshot of a pane's ENTIRE scrollback (headless re-render -> tall PNG)
unterm-cli screenshot --scrollback [--pane N] [--max-rows N] [-o FILE]
# Long screenshot of ANOTHER app's window: scroll + stitch (macOS)
unterm-cli screenshot --scroll-app Safari [--scroll-title SUBSTR] [--max-frames N] [-o FILE]

スクリプトに適した未加工の JSON-RPC 出力を得るには、任意のサブコマンドに --json を渡します。unterm-cli が解析するよう、-- CMD より前に指定してください。後ろに置くと、子コマンドによって解析されます。session create は複数のトークンからなるコマンドを argv として保持しますが、単一のコマンド文字列は引き続きプラットフォームのシェルで実行されます。1 回の呼び出しでロケールを上書きするには、--lang <code> を渡します。複数の Unterm ウィンドウが開いていて、対象を確実に指定する必要がある場合は、--instance <id> を渡すか、UNTERM_INSTANCE=<id> を設定します。

マルチインスタンスの検出は MCP と CLI から利用できます。instance.list を呼び出すか、unterm-cli instance list を実行するか、~/.unterm/instances/ を確認してください。

AI エージェントの自動検出

Unterm は、マシン上のすべての AI コーディングエージェントに自身を認識させ、手動設定なしでターミナルを操作できるようにします。初回起動時（バージョンごと）に GUI が unterm-cli setup-ai を実行し、インストール済みのエージェント — Claude Code、Codex、Gemini CLI、Cursor、Windsurf、OpenCode — を検出して、それぞれに対して次の処理を行います。

• エージェントの グローバル 設定に unterm MCP サーバーを登録します（既存の設定にマージし、上書きはしません）。これにより、エージェントは起動した時点で実際のターミナルの一覧表示、実行、読み取り、スクリーンショット撮影ができます。
• エージェントのグローバルコンテキストファイル（CLAUDE.md / AGENTS.md / GEMINI.md）に、マーカーで区切られた短い Unterm の説明を追加します。これにより、MCP サーバーを読み込まないエージェントも Unterm の存在を認識できます。

登録されたブリッジ（unterm-cli mcp-stdio）は接続時に稼働中の制御サーバーを自動検出し、unterm-core を優先して、GUI インスタンスの記録をフォールバックとして使用します。そのため、静的な登録は再起動後も複数のウィンドウ間でも機能し続けます。接続したエージェントには、MCP の initialize instructions フィールドを介して使用方法の概要も送信されます。

unterm-cli setup-ai              # detect agents + register (idempotent; safe to re-run)
unterm-cli setup-ai --dry-run    # show what would change, write nothing
unterm-cli setup-ai --no-context # register the MCP server only, don't touch context files
unterm-cli setup-ai --remove     # undo: strip the server entry + context block from every agent

---

設定

ユーザー設定は次の場所にあります。

プラットフォーム	場所
macOS	~/.unterm/
Linux	~/.unterm/
Windows	%USERPROFILE%\.unterm\

ファイル：

ファイル	用途
core.json	ヘッドレス Core のエンドポイント、認証トークン、pid（MCP ベースの自動化で優先的に使用）
server.json	アクティブな GUI インスタンスの MCP/HTTP ポート、認証トークン、pid（自動、後方互換性のためアクティブな GUI を反映）
active.json	現在アクティブな GUI インスタンス id へのポインター（自動、以前のアクティブなインスタンスが終了した場合のみ更新）
instances/<name>.json	インスタンスごとのメタデータ（NATO id、ポート、トークン、pid、started_at、version、platform）
auth_token	アクティブな認証トークンの従来形式のミラー（後方互換性のため）
proxy.json	自動／手動プロキシ URL、除外設定、ノード、ローテーション、Clash コントローラーの状態
theme.json	アクティブなテーマ id
lang.json	保存されたロケールの上書き
compat.json	$TERM_PROGRAM を上書きする {"term_program": "..."}
scrollback.json	デフォルトのスクロールバック行数の上書き
update_check.json	バックグラウンドのアップデート確認ポーラーの状態（最終確認、確認済みの最新バージョン）
onboarded.json	初回起動フラグ（表示済みの ▼ 項目）
recording.json	録画設定（秘匿化パターンなど）
unterm.conf	ターミナル設定：フォント、色、ウィンドウ、シェル、[env]、[keys] — 設定リファレンスを参照
tasks.db	永続タスクストア。Agent Cockpit のフリート（メンバー、worktree、ブランチ、レビュー状態）はここに保存されます。古い fleets.json は一度だけインポートされます。
checkpoints.json	リポジトリごとのエージェント作業前スナップショット（dangling-commit の SHA、リポジトリごとの直近 20 件）
sessions/	録画メタデータのインデックス（プロジェクトごとのサブディレクトリ）
screenshots/	範囲指定スクリーンショット（PNG）

---

開発

前提条件：最近の安定版 Rust ツールチェーン。Linux ではさらに、get-deps に記載されたシステム依存関係が必要です。

make build        # all binaries (debug)
make check        # static checks
make test         # tests
make clean-release-artifacts  # remove local dmg/msi/zip/deb/AppImage packages

現在のプラットフォーム向けにリリースビルドを作成します。

cargo build --release -p unterm -p unterm-cli -p unterm-mux -p strip-ansi-escapes

プラットフォーム用パッケージをビルドします。

# macOS — universal .app + zip (run on macOS)
ci/deploy.sh

# Linux — .deb
ci/deploy.sh
# Linux — AppImage
ci/appimage.sh

# Windows — staged release tree + zip
bash ci/deploy.sh
# Windows — MSI (requires WiX 6 at .\.tools\wix.exe — install via `dotnet tool install --tool-path .\.tools wix --version 6.0.1`)
pwsh -File ci/build-msi.ps1

macOS のコード署名と公証は ローカルでのみ行われます（CI の手順はありません）。これにより、Developer ID の .p12 秘密鍵を Mac の外に持ち出す必要がありません。証明書を保持する Mac で、一度だけセットアップします。

xcrun notarytool store-credentials UntermNotary \
  --apple-id <your-apple-id> --team-id 6NQM3XP5RF

リリースタグ

Unterm のリリースタグには、マイナータグ（v0.50）またはパッチタグ（v0.50.0）を使用できます。リリースの変更履歴とパッケージバージョンに合ったタグ形式を使用してください。まとまった修正や機能をリリースできる状態になった場合にのみ、タグを作成してください。

git tag -a vX.Y.Z -m "Unterm vX.Y.Z" && git push origin vX.Y.Z
make release-mac                    # build universal + sign + notarize + upload

make release-mac は git describe --exact-match HEAD からタグを読み取り、 ユニバーサルな x86_64 および aarch64 バイナリをビルドし、NOTARY_PROFILE=UntermNotary を指定して ci/sign-macos.sh を呼び出した後、生成された DMG を対応する GitHub Release に gh release upload でアップロードします。ローカルでの検証とアップロードが終わったら、 make clean-release-artifacts を実行して、ビルドキャッシュは残したまま ルート階層のリリースパッケージを削除してください。

すべての PR に対して、CI は macOS、Linux、Windows で cargo check を実行します。 タグ付きのプッシュ（vX.Y または vX.Y.Z）により、Linux と Windows の 2 つのプラットフォームのアーティファクトを GitHub Releases に公開する release-linux および release-windows ワークフローが実行されます。 macOS は意図的に CI の対象外です。詳細は上記をご覧ください。

---

リポジトリ

このリポジトリは Unterm のメインプロジェクトです。

https://github.com/zhitongblog/unterm

Unterm には、変更を加えた WezTerm のコンポーネントが含まれています。上流の WezTerm は、Wez Furlong とコントリビューターによる別個のプロジェクトです。

アンバサダー

Unterm はごく少人数のチームで開発されているため、多くの人は別の開発者から紹介されてこのプロジェクトを知ります。Unterm について記事を書いたり、録音したり、話したりした場合は、リンクを共有してください。登録は不要です。あなたの名前とともに unterm.app/ambassador に掲載されます。いくつか、誠実さを保つための基本ルールがあります。ユーザーであることを明記し、自分の言葉で書き、自己宣伝が歓迎される場所にのみ投稿してください。また、偽アカウント、偽のレビュー、購入したスターは禁止です。

---

Unterm によって時間を節約できたら、GitHub でスターを付けてください。それが、ほかの人にこのプロジェクトを知ってもらうための主な方法です。