Gib deinem Coding-Agent einen Bildkompressor

Bitte Claude Code oder Codex, „die Bilder in diesem Ordner zu komprimieren", und sieh zu, was passiert. Er wird anbieten, sharp zu installieren, ein Wegwerf-Node-Skript schreiben, die Qualitätseinstellungen raten und dir einen Ordner zurückgeben, in dem einige Dateien kleiner geworden sind, eine größer, und niemand sagen kann, welche.

Der Agent ist nicht das Problem. Bildkomprimierung gehört zu den Fähigkeiten, die trivial aussehen und es nicht sind: formatspezifische Encoder, Qualitätsheuristiken und ein Ergebnis, das man nur durch Messen beurteilen kann. Das ist die Aufgabe eines Werkzeugs, nicht eines Skripts, das der Agent jedes Mal neu improvisiert.

Die Aufteilung, die es funktionieren lässt

Es gibt einen Schritt, den ein Agent tatsächlich nicht kann: sich anmelden. pipic login öffnet einen Browser und wartet auf deine Bestätigung. Ein Agent in einer Sandbox hat ein anderes HOME, keinen Browser und keine Möglichkeit, den Knopf zu drücken.

Also verlange es nicht von ihm. Teile die Arbeit danach auf, wer sie wirklich erledigen kann:

Du, einmal. In deinem eigenen Terminal:

npm i -g @pipic/cli
pipic login

Die Anmeldedaten landen in ~/.config/pipic/config.json. Jedes Werkzeug, das auf dieser Maschine als du läuft, kann sie ab jetzt nutzen — auch dein Agent.

Dein Agent, jedes Mal danach. Füge das in die Konversation ein:

Use the `pipic` CLI to compress the images in ./assets.
It's already installed and signed in — do not install it or run
`pipic login` yourself.

  pipic ./assets --replace --json

It prints one JSON object per file:
  {"file":"a.png","status":"ok","before":102400,"after":41000,"saved":61400}
status is "ok", "skipped" or "error". "skipped" is not a failure — it
carries an `error` string explaining why (e.g. already small enough).

Exit 0 = all good, 1 = some files failed, 3 = not signed in,
4 = monthly quota exhausted.
Don't retry on exit 2 (usage error), 3 or 4 — on 3, stop and tell the
user to sign in. On exit 1, re-run only the paths whose rows had status
"error": a full re-run re-uploads every file and spends quota again.

Jede Zeile darin verhindert einen bestimmten Fehlschlag, und zwei davon verhindern teure.

Ohne das „do not install it or run pipic login yourself" versucht es der Agent trotzdem — und pipic login wartet bis zu zehn Minuten auf eine Browser-Bestätigung, die er nicht geben kann. In Codex oder Claude Code zeigt sich das als Tool-Aufruf, den dein Framework irgendwann abbricht, was sich liest, als hinge das Werkzeug.

Ohne die Zeile zu Exit-Code 1 tut ein Agent, der bei hundert Dateien zwei Fehlschläge sieht, das Naheliegende: Er lässt das ganze Verzeichnis erneut laufen. Es gibt keine lokale „schon komprimiert"-Prüfung — jede Datei wird erneut hochgeladen, und das Monatskontingent zählt jede angenommene Anfrage. Im kostenlosen Tarif sind das hundert im Monat, ein blinder Wiederholungslauf kann sie also komplett verbrauchen.

Der Rest sind billigere Fehler: ohne Ziel-Flag gibt es einen Nutzungsfehler, und ohne den Hinweis, dass skipped kein Fehlschlag ist, meldet er Probleme, wo keine sind — auch übersprungene Zeilen tragen einen error-String, der erklärt, warum sich nichts geändert hat.

Was der Agent sieht

Eine veranschaulichende Sitzung — die Form ist echt, die Zahlen sind erfunden, deine werden andere sein:

> compress the images in ./assets

