Des recettes pour tirer le meilleur d'Unterm

Connecter Unterm à vos agents

Inscrit Unterm comme serveur MCP auprès de chaque agent trouvé, ajoute une courte note à leur contexte global (CLAUDE.md, AGENTS.md, GEMINI.md) et branche les hooks de cycle de vie qui rapportent leur état.

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

Limitez avec --client claude-code (répétable) ; --remove annule tout.

Qui a besoin de vous ? Depuis un script

La même boîte de réception que Ctrl Shift A, en ligne de commande. Avec --json, elle alimente une barre d'état, une notification ou un 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

Les états sont waiting, done, working et idle, ceux en attente d'abord.

Un état précis grâce aux hooks officiels

Unterm déduit l'état d'un agent de son titre et de l'écran. Les hooks propres aux agents (hooks de Claude Code, notify de Codex, commande de notification d'Aider) sont plus précis : ils signalent « en attente » dès que l'agent pose sa question.

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

setup-ai le fait déjà ; ceci installe seulement les hooks, et --remove les retire.

Une tâche sur plusieurs agents, fusionner la meilleure

Chaque membre a son worktree git, sa branche et son onglet. Comparez les diffs, lancez vos vérifications dans chaque worktree, fusionnez-en un, écartez les autres.

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

La fusion est un squash laissé indexé dans votre dépôt — le commit vous revient. Les modifications non commitées d'un membre sont incluses. Passez --cwd quand vous lancez depuis un shell ; sinon la flotte prend le dossier du panneau actif.

Laisser un agent suggérer, pas taper

La commande apparaît en texte fantôme dans le panneau. Tab l'accepte, continuer à taper l'ignore — rien ne s'exécute sans vous.

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 montre ce qui est en attente ; cancel en retire une.

Ouvrir un onglet, lancer, lire le résultat

Pour un script qui a besoin d'un vrai shell avec votre environnement : créer un onglet dans le bon dossier, lancer une commande et attendre sa fin, puis lire l'écran.

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 renvoie la sortie à la fin de la commande ; exec run lance et rend la main.

Diviser un panneau de l'extérieur

Placez un tail de logs ou un observateur de tests sous le panneau où vous travaillez, sans la souris.

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

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

Directions : right, left, down et up.

Plusieurs instances d'Unterm

Chaque Unterm en cours a un nom — alpha, bravo, … — et toute commande CLI peut en viser une.

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

Sans --instance, les commandes vont à l'instance active.

Parler MCP directement

Du JSON-RPC ligne par ligne sur TCP, sur 127.0.0.1. Le port et un jeton sont dans le fichier d'instance ; connectez-vous d'abord, puis appelez l'une des 151 méthodes.

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 liste toutes les méthodes ; les clients MCP peuvent utiliser le pont unterm-cli mcp-stdio.

Donner l'historique d'un panneau à un modèle

Du texte brut, sans codes d'échappement : les N dernières lignes, ou toute la session en Markdown avec le projet et le shell en tête.

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 garde les couleurs ; --start-line/--end-line choisissent une plage.

Capturer tout un historique

Un long PNG de tout ce qu'un panneau a affiché, rendu hors écran : cela marche même fenêtre masquée.

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

--max-rows le limite ; sur macOS, --scroll-app Safari fait de même pour la fenêtre d'une autre app.

Enregistrer une session en Markdown

Commandes et sorties, expurgées et rangées à côté du projet dans .unterm/sessions — qu'Unterm fait ignorer par 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> se limite à un projet.

Sauver vos onglets, les retrouver

Un ensemble nommé d'onglets et de leurs dossiers. À restaurer après un redémarrage, ou le lendemain.

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 montre ce qui s'ouvrirait sans l'ouvrir.

Une identité distincte par projet

Un profil contient des jetons, une identité git et des clés SSH. Les secrets vivent dans le trousseau du système et n'apparaissent comme variables d'environnement que dans les onglets de ce profil.

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 demande une fois l'accès au trousseau à la première lecture d'un secret. Depuis un gestionnaire de mots de passe : --from-stdin.

Une fenêtre administrateur sous Windows

Ouvrez la palette de commandes et choisissez « New Administrator Window ». Windows demande via l'UAC, puis ouvre un Unterm séparé, élevé.

Elle ne partage rien avec votre fenêtre normale — ni Core, ni serveur MCP, ni page de réglages — : rien de ce qui tourne sous votre compte ne peut taper dans un shell élevé. Son titre commence par « Administrator: ».

Régler

Les réglages sont dans ~/.unterm/unterm.conf. Quelques-uns à connaître :

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 ouvre plutôt la page de réglages dans le navigateur.

Les raccourcis à retenir

La liste complète, avec vos modifications, s'obtient par unterm-cli show-keys.