把 Unterm 用到極致的配方

把 Unterm 接入你的 agent

把 Unterm 作為 MCP 伺服器註冊給它找到的每一個 agent，在它們的全域性上下文（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 就能餵給狀態列、通知指令碼或定時任務。

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，等待中的排在最前。

用官方鉤子獲得精確的 agent 狀態

Unterm 會從標題和螢幕內容推斷 agent 的狀態。agent 自己的鉤子（Claude Code hooks、Codex notify、Aider 的通知指令）更精確：它一開口問你，就立刻報告“等待中”。

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

setup-ai 已經包含這一步；這裡是單獨裝鉤子，--remove 可以移除。

一個任務交給多個 agent，合併最好的

每個成員有自己的 git worktree、分支和標籤。比較 diff，在各自的 worktree 裡跑檢查，合併一個，丟棄其餘。

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，結果留在你倉庫的暫存區——提交由你來做。成員沒提交的改動也會一併帶上。從 shell 裡啟動時請帶上 --cwd，否則 fleet 會用當前聚焦窗格的目錄。

讓 agent 建議，而不是直接打字

指令以灰色提示出現在窗格里。按 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 撤回。

開一個標籤、跑指令、讀結果

適合需要真實 shell 和你的環境變數的指令碼：在正確的目錄建標籤，執行指令並等它結束，再讀螢幕內容。

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，開頭記錄專案和 shell 資訊。

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 選取範圍。

給整段歷史截一張長圖

把窗格輸出過的全部內容渲染成一張長 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> 只看某個專案。

儲存標籤佈局，隨時恢復

一組帶名字的標籤及其目錄。重啟後恢復，或者第二天接著幹。

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”。Windows 透過 UAC 確認後，會開啟一個獨立的、提權的 Unterm。

它和你的普通視窗不共享任何東西——沒有 Core、沒有 MCP 伺服器、沒有設定頁——所以以你身分執行的程式無法往提權 shell 裡打字。它的標題以“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 檢視。