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로 제거합니다.

작업 하나를 여러 에이전트로, 최선을 병합

멤버마다 자기 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이며, 커밋은 당신이 합니다. 멤버의 커밋되지 않은 변경도 포함됩니다. 셸에서 시작할 때는 --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으로 범위를 고릅니다.

스크롤백 전체를 스크린샷으로

창이 출력한 모든 것을 긴 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 서버도, 설정 페이지도 없음——그래서 당신 권한으로 실행되는 프로그램이 관리자 셸에 입력할 수 없습니다. 제목은 “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.