API-HANDBUCH / 01

Agentensteuerung, die maschinenlesbar bleibt.

Erzeugte Bash- und PowerShell-Helfer plus authentifizierte JSON-APIs lassen einen Agent echte PTY-Worker erzeugen und steuern, Evidenz prüfen und expliziten Zustand publizieren. MidTerm liefert Transport und Persistenz – kein weiteres Modell.

Von Johannes G. E. Schmidt · Aktualisiert am 14. Juli 2026

60-SEKUNDEN-PFAD / 02

Starten. Exakte ID erfassen. Diese Session adressieren.

In einem MidTerm-Terminal ausführen. MidTerm erzeugt und aktualisiert die lokalen .midterm-Helfer für das Arbeitsverzeichnis der Session.

Bash

. .midterm/mtcli.sh

worker_json=$(mt_bootstrap "review worker" "$PWD" codex status)
sid=$(printf '%s' "$worker_json" | jq -r '.session.id')

mt_prompt "$sid" \
  "Review the auth change, run focused tests, then publish a verified checkpoint."
mt_tail "$sid" 80

mt_publish_status \
  working \
  "Reviewing auth change" \
  "Run focused tests" \
  "Publish verification" \
  MidTerm \
  "$sid" \
  "$PWD"

mt_checkpoint \
  verified \
  "Focused tests passed" \
  "18 backend tests" \
  MidTerm \
  "$sid" \
  "$PWD"

mt_control_plane | jq

PowerShell

. .\.midterm\mtcli.ps1

$worker = Mt-Bootstrap `
  -Name 'review worker' `
  -Cwd $PWD.Path `
  -Profile codex `
  -SlashCommands @('status')
$sid = ($worker | ConvertFrom-Json).session.id

Mt-Prompt -InputArgs @(
  $sid
  'Review the auth change, run focused tests, then publish a verified checkpoint.'
)
Mt-Tail -InputArgs @($sid, '80')

Mt-PublishStatus `
  -State working `
  -Summary 'Reviewing auth change' `
  -CurrentTask 'Run focused tests' `
  -NextAction 'Publish verification' `
  -Project MidTerm `
  -SessionId $sid `
  -RepositoryPath $PWD.Path

Mt-Checkpoint `
  -Kind verified `
  -Summary 'Focused tests passed' `
  -Details '18 backend tests' `
  -Project MidTerm `
  -SessionId $sid `
  -RepositoryPath $PWD.Path

Mt-ControlPlane | ConvertFrom-Json

mt_bootstrap NAME CWD PROFILE [SLASH_COMMAND ...] liefert JSON zurück. Der exakte Griff für diesen laufenden Worker ist session.id; eine Session nicht aus ihrem Anzeigenamen erraten. Das Bash-Beispiel nutzt jq nur zum Auslesen dieses Feldes.

RUNTIME-GRENZE / 03

Ein überwachtes PTY ist nicht Agent Controller.

Die Flags sind bewusst getrennt, weil die Ausführungsmodelle verschieden sind.

`agentControlled: true`	Überwachungsmetadatum einer normalen Terminal-Session. `mt_bootstrap` erzeugt diesen Worker-Typ, injiziert Anleitung und startet die gewählte CLI in einem echten `mthost`-PTY.
`appServerControlOnly: true`	Eine explizite provider-gestützte Agent-Controller-Session über `mtagenthost`: strukturierte Historie, Tool-Lebenszyklus, Freigaben, Fragen, Diffs und Turn-Steuerung – ohne PTY oder Terminal-Puffer.
Normales Terminal	Funktioniert mit jedem Terminal-Programm und stellt Puffer, Tail, Paste, rohe Tasten, Git, Browser, Historie und Control-Plane-Helfer bereit. Die CLI-Ausgabe bleibt Terminal-Ausgabe.
Keine Auto-Konvertierung	Codex, Claude Code, Grok, OpenCode oder eine andere CLI im Terminal zu starten, konvertiert die Session niemals stillschweigend in Agent Controller.

Vor der Wahl des Steuerpfads mt_agent_capabilities abfragen. Jede Session meldet agentControlled, appServerControlAttached, appServerControlOnly, surface, profileHint und unterstützte promptModes.

BEFEHLSKARTE / 04

Die schmalste explizite Oberfläche nutzen.

Dieselbe erzeugte Datei lässt sich dot-sourcen oder direkt als .midterm/mtcli.sh mt_status beziehungsweise pwsh .midterm\mtcli.ps1 mt_status ausführen.

Erzeugen und prüfen	`mt_sessions`, `mt_new_session [SHELL] [CWD]`, `mt_bootstrap NAME CWD PROFILE [SLASH_COMMAND ...]`, `mt_tail [SESSION_ID] [LINES]`, `mt_buffer [SESSION_ID]`, `mt_activity [SESSION_ID] [SECONDS] [BELL_LIMIT]`.
PTY steuern	`mt_prompt [SESSION_ID] TEXT`, `mt_prompt_now [SESSION_ID] TEXT`, `mt_slash [SESSION_ID] COMMAND`, `mt_paste`, `mt_sendtext`, `mt_sendkeys` sowie explizite Helfer für Enter, Strg-C, Escape und Pfeiltasten.
Browser-Evidenz	`mt_preview`, `mt_open`, `mt_status`, `mt_outline`, `mt_query`, `mt_text`, `mt_exec`, `mt_click`, `mt_fill`, `mt_wait`, `mt_log`, `mt_proxylog`, `mt_screenshot`.
Repository-Zustand	`mt_repo list\|status\|add PATH [ROLE] [LABEL]\|remove REPO_ROOT\|refresh [REPO_ROOT]` und `mt_supervise [REPO_PATH ...]`.
Eingabehistorie	`mt_input_history [SESSION_ID] [KIND] [LIMIT]`, `mt_input_history_show`, `mt_input_history_replay`, `mt_input_history_delete`, `mt_input_history_clear`.
Publizierter Zustand	`mt_work_list\|add\|update\|delete`, `mt_publish_status`, `mt_status_list\|clear`, `mt_checkpoint`, `mt_checkpoints`, `mt_events`.
Verteilen	`mt_dispatch SESSION_ID[,SESSION_ID...] TEXT` sendet einen expliziten Turn an benannte lokale Sessions. `mt_control_plane` liest den resultierenden Host-Snapshot.

JSON-VERTRÄGE / 05

Stabile Wurzeln, explizite Datensätze.

Diese Antwortschlüssel verwenden, statt Terminal-Prosa zu parsen.

`mt_bootstrap`	`session`, `profile`, `launchCommand`, `slashCommands`, `guidanceInjected`, `midtermDir`. Die exakte Worker-ID ist `session.id`.
`mt_agent_capabilities`	`schemaVersion`, `features`, `workItemStates`, `sessionStates`, `sessions`. Session-Datensätze enthalten die oben genannten Runtime-Flags.
`mt_control_plane`	`workItems`, `sessionStatuses`, `checkpoints`.
`mt_events`	`latestSequence`, `events`. Die letzte Sequenz als `AFTER_SEQUENCE` für inkrementelle Lesezugriffe übergeben.
`mt_dispatch`	`results`; jedes Ergebnis hat `sessionId`, `accepted`, `queued` und ein nullable `error`.
Listen	`mt_work_list` → `totalCount`, `items`; `mt_status_list` → `statuses`; `mt_checkpoints` → `totalCount`, `checkpoints`.
`mt_input_history`	`totalCount`, `entries`. Entry-Typen sind `prompt`, `textPaste`, `imagePaste` und `fileUpload`.
`mt_repo list`	`repos`; jede Bindung enthält `repoRoot`, `label`, `role`, `source`, `isPrimary` und `status`.

Work-Item-Status: open, active, waiting, blocked, done, dismissed. Session-Status: working, waiting, needsInput, blocked, done. Prioritäten: low, normal, high, urgent.

Die Control Plane ist ein Ausgang, kein Agent. MidTerm persistiert, was Aufrufer publizieren; es erfindet keine Aufgaben, Zusammenfassungen, nächsten Schritte oder Abschlussmeldungen.

HTTP + AUTH / 06

Die Helfer sind authentifizierte API-Clients.

Für normale Arbeit die Helfer verwenden; die Routen direkt aufrufen, wenn ein anderes Werkzeug den rohen Vertrag braucht.

Worker	`POST /api/workers/bootstrap`, `GET /api/sessions/{id}/buffer/tail`, `POST /api/sessions/{id}/input/prompt`.
Control Plane	`GET /api/control-plane`, `GET /api/control-plane/capabilities`, `GET /api/control-plane/events`, `POST /api/control-plane/dispatch`.
Publizierte Datensätze	`/api/control-plane/work-items`, `/api/control-plane/session-status/{sessionId}`, `/api/control-plane/checkpoints`.
Historie und Git	`/api/input-history`, `/api/input-history/{id}/replay`, `/api/git/repos`, `/api/git/repos/refresh`.

Der erzeugte Helfer enthält einen maschinenlokalen Browser-Session-Zugang mit ungefähr acht Tagen Laufzeit. .midterm/mtcli.sh und .midterm/mtcli.ps1 wie Geheimnisse behandeln. Mit MT_API_KEY wird stattdessen Authorization: Bearer verwendet.

Für Fernzugriff MidTerms HTTPS- und Passwortschutz aktiv lassen und den Netzwerkpfad begrenzen. Siehe Tailscale-Sicherheitsleitfaden für Fernzugriff.

GRENZEN / 07

Deterministisch, wo es zählt. Ehrlich, wo es nicht geht.

Diese Grenzen verhindern, dass Automatisierung mehr Wissen vorgibt, als sie besitzt.

Attention	`mt_attention` ordnet Sessions anhand von Prozessprofil, Timing, Aktivitäts-Heat und Bells. Das ist operative Orientierung, kein semantischer Beweis dafür, dass ein Agent fertig oder blockiert ist.
Prompt-Modus	`mt_prompt` nutzt den zustandsabhängigen automatischen Pfad. `mt_prompt_now` nur verwenden, wenn ausdrücklich zuerst unterbrochen werden soll.
Dispatch	Dispatch ist unmittelbar und lokal. Er wartet nicht auf ein freies PTY und führt keine PTY-Warteschlange; `queued` ist derzeit false. Hub-Varianten lesen entfernte Snapshots, Events und Capabilities, schreiben oder dispatchen aber nicht rechnerübergreifend.
Browser	Browser-Befehle brauchen eine verbundene MidTerm-Oberfläche und eine steuerbare Vorschau. Die meisten Browser-Helfer liefern kompakten Text; `mt_capabilities --json` ist die Discovery-Ausnahme.
Historie	Die Eingabehistorie erfasst pro Session explizite, von MidTerm behandelte Prompts, Terminal-Sends, Pastes, Bilder und Dateien. Sie rekonstruiert nie Absicht aus PTY-Ausgabe; rohe `mt_sendtext`- oder `mt_sendkeys`-Aufrufe sind für sich keine Historieneinträge.
Referenzabdeckung	Das eingecheckte OpenAPI-Dokument listet noch nicht jede neuere Control-Plane-, History-, Git- und Browser-Route. Capability Discovery und die erzeugten Helfer sind die aktuelle ausführbare Oberfläche.

FAQ / 08

Exakte Antworten.

Kann ein KI-Agent MidTerm steuern?

Ja. Erzeugte Bash- und PowerShell-Helfer sowie authentifizierte HTTP-APIs können PTY-Worker anlegen, Prompts senden, Terminal-Tails lesen, Repositories und Browser-Vorschauen prüfen und strukturierten Arbeitszustand publizieren.

Nutzt MidTerm eigene KI, um Agent-Zustand abzuleiten?

Nein. Die Control Plane speichert explizite Work Items, Session-Status, Checkpoints und Events, die Agents oder Werkzeuge publizieren. Sie leitet keinen semantischen Zustand aus Terminal-Ausgabe ab. Die separate Attention-Ansicht und der automatische Prompt-Modus nutzen allerdings operative Heuristiken.

Erzeugt mt_bootstrap eine Agent-Controller-Session?

Nein. mt_bootstrap erzeugt einen echten PTY-Worker, markiert ihn als agentControlled, injiziert die erzeugten Helfer und startet das gewählte CLI-Profil. Eine appServerControlOnly-Session ist eine explizite provider-gestützte Agent-Controller-Oberfläche mit strukturierter Historie und ohne PTY.

Kann eine Control Plane auf andere Rechner dispatchen?

Heute nicht. Lokaler Dispatch kann einen Turn an explizite Session-IDs derselben MidTerm-Instanz verteilen. Hub-Endpunkte können entfernte Snapshots, Events und Capabilities lesen; entfernte Schreibzugriffe und rechnerübergreifender Dispatch sind nicht verfügbar.

Funktioniert das mit jeder CLI?

Die PTY- und generischen Session-Helfer funktionieren mit jedem Terminal-Programm. Bootstrap bietet eingebaute Startprofile für ausgewählte KI-CLIs; andere CLIs lassen sich normal oder über die rohe Bootstrap-API mit einem expliziten Startbefehl ausführen.

Ausführung real halten.
Steuerung explizit machen.

MidTerm installieren ↘Implementierung prüfen →