把 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 查看。