Pu.sh: Mini-Coding-Agent in 400 Zeilen Shell-Code

Vor einem halben Jahr begann alles mit einer experimentellen Idee: einem Mini-Agenten, der sich selbst Aufgaben stellt und löst. Inspiriert von Projekten wie pi-autoresearch sollte er nicht nur funktionieren, sondern auch absolut portabel sein. Das Ergebnis? Pu.sh – ein Coding-Agent, der in nur 400 Zeilen Shell-Code daherkommt und dabei sieben essenzielle Werkzeuge für die Codebearbeitung mitbringt.

Die Philosophie hinter Pu.sh ist einfach: Keine externen Abhängigkeiten, nur Systembefehle. Das bedeutet konkret: Der Agent nutzt ausschließlich sh, curl, awk und Standard-Tools wie bash, grep oder find. Keine Python-Umgebungen, keine Node.js-Pakete, keine Container. Nur das, was auf fast jedem Unix-System bereits vorhanden ist. Doch wie schafft man es, in so wenigen Zeilen einen Agenten zu bauen, der nicht nur funktioniert, sondern auch interaktiv nutzbar ist?

Die Architektur: Minimalismus mit Systemprimitiven

Der Kern von Pu.sh besteht aus einem tighten Loop, der die Kommunikation mit KI-Modellen wie OpenAI oder Anthropic steuert. Das Besondere: Der Agent verarbeitet nicht nur einfache Textbefehle, sondern führt auch strukturierte Aufgaben aus – etwa das Lesen, Schreiben oder Bearbeiten von Dateien. Dafür setzt er auf JSON-Parser in `awk`, eine Sprache, die normalerweise nicht für solche Aufgaben gedacht ist.

Ein zentraler Baustein ist die Werkzeugoberfläche. Pu.sh bietet sieben grundlegende Funktionen:

• bash – Ausführung von Shell-Befehlen
• read – Lesen von Dateien
• write – Schreiben von Dateien
• edit – Bearbeiten von Dateien (Text-basiert)
• grep – Suchen in Dateien
• find – Auffinden von Dateien
• ls – Auflisten von Verzeichnissen

Diese Werkzeuge bilden die Grundlage für jede Interaktion mit dem Agenten. Die Syntax erinnert an die Schnittstelle von Tools wie Claude Code oder Pi (pi.dev), die ebenfalls ähnliche Funktionen bieten. Doch während diese Plattformen auf komplexe Backends setzen, kommt Pu.sh mit reinen Shell-Befehlen aus.

Herausforderungen und Workarounds: Warum awk für JSON?

Eines der größten Hindernisse bei der Entwicklung war die JSON-Verarbeitung. Da Pu.sh keine externen Bibliotheken nutzt, musste der Entwickler auf awk zurückgreifen – eine Sprache, die normalerweise für Textmanipulationen gedacht ist. Das Ergebnis sind „kreativ“ gestaltete `awk`-Skripte, die JSON-Strings zerlegen und strukturierte Daten verarbeiten. Solche Lösungen sind zwar nicht elegant, aber sie funktionieren – und das ist das Wichtigste.

Ein weiterer Knackpunkt war die KI-Integration. Der Agent muss nicht nur einfache Befehle ausführen, sondern auch komplexe Anweisungen in sinnvolle Aktionen umwandeln. Dafür nutzt er die OpenAI Responses API mit Unterstützung für Reasoning Items, die den Kontext zwischen den einzelnen Schritten erhalten. Auch hier gilt: Alles läuft über Standard-Tools, ohne zusätzliche Abhängigkeiten.

Testumgebung: 90 automatisierte Checks ohne API

Bevor Pu.sh veröffentlicht wurde, durchlief es eine rigorose Testphase. Insgesamt 90 automatisierte Tests prüften die Funktionalität der Werkzeuge – ohne dabei eine API aufzurufen. Stattdessen wurden die erwarteten Ausgaben direkt mit den tatsächlichen Ergebnissen verglichen. Das garantiert Stabilität und macht den Agenten zuverlässiger, als es viele größere Projekte wären.

Zu den getesteten Szenarien gehörten:

• Dateibearbeitung (Lesen, Schreiben, Bearbeiten)
• Suchoperationen mit grep und find
• Shell-Befehlsausführung mit Fehlerbehandlung
• Konsistenzprüfungen bei Mehrfachaufrufen

Diese Tests zeigen: Ein minimalistischer Ansatz muss kein Kompromiss bei der Qualität sein.

Grenzen und Zukunft: Was Pu.sh (noch) nicht kann

Natürlich hat Pu.sh auch klare Einschränkungen. Einige Features, die bei größeren Agenten selbstverständlich sind, fehlen hier bewusst:

• Keine grafische Oberfläche (TUI): Der Agent läuft rein textbasiert.
• Kein Streaming: Antworten werden nicht in Echtzeit angezeigt.
• Keine Bildverarbeitung: Visuelle Inhalte werden nicht unterstützt.
• Kein OAuth: Authentifizierung über externe Dienste ist nicht integriert.
• Keine Windows-Unterstützung: Der Agent ist auf Unix-Systeme beschränkt.
• Keine „Würde“: Die Codebasis ist bewusst roh und funktioniert – nicht mehr.

Doch genau diese Einschränkungen machen Pu.sh interessant. Sie zeigen, dass ein Coding-Agent ohne komplexe Infrastruktur funktionieren kann. Für Entwickler, die Kontrolle über ihre Tools behalten möchten, ist das ein starkes Argument.

Inspiration und Motivation: Warum weniger manchmal mehr ist

Die Idee zu Pu.sh entstand nicht aus dem Nichts. Ein entscheidender Impuls kam von Mario Zechners Talk „Taking Back Control of Your Tools“, in dem er dazu aufrief, Abhängigkeiten zu reduzieren und eigene Lösungen zu bauen. Ein weiterer Einfluss war Pi (pi.dev), das ähnliche Werkzeuge anbietet – allerdings mit deutlich mehr Infrastruktur.

Der Entwickler von Pu.sh betont ausdrücklich, dass er Teile der System-Prompts und Architektur von Pi adaptiert hat. Ohne diese Inspiration wäre das Projekt wohl nicht in dieser Form entstanden. Doch statt eine 1:1-Kopie zu erstellen, wurde Pu.sh als kompakte, portable Alternative konzipiert – eine Art „Do-it-yourself“-Version für Entwickler, die ihre eigenen Agenten bauen möchten.

Fazit: Ein Proof of Concept für mehr Autonomie

Pu.sh ist mehr als nur ein weiteres KI-Projekt. Es ist ein Manifest für Minimalismus in der Softwareentwicklung. Mit nur 400 Zeilen Shell-Code beweist es, dass ein vollwertiger Coding-Agent keine monolithische Infrastruktur braucht. Stattdessen setzt es auf Simplizität, Portabilität und Kontrolle – Werte, die in einer Welt voller komplexer KI-Tools oft verloren gehen.

Für Entwickler, die ihre eigenen Agenten bauen oder bestehende Tools anpassen möchten, bietet Pu.sh eine hervorragende Grundlage. Die Codebasis ist offen, die Architektur transparent, und die Grenzen sind klar definiert. Wer mehr braucht, kann sie erweitern – wer weniger will, hat bereits eine funktionierende Lösung.

In Zukunft könnte Pu.sh noch weiter wachsen. Vielleicht mit besseren Parsern, mehr Plattformunterstützung oder sogar einer einfachen GUI. Doch eines ist sicher: Der erste Schritt ist getan. Und er beweist, dass große Ideen manchmal in kleinem Code stecken.