Ricette per ottenere di più da Unterm

Collegare Unterm ai tuoi agenti

Registra Unterm come server MCP presso ogni agente trovato, aggiunge una breve nota al loro contesto globale (CLAUDE.md, AGENTS.md, GEMINI.md) e collega gli hook di ciclo di vita che ne riportano lo stato.

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

Limita con --client claude-code (ripetibile); --remove annulla tutto.

Chi ha bisogno di te? Da uno script

La stessa posta di Ctrl Shift A, da riga di comando. Con --json alimenta una barra di stato, una notifica o 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

Gli stati sono waiting, done, working e idle, quelli in attesa per primi.

Stato preciso con gli hook ufficiali

Unterm ricava lo stato di un agente da titolo e schermo. Gli hook propri degli agenti (hook di Claude Code, notify di Codex, comando di notifica di Aider) sono più precisi: dicono «in attesa» nell'istante in cui l'agente chiede.

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

setup-ai lo fa già; questo installa solo gli hook, e --remove li toglie.

Un compito su più agenti, unisci il migliore

Ogni membro ha il proprio worktree git, branch e scheda. Confronta i diff, esegui i controlli in ogni worktree, unisci uno e scarta gli altri.

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

L'unione è uno squash lasciato in staging nel tuo repo — il commit spetta a te. Le modifiche non committate del membro sono incluse. Passa --cwd quando avvii da una shell; senza, la flotta usa la cartella del riquadro attivo.

Lascia che un agente suggerisca, non digiti

Il comando appare come testo fantasma nel riquadro. Tab lo accetta, continuare a scrivere lo ignora — senza di te non parte nulla.

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 mostra quelli in sospeso; cancel ne ritira uno.

Aprire una scheda, eseguire, leggere il risultato

Per uno script che ha bisogno di una vera shell con il tuo ambiente: crea una scheda nella cartella giusta, esegui un comando e aspetta che finisca, poi leggi lo schermo.

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 restituisce l'output alla fine del comando; exec run lancia e torna subito.

Dividere un riquadro dall'esterno

Metti un tail dei log o un watcher dei test sotto il riquadro in cui lavori, senza mouse.

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

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

Le direzioni sono right, left, down e up.

Più istanze di Unterm

Ogni Unterm in esecuzione ha un nome — alpha, bravo, … — e ogni comando CLI può puntare a una.

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

Senza --instance, i comandi vanno all'istanza attiva.

Parlare MCP direttamente

JSON-RPC riga per riga su TCP, su 127.0.0.1. Porta e token sono nel file dell'istanza; prima accedi, poi chiama uno qualsiasi dei 151 metodi.

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 elenca tutti i metodi; i client MCP possono usare invece il ponte unterm-cli mcp-stdio.

Passare la cronologia di un riquadro a un modello

Testo semplice, senza codici di escape: le ultime N righe, o l'intera sessione in Markdown con progetto e shell in testa.

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 mantiene i colori; --start-line/--end-line scelgono un intervallo.

Uno screenshot di tutta la cronologia

Un lungo PNG di tutto ciò che un riquadro ha stampato, renderizzato fuori schermo: funziona anche a finestra coperta.

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

--max-rows lo limita; su macOS, --scroll-app Safari fa lo stesso con la finestra di un'altra app.

Registrare una sessione in Markdown

Comandi e output, oscurati e conservati accanto al progetto in .unterm/sessions — che Unterm fa ignorare a 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> si limita a un progetto.

Salvare le schede e riaverle

Un insieme con nome di schede e delle loro cartelle. Da ripristinare dopo un riavvio o il giorno dopo.

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 mostra cosa si aprirebbe senza aprirlo.

Un'identità separata per progetto

Un profilo contiene token, un'identità git e chiavi SSH. I segreti stanno nel portachiavi di sistema e compaiono come variabili d'ambiente solo nelle schede di quel profilo.

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 chiede una volta l'accesso al portachiavi alla prima lettura di un segreto. Da un gestore di password con --from-stdin.

Una finestra amministratore su Windows

Apri la palette dei comandi e scegli «New Administrator Window». Windows chiede tramite UAC, poi apre un Unterm separato con privilegi elevati.

Non condivide nulla con la finestra normale — né Core, né server MCP, né pagina delle impostazioni —, quindi niente di ciò che gira col tuo account può scrivere in una shell elevata. Il titolo inizia con «Administrator:».

Regolarlo

Le impostazioni stanno in ~/.unterm/unterm.conf. Alcune da conoscere:

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 apre invece la pagina delle impostazioni nel browser.

Scorciatoie da imparare

L'elenco completo, con le tue modifiche, è in unterm-cli show-keys.