Der Screenshot aus der Zwischenablage als Hermes-Input: der Befehl hermes clipboard image


Du hast einen Screenshot gemacht und willst genau eine Frage dazu stellen: „aus welcher Stage kommt dieser Fehler?“ Im Terminal ist der natürliche Griff Ctrl+V. Diesen Griff gibt es in einem Skript nicht — Skripte führen Befehle aus, sie drücken keine Tasten. Also hast du drei Zeilen Shell um xclip geschrieben, festgestellt, dass sie unter Windows nichts tun, ein anderes Set für macOS gebraucht und irgendwann aufgegeben und die Datei von Hand gespeichert.

Die am 6. November gemergte Änderung holt das in Hermes selbst. hermes clipboard image schreibt das Bild aus der Zwischenablage der Maschine in eine Datei: Bei Erfolg gibt der Befehl den Pfad aus, und mit --json liefert er eine stabile JSON-Antwort und eine Reihe klar getrennter Exit-Codes. Er liest nur die Zwischenablage der Maschine, auf der er läuft — kein Gateway, kein Session-Store, keine Profile-Datei.

Der alte Weg: das private Skript der TUI aufrufen

Hermes kann seit einer Weile Bilder ins Terminal einfügen, und die Implementierung in hermes_cli/clipboard.py leistet eine Menge plattformspezifische Arbeit. Der einzige exponierte Einstiegspunkt war aber ein internes Skript: ui-tui/scripts/clipboard_image.py. Ein Drittanbieter-Client, der Clipboard-Bilder wollte, musste PYTHONPATH auf den Hermes-Source-Tree zeigen lassen und dieses Skript aufrufen.

Es funktionierte, und es war an drei Stellen gleichzeitig fragil: Der Pfad konnte sich verschieben, die Argumente konnten sich ändern, und selbst seine true/false-Antwort konnte sich ändern. Das tiefer liegende Problem war „wo ist der Source-Tree?“ — warum sollte ein Client wissen, wo der Nutzer Hermes installiert hat?

Der neue Befehl packt denselben Extractor (hermes_cli.clipboard.save_clipboard_image) in einen dokumentierten Befehl mit Exit-Codes und JSON.

Ein Befehl, eine Datei auf der Platte

hermes clipboard image --out /tmp/shot.png

Bei Erfolg gibt er den Pfad aus. --out wird angelegt oder überschrieben, und sein Verzeichnis wird bei Bedarf erstellt. In Skripten willst du meist die JSON-Form:

hermes clipboard image --out /tmp/shot.png --json
{"ok": true, "path": "/tmp/shot.png", "mime": "image/png", "bytes": 248193}

mime wird nicht aus der Endung geraten — es wird aus den Magic Bytes der Datei gelesen, sodass PNG, JPEG, GIF, BMP, TIFF und WebP alle erkannt werden. Normalerweise ist die Ausgabe immer PNG, weil der Extractor konvertiert; die eine Ausnahme ist, wenn du eine Bild-Datei kopiert hast (ein Windows-/WSL-File-Drop), die Byte für Byte kopiert wird und ein jpg oder webp sein kann.

Jeder Ausgang hat seinen Exit-Code

In der Automatisierung ist der schlimmste Fehlermodus nicht das Scheitern — es ist das Scheitern ohne Begründung. Dieser Befehl trennt die Ausgänge:

Situation reason im JSON Exit
Ein Bild wurde geschrieben keins, ok: true 0
Die Zwischenablage enthält kein Bild (nur Text) no_image 1
Kein nutzbares Clipboard-Tool installiert no_tool, plus die gesuchten Tools 3
--out ist nicht schreibbar write_failed 4
Ungültige Argumente kein JSON, argparse-Usage-Fehler 2

no_image von no_tool getrennt zu halten ist wichtig: Das eine heißt, du hast keinen Screenshot gemacht, das andere, dass diese Maschine gar keine Zwischenablage lesen kann. Sie brauchen unterschiedliche Fixes. Auf einem Server ohne grafische Session bekommst du no_tool, keinen vagen Fehler.

Warum das einen eigenen Befehl verdient

Weil er eine konkrete Engineering-Frage klärt: Das Lesen einer Zwischenablage muss lokal sein.