I'll use the pipic CLI.

  $ pipic ./assets --replace --json

  {"file":"assets/hero.png","status":"ok","before":2411233,"after":486201,"saved":1925032}
  {"file":"assets/team.jpg","status":"ok","before":880640,"after":712704,"saved":167936}
  {"file":"assets/icon.svg","status":"skipped","before":0,"after":0,"saved":0,"error":"unsupported file type"}
  {"file":"assets/logo.webp","status":"skipped","before":18944,"after":18944,"saved":0,"error":"not smaller — original kept"}

Done. Two files compressed, saving about 2.0 MB — hero.png did most of
the work, dropping from 2.4 MB to 486 KB. I left logo.webp alone because
compressing it came back larger, and skipped icon.svg since SVG isn't a
raster format.

Der letzte Absatz ist der bemerkenswerte Teil. Der Agent rät nicht — er liest einen Vertrag. saved ist eine Byte-Zahl, kein Verhältnis. skipped ist nicht error. not smaller — original kept sagt genau, warum sich nichts geändert hat.

Improvisierte Skripte liefern das nicht. Sie geben aus, was der Agent gerade als console.log schreiben wollte, und die Zusammenfassung, die du zurückbekommst, ist der Eindruck des Agents von seiner eigenen Ausgabe.

Warum „nur wenn es kleiner ist" hier zählt

Bereits optimierte Bilder kommen manchmal größer zurück. Ein naives Skript überschreibt sie trotzdem, und dein Repository wächst bei jedem Lauf still an.

pipic schreibt eine Datei nur dann zurück, wenn das Ergebnis tatsächlich kleiner ist. Unter --replace bleibt das Original unangetastet; unter -o wird es mitkopiert, damit das Ausgabeverzeichnis ein vollständiger Satz bleibt. In beiden Fällen meldet sich die Datei als skipped, nicht als error — ein Agent, der die Ausgabe liest, erzählt dir also nicht von einem Fehlschlag, wo keiner war.

Das Flag, das nicht optional ist

--replace und -o <dir> schließen sich gegenseitig aus, und eines von beiden ist Pflicht. Führe pipic ./assets ohne beide aus, und es bricht mit einem Nutzungsfehler ab, bevor auch nur eine Anfrage rausgeht.

Das ist Absicht, und es zählt umso mehr, wenn ein Agent am Steuer sitzt. Ein Werkzeug, das standardmäßig überschreibt, überschreibt irgendwann etwas, das du behalten wolltest — in einem Lauf, den du nicht vollständig gelesen hast. Das Ziel explizit zu machen heißt, dass der Agent seine Absicht erklären muss, und du diese Absicht in dem Befehl siehst, den er dir zeigt.

Wenn der Agent deine Anmeldedaten nicht sieht

Sandboxed Agents, Container, CI — überall dort, wo ~/.config nicht deins ist. Erstelle einen Token auf deiner Kontoseite und stelle ihn in dieser Umgebung als PIPIC_TOKEN bereit. Er hat Vorrang vor der Anmeldedatei, derselbe Befehl funktioniert also ohne pipic login.

Beachte, dass pipic token create dich bewusst auf die Webseite schickt, statt lokal einen Token auszustellen. Eine gestohlene CLI-Anmeldeinformation sollte keine neuen ausstellen können.

Exit-Codes sind die Schnittstelle

Für alles Automatisierte ist das der wichtigste Teil:

3 heißt: pipic login ausführen — das Einzige, was du selbst tun musst. 4 heißt, dein Monatskontingent für CLI und API ist aufgebraucht; es wird nichts automatisch berechnet, und das Komprimieren auf pipic.cc bleibt ohnehin kostenlos und unbegrenzt.

Ein Agent, der auf diese Codes verzweigt, tut das Richtige, ohne dass du eine Textwand interpretieren musst. Einer, der auf Nachrichtenstrings mustervergleicht, bricht beim ersten Mal, wenn wir etwas umformulieren — genau deshalb sind die Codes, die status-Werte und die Feldnamen der stabile Vertrag, und der menschenlesbare error-Text ist es nicht.