Rezepte, um mehr aus Unterm herauszuholen

Unterm mit deinen Agenten verbinden

Meldet Unterm als MCP-Server bei jedem gefundenen Agenten an, ergänzt deren globalen Kontext (CLAUDE.md, AGENTS.md, GEMINI.md) um einen kurzen Hinweis und richtet die Lifecycle-Hooks ein, die ihren Zustand melden.

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

Mit --client claude-code (mehrfach möglich) einschränken; --remove macht alles rückgängig.

Fragen, wer dich braucht — aus einem Skript

Derselbe Posteingang wie Ctrl Shift A, auf der Kommandozeile. Mit --json speist er eine Statusleiste, eine Benachrichtigung oder einen Cron-Job.

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

Zustände sind waiting, done, working und idle, Wartende zuerst.

Genauer Agentenstatus über offizielle Hooks

Unterm liest den Zustand eines Agenten aus Titel und Bildschirm. Die eigenen Hooks der Agenten (Claude-Code-Hooks, Codex notify, Aiders Benachrichtigungsbefehl) sind genauer: Sie melden „wartet“ im Moment der Rückfrage.

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

setup-ai erledigt das bereits; dies sind nur die Hooks, und --remove entfernt sie.

Eine Aufgabe auf mehreren Agenten, die beste mergen

Jedes Mitglied bekommt eigenen Git-Worktree, Branch und Tab. Diffs vergleichen, Prüfungen im jeweiligen Worktree laufen lassen, eines mergen, den Rest verwerfen.

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

Der Merge ist ein Squash, der gestaged in deinem Repo liegt — der Commit gehört dir. Nicht committete Änderungen eines Mitglieds sind dabei. Gib beim Start aus einer Shell --cwd an; ohne nimmt die Fleet den Ordner des fokussierten Panes.

Agenten vorschlagen statt tippen lassen

Der Befehl erscheint als Geistertext im Pane. Tab übernimmt ihn, Weitertippen ignoriert ihn — ohne dich läuft nichts.

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 zeigt Offenes; cancel zieht einen Vorschlag zurück.

Tab öffnen, etwas ausführen, Ergebnis lesen

Für Skripte, die eine echte Shell mit deiner Umgebung brauchen: Tab im richtigen Ordner anlegen, Befehl ausführen und auf das Ende warten, dann den Bildschirm lesen.

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 liefert die Ausgabe, wenn der Befehl endet; exec run startet und kehrt sofort zurück.

Ein Pane von außen teilen

Setz ein Log-Tail oder einen Test-Watcher unter das Pane, in dem du arbeitest — ohne Maus.

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

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

Richtungen sind right, left, down und up.

Mehrere Unterm-Instanzen

Jedes laufende Unterm hat einen Namen — alpha, bravo, … — und jeder CLI-Befehl kann auf eines zielen.

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

Ohne --instance gehen Befehle an die aktive Instanz.

MCP direkt sprechen

Zeilenweises JSON-RPC über TCP auf 127.0.0.1. Port und Token stehen in der Instanzdatei; erst anmelden, dann jede der 151 Methoden aufrufen.

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 listet alle Methoden; MCP-Clients können stattdessen die Brücke unterm-cli mcp-stdio nutzen.

Den Verlauf eines Panes an ein Modell geben

Reiner Text ohne Escape-Codes: die letzten N Zeilen oder die ganze Sitzung als Markdown, mit Projekt und Shell im Kopf.

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 behält die Farben; --start-line/--end-line wählen einen Bereich.

Einen Screenshot des ganzen Scrollbacks

Ein langes PNG von allem, was ein Pane ausgegeben hat, außerhalb des Bildschirms gerendert — funktioniert auch bei verdecktem Fenster.

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

--max-rows begrenzt es; unter macOS macht --scroll-app Safari dasselbe mit dem Fenster einer anderen App.

Eine Sitzung als Markdown aufzeichnen

Befehle und Ausgaben, geschwärzt und neben dem Projekt in .unterm/sessions abgelegt — Unterm sorgt dafür, dass Git den Ordner ignoriert.

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> zeigt nur ein Projekt.

Tabs speichern und zurückholen

Eine benannte Sammlung von Tabs und ihren Ordnern. Nach einem Neustart oder am nächsten Tag wiederherstellen.

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 zeigt, was sich öffnen würde, ohne es zu öffnen.

Eine eigene Identität pro Projekt

Ein Profil enthält Tokens, eine Git-Identität und SSH-Schlüssel. Geheimnisse liegen im System-Schlüsselbund und erscheinen nur in den Tabs dieses Profils als Umgebungsvariablen.

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 fragt einmal nach Schlüsselbund-Zugriff, wenn ein Geheimnis zum ersten Mal gelesen wird. Aus einem Passwortmanager per Pipe mit --from-stdin.

Ein Administratorfenster unter Windows

Öffne die Befehlspalette und wähle „New Administrator Window“. Windows fragt über UAC nach und öffnet dann ein separates Unterm mit erhöhten Rechten.

Es teilt nichts mit deinem normalen Fenster — keinen Core, keinen MCP-Server, keine Einstellungsseite —, sodass nichts, was unter deinem Konto läuft, in eine erhöhte Shell tippen kann. Sein Titel beginnt mit „Administrator:“.

Anpassen

Die Einstellungen stehen in ~/.unterm/unterm.conf. Ein paar, die man kennen sollte:

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 öffnet stattdessen die Einstellungsseite im Browser.

Tastenkürzel, die sich lohnen

Die vollständige Liste samt deiner Änderungen liefert unterm-cli show-keys.