Denk an die Art, wie Gateways deployt werden. Das Hermes-Gateway eines Nutzers läuft vielleicht auf einer Remote-Box oder in einem Container, während der Mensch und seine Zwischenablage auf einem Laptop sind. Wäre „lies die Zwischenablage“ ein Gateway-RPC, würde es die Zwischenablage der fernen Maschine lesen — nutzlos, meist leer. Der Befehl ist deshalb bewusst gerätelokal: keine Gateway-Verbindung, kein Session-Store, keine Profile-Datei, strikt „schreib das Clipboard-Bild dieser Maschine in diesen Pfad“.

Auch die schreibende Hälfte ist sorgfältig. Sie extrahiert in ein privates temporäres Verzeichnis neben dem Ziel und benennt die fertige Datei auf --out um, sodass bei jedem Fehlschlag die vorhandene Datei exakt so bleibt, wie sie war — kein halb geschriebenes Bild. Beim Überschreiben einer vorhandenen Datei bleiben deren Permission-Bits erhalten, eine 0600-Temp-Datei weitet sie also nicht still aus.

In Hermes einbauen

Sobald du einen Pfad hast, ist der Rest gewöhnlich. hermes chat akzeptiert bereits --image, ein Screenshot kann also mit einer Frage mitfahren:

hermes clipboard image --out /tmp/shot.png --json > /tmp/shot.json
hermes chat -q "Which stage is this error from? One conclusion and one command to check it." --image /tmp/shot.png --oneshot

Die Zwischendatei lässt sich mit jq leicht überspringen:

SHOT=$(hermes clipboard image --out /tmp/shot.png --json | jq -r .path) && hermes chat -q "What is misaligned in this UI?" --image "$SHOT" --oneshot

Lässt du --oneshot weg, bleibt hermes chat interaktiv, mit dem Bild an diese eine Frage gehängt — der Alltags-Loop „Screenshot, fragen, weiterreden“.

Die Plattform-Details, die du wirklich triffst

  • macOS: zuerst pngpaste (schnell, mehr Formate), dann osascript als immer vorhandener Fallback.
  • Windows: zuerst powershell, dann pwsh.
  • Linux: unter WSL versucht es zuerst powershell.exe; unter Wayland wl-paste; unter X11 xclip. Eine fehlgeschlagene WSL-Probe fällt durch, weil WSLg vielleicht trotzdem ein funktionierendes wl-paste oder xclip hat.
  • NixOS-Container-Modus: Jeder hermes-Subcommand läuft im verwalteten Container, dieser eingeschlossen, er kann die Host-Zwischenablage also nicht sehen, und --out ist ein Pfad im Container. Das ist eine Grenze des Container-Modus, kein Bug.

Eines ist das hier nicht: das Bild zeichnen. Inline-Bilder in CLI und TUI behandelt, wie Anhänge und von Tools erzeugte Bilder im Transkript erscheinen. Dieser Befehl ist die andere Richtung — wie ein Bild von der Zwischenablage auf die Platte kommt —, und beide werden meist zusammen benutzt.

Kannst du es heute nutzen

Der Befehl ist auf main (6. November, PR #150285) und nicht im v0.23.0-Tag. Die Prüfung ist trivial: Wenn hermes clipboard --help irgendetwas ausgibt, hat dein Build ihn; „invalid choice“ heißt, er fehlt. Er ist im Abschnitt hermes clipboard der CLI-Referenz dokumentiert, nach dem Upgrade passt die Seite also zu dem, was du hast.

Update (10.11.2026): Diese Änderungen sind mit v0.23.1 (9. November) erschienen – ein hermes update genügt. Die Aussage „nicht in v0.23.0“ oben stimmt weiterhin; v0.23.1 schließt die Lücke.

Und wenn du wissen willst, ob diese Maschine überhaupt eine Zwischenablage lesen kann, beantwortet der Befehl das selbst: Ohne verfügbares Bild unterscheidet er „kein Bild“ von „kein Tool“, und Letzteres listet die Tool-Namen auf, nach denen er gesucht hat — im Wesentlichen deine Install-Liste.

Die Kurzfassung

hermes clipboard image ist ein kleiner Befehl, der eine Schnittstellengrenze repariert: Er befördert „lies die lokale Zwischenablage“ von einem TUI-Implementierungsdetail zu einem dokumentierten Einstiegspunkt mit JSON und Exit-Codes und sagt die Gerätelokal-Regel klar. Für alle, die dagegen skripten, ist nicht der Befehl das Nützlichste, sondern die vier Exit-Codes — ein case-Statement trennt jetzt „kein Screenshot“, „kein Tool“, „nicht schreibbar“ und „fertig“, statt Fehlertext zu greppen.