上級者向け

Unterm を使い倒すレシピ

ここにあるコマンドはすべて、書く前に実際の Unterm で実行しています。コピーして、貼って、名前を変えるだけ。

エージェント

Unterm をエージェントにつなぐ

見つかったすべてのエージェントに Unterm を MCP サーバーとして登録し、グローバルコンテキスト（CLAUDE.md、AGENTS.md、GEMINI.md）に短い説明を加え、状態を報告するライフサイクルフックを設定します。

unterm-cli setup-ai --dry-run   # what would change
unterm-cli setup-ai             # register with every agent found

--client claude-code（複数指定可）で対象を絞れます。--remove ですべて元に戻せます。

スクリプトから「誰が待っている？」

Ctrl Shift A と同じ受信箱をコマンドラインで。--json を付ければステータスバーや通知、cron に流せます。

unterm-cli agent inbox

# just the ones waiting on you
unterm-cli --json agent inbox \
  | jq -r '.items[] | select(.state=="waiting") | "\(.agent): \(.task_hint // .pane_title)"'

出力

PANE       AGENT     STATE      FOR     TAB   TASK
3      ✋   codex     waiting    23s     2     Partition the ledger tables
4      ✓   claude    done       13s     3     Fix the flaky checkout e2e test
2      ⚡   claude    working    27s     1     Add rate limiting to /v1/charge

codex: Partition the ledger tables

状態は waiting、done、working、idle。待機中が先頭に並びます。

公式フックで正確な状態を

Unterm はタイトルと画面からエージェントの状態を読み取ります。エージェント自身のフック（Claude Code hooks、Codex notify、Aider の通知コマンド）はより正確で、質問した瞬間に「待機中」と伝えます。

unterm-cli agent enable-hooks --dry-run
unterm-cli agent enable-hooks

setup-ai は既にこれを行います。これはフックだけを入れる方法で、--remove で外せます。

1 つのタスクを複数のエージェントで、最良をマージ

各メンバーに専用の git worktree、ブランチ、タブ。差分を比べ、それぞれの worktree でチェックを走らせ、1 つをマージして残りは破棄します。

cd ~/code/payments-api
unterm-cli fleet launch --cwd "$PWD" --agents claude,codex \
  -- "add an idempotency key to POST /v1/charge"

unterm-cli review diff    --fleet add-an-idempotency-key --member 1 --stat
unterm-cli review verify  --fleet add-an-idempotency-key --member 1 --command "cargo test"
unterm-cli review merge   --fleet add-an-idempotency-key --member 1
unterm-cli review discard --fleet add-an-idempotency-key --member 2
unterm-cli fleet clean add-an-idempotency-key

出力

fleet add-an-idempotency-key launched — 2 member(s)
  claude    fleet/add-an-idempotency-key-1  ~/code/payments-api.fleet/add-an-idempotency-key-1
  codex     fleet/add-an-idempotency-key-2  ~/code/payments-api.fleet/add-an-idempotency-key-2
  +?     -0     idempotency.rs (new)
verification verify-1790326294259-0 queued: cargo test
merged fleet/add-an-idempotency-key-1 — staged in ~/code/payments-api (commit it yourself)
member 2 of add-an-idempotency-key discarded
fleet add-an-idempotency-key cleaned

マージはステージ済みで残る squash で、コミットはあなたが行います。メンバーの未コミットの変更も含まれます。シェルから起動するときは --cwd を付けてください。付けないとフォーカス中のペインのフォルダが使われます。

エージェントには打たせず、提案させる

コマンドはペインにゴーストテキストとして現れます。Tab で採用、入力を続ければ無視——あなたなしでは何も実行されません。

unterm-cli session suggest post --rationale "tests passed" \
  -- "git push origin feat/rate-limit"
unterm-cli session suggest list

出力

Suggestion: sg_1790324293038_1
Status: queued
SUGGESTION               PANE     AGENT      TEXT
sg_1790324293038_1       5        anonymous  git push origin feat/rate-limit

session suggest list で保留中を確認、cancel で取り下げ。

スクリプト

タブを開き、実行し、結果を読む

あなたの環境を持つ本物のシェルが必要なスクリプト向け：正しいフォルダにタブを作り、コマンドを実行して終了を待ち、画面を読みます。

P=$(unterm-cli session create --cwd ~/code/infra | awk '/^Pane:/{print $2}')
unterm-cli exec wait --pane-id $P --timeout-ms 600000 -- "git log --oneline -3 && ls"
unterm-cli session text --pane-id $P | tail -20

出力

2f1cf7d (HEAD -> main) init
README.md

exec wait は終了時に出力を返し、exec run は投げっぱなしです。

外からペインを分割

作業中のペインの下にログの tail やテストの監視を置く。マウスは不要です。

unterm-cli session split --direction down --size-percent 35 --cwd ~/code/web-dashboard

出力

Pane: 6
Title: /bin/zsh
Direction: down

方向は right、left、down、up。

複数の Unterm インスタンス

起動中の Unterm にはそれぞれ名前——alpha、bravo……——があり、どの CLI コマンドも宛先を指定できます。

unterm-cli instance set-title "payments on-call"
unterm-cli instance list
unterm-cli --instance bravo agent inbox
unterm-cli instance set-title --clear

出力

Title: payments on-call
ID        PID      MCP     HTTP    CWD                      TITLE
alpha     1383     49173   19877                            payments on-call

--instance を省くと、アクティブなインスタンスに送られます。

MCP を直接話す

127.0.0.1 上の TCP で行区切りの JSON-RPC。ポートとトークンはインスタンスファイルにあります。まずログインし、151 のメソッドのどれでも呼べます。

J=~/.unterm/server.json      # %USERPROFILE%\.unterm\server.json on Windows
PORT=$(jq .mcp_port $J); TOKEN=$(jq -r .auth_token $J)
{ printf '{"jsonrpc":"2.0","id":1,"method":"auth.login","params":{"token":"%s"}}\n' "$TOKEN"
  printf '{"jsonrpc":"2.0","id":2,"method":"agent.status"}\n'
  sleep 1; } | nc 127.0.0.1 "$PORT"

出力

{"id":1,"jsonrpc":"2.0","result":{"status":"ok"}}
{"id":2,"jsonrpc":"2.0","result":{"agents":[{"agent":"codex","pane_id":3,"state":"waiting",…},…],"enabled":true}}

unterm-cli reference で全メソッドを一覧。MCP クライアントは unterm-cli mcp-stdio ブリッジも使えます。

保存と共有

ペインの履歴をモデルに渡す

エスケープコードなしのプレーンテキスト：最後の N 行、またはプロジェクトとシェルの情報を先頭に記した Markdown でセッション全体を。

unterm-cli scrollback --pane-id 2 --tail 200 > last-run.txt
unterm-cli session export --pane-id 2 -o session.md

出力

---
unterm_session_id: e2320821-38dc-4148-b94f-9bd4eef56357
tab_id: 2
project_path: ~/code/payments-api
project_slug: payments-api

--escapes で色を残し、--start-line/--end-line で範囲を選べます。

スクロールバック全体をスクリーンショット

ペインが出力したすべてを 1 枚の縦長 PNG に。画面外でレンダリングするので、ウィンドウが隠れていても動きます。

unterm-cli screenshot --scrollback --pane-id 2 -o pane.png

--max-rows で上限を設定。macOS では --scroll-app Safari で他のアプリのウィンドウも同様に撮れます。

セッションを Markdown に録画

コマンドと出力を秘匿化し、プロジェクト内の .unterm/sessions に保存——Unterm はこのフォルダを git に無視させます。

unterm-cli session record start
# … work in the pane …
unterm-cli session record stop
unterm-cli sessions list
unterm-cli sessions read <session-id>

出力

Session id: next-core-5-1790324289544601
Block count: 4
Markdown: ~/code/infra/.unterm/sessions/1790324289544601/tab-5-1790324289544601.md
Exit reason: recording_stopped

sessions list --project <slug> で 1 つのプロジェクトに絞れます。

タブを保存して、呼び戻す

名前付きのタブとフォルダのセット。再起動後や翌日の作業で復元できます。

unterm-cli workspace save morning
unterm-cli workspace restore morning --dry-run
unterm-cli workspace restore morning

出力

Workspace: morning
Sessions: 6
Workspace: morning
Planned: 6

--dry-run は何が開くかを表示するだけで、実際には開きません。

自分好みに設定

プロジェクトごとに別の身元

プロファイルはトークン、git の身元、SSH 鍵を持ちます。シークレットはシステムのキーチェーンに保管され、そのプロファイルのタブにだけ環境変数として現れます。

unterm-cli profile create "Work — Acme" --accent "#E8B34B"
unterm-cli profile set-secret "Work — Acme" GITHUB_TOKEN     # asks for the value
unterm-cli session create --cwd ~/code/acme --profile work-acme

出力

Created profile "Work — Acme"
  ID:    work-acme
Stored GITHUB_TOKEN in keychain for profile work-acme

プロファイルのシークレットを初めて読むとき、macOS がキーチェーンへのアクセスを一度だけ尋ねます。パスワードマネージャーからは --from-stdin でパイプできます。

Windows の管理者ウィンドウ

コマンドパレットを開き「New Administrator Window」を選ぶと、UAC の確認のあと、独立した昇格済みの Unterm が開きます。

通常のウィンドウとは何も共有しません——Core も MCP サーバーも設定ページもなし——なので、あなたの権限で動くプログラムが昇格したシェルに入力することはできません。タイトルは「Administrator:」で始まります。

調整する

設定は ~/.unterm/unterm.conf にあります。知っておくと便利なもの：

font_size = 14

[window]
padding_left = 16
padding_right = 16
backdrop = "mica"        # Windows 11

[cockpit]
done_hold_secs = 30      # how long a finished agent stays marked

unterm-cli settings open でブラウザの設定ページを開くこともできます。

覚えておきたいキー

変更したものも含む完全な一覧は unterm-cli show-keys。

`CtrlShiftP`	コマンドパレット
`CtrlShiftA`	エージェント受信箱
`CtrlShiftAltA`	フリートを起動
`CtrlShiftS`	クイック選択：ラベルでパス、ハッシュ、URL をコピー
`CtrlShiftJ`	コンポーザー：長いプロンプトを書き、ペインが空いたら送信
`CtrlShiftG`	Git パネル
`CtrlShiftD / E`	右 / 下に分割
`CtrlShiftZ`	フォーカス中のペインを拡大

CLI reference · MCP reference · すべての機能を見る