Paperclip: Kostenloses Tool verwandelt KI-Agenten in ein Softwareteam

Die meisten Entwickler, die mehrere KI-Agenten betreiben, stoßen um den fünften Agenten herum an dieselbe Grenze. Man hat Claude Code in einem Terminal, der einen Backend-Dienst umschreibt, Codex in einem anderen, der Tests generiert, Cursor, der eine Komponente bearbeitet, und drei weitere Tabs, die man vergessen hat zu überprüfen. Niemand weiß, was der andere tut. Die Kosten explodieren. Zwei Agenten duplizieren dieselbe Arbeit. Einer läuft sechs Stunden lang und produziert nichts Nützliches, weil ihm niemand ein klares Ziel vorgegeben hat.

Paperclip behebt dieses Problem. Es ist eine Open-Source-Orchestrierungsplattform, die Ihre verstreuten KI-Agenten in ein strukturiertes Unternehmen verwandelt, komplett mit Organigrammen, zugewiesenen Rollen, Aufgabenverwaltung, Budgetgrenzen und Audit-Protokollen. Es erreichte in weniger als drei Wochen über 35.000 GitHub-Sterne, was zeigt, wie viele Entwickler dieselbe Frustration empfanden.

Dieser Artikel führt Sie durch die Einrichtung, Strukturierung Ihres ersten Agenten-Unternehmens und dessen Betrieb, damit die Arbeit tatsächlich erledigt wird, ohne dass Sie jedes Terminal überwachen müssen.

Was Paperclip ist (und was nicht)

Bevor Sie etwas installieren, sollten Sie verstehen, was Sie erhalten.

Paperclip ist eine Orchestrierungsschicht. Es koordiniert Agenten, verfolgt deren Arbeit, kontrolliert deren Budgets und gibt ihnen Kontext zu den Unternehmenszielen. Es erstellt keine Agenten, ersetzt Ihren KI-Anbieter nicht und fügt keine Chat-Oberfläche hinzu.

Das mentale Modell, das das Paperclip-Team verwendet: „Wenn Claude Code ein Mitarbeiter ist, ist Paperclip das Unternehmen.“

Das bedeutet:

• Agenten haben Rollen, nicht nur Prompts
• Aufgaben haben Verantwortliche, nicht nur offene Terminals
• Budgets haben harte Grenzen, nicht nur ein Gefühl
• Alles wird in einem Audit-Trail protokolliert

Paperclip funktioniert mit Claude Code, OpenAI Codex, Cursor, Gemini CLI und jedem Agenten, der einen Webhook oder ein Heartbeat-Signal empfangen kann. Sie bringen die Agenten mit. Paperclip führt das Unternehmen.

Es ist explizit nicht:

• Eine Chatbot-Benutzeroberfläche
• Ein Drag-and-Drop-Workflow-Builder wie n8n oder Zapier
• Ein Framework zum Schreiben von Agenten
• Nützlich für Single-Agent-Anwendungsfälle

Wenn Sie gelegentlich einen einzelnen KI-Agenten betreiben, ist Paperclip überdimensioniert. Wenn Sie drei oder mehr Agenten für laufende Arbeiten einsetzen, ist es das fehlende Puzzleteil.

Paperclip installieren

Sie benötigen Node.js 20+, pnpm 9.15+ und das war’s. Paperclip wird mit einer eingebetteten PostgreSQL-Datenbank geliefert, sodass Sie keinen externen Speicher einrichten müssen.

Der schnellste Weg zum Start:

npx paperclipai onboard --yes

Dies lädt das CLI herunter, führt das Onboarding mit sinnvollen Standardeinstellungen durch und startet den Server auf Port 3100. Öffnen Sie http://127.0.0.1:3100 und Sie sehen das Dashboard.

Wenn Sie beitragen oder den Code genauer untersuchen möchten:

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev

Wenn Sie Docker bevorzugen:

docker compose -f docker-compose.quickstart.yml up --build

Was auf der Festplatte erstellt wird:

~/.paperclip/instances/default/
  config.json          — Server- und Speichereinstellungen
  db/                  — eingebettete PostgreSQL-Datendateien
  secrets/master.key   — Verschlüsselungsschlüssel (automatisch generiert)
  logs/                — Server-Protokolle
  data/storage/        — Dateianhänge
  workspaces/<agent>/  — Arbeitsverzeichnisse pro Agent

Der lokale Modus verwendet standardmäßig die local_trusted Authentifizierung, die die Anmeldung überspringt und einen synthetischen „Board“-Benutzer verwendet. Sie können das Dashboard sofort nutzen, ohne ein Konto erstellen zu müssen.

Sobald Sie angemeldet sind, führen Sie den Gesundheitscheck durch:

paperclipai doctor

Wenn etwas falsch konfiguriert ist, behebt --repair die meisten Probleme automatisch:

paperclipai doctor --repair

Ihr erstes Unternehmen einrichten

In Paperclip ist ein „Unternehmen“ der übergeordnete Container für Ihre Agenten, Aufgaben, Ziele und Budgets. Stellen Sie es sich wie ein Projekt vor, nur dass jedes Projektmitglied ein KI-Agent mit einer Rolle und einer Berichtslinie ist.

Erstellen Sie über das Dashboard ein neues Unternehmen und geben Sie ihm ein Leitbild. Dies ist nicht nur Dekoration. Jede Aufgabe, die ein Agent erhält, lässt sich auf die Unternehmensmission zurückführen, sodass Agenten den Kontext verstehen, warum sie die Arbeit tun und nicht nur was zu tun ist. Dies ist wichtig für die Entscheidungsfindung bei längeren Agentenläufen.

Ein einfaches Beispiel für eine Mission: „Entwickeln und pflegen Sie eine REST-API für das Kundenauftragsmanagement. Priorisieren Sie Korrektheit über Geschwindigkeit. Dokumentieren Sie jeden öffentlichen Endpunkt.“

Diese eine Aussage gibt Ihren Agenten einen Filter für jede Entscheidung, die sie treffen.

Ihre ersten Agenten hinzufügen

Jeder Agent in Paperclip hat einen Adapter, der definiert, welches KI-Tool er verwendet und wie er kommuniziert.

Die unterstützten Adapter von Haus aus:

Um einen Claude Code Agenten über die CLI hinzuzufügen:

paperclipai agent local-cli "Backend Engineer" --company-id <your-company-id>

Dies bootet den Agenten, installiert seine Fähigkeiten in ~/.claude/skills und generiert API-Anmeldeinformationen. Der Agent existiert nun in Ihrem Unternehmens-Organigramm und kann Aufgaben zugewiesen bekommen.

Einen Claude-Agenten konfigurieren (in der Benutzeroberfläche oder in der Pro-Agent-Konfiguration festlegen):

Eine Modellzuweisung nach Rolle ist vor dem Start überlegenswert. Opus auf jedem Agenten laufen zu lassen, wird schnell teuer. Eine praktische Aufteilung:

• CEO / Orchestrierungs-Agenten: Sonnet (strategisches Denken, den Kosten wert)
• Manager-Agenten: Haiku (Routing und Delegation, günstig und schnell)
• Kreative / Codierende ICs: Sonnet (hier zählt die Ausgabequalität)
• Formelhafte ICs: Haiku (Boilerplate-Generierung, Test-Scaffolding, Migrationen)

Diese Zuweisung kann Ihre monatlichen Agentenausgaben im Vergleich zum flächendeckenden Einsatz von Sonnet um 40-60 % senken, ohne dass es bei Routineaufgaben zu einem signifikanten Qualitätsverlust kommt.

Ihre Agenten-Organisation strukturieren

Hier ist eine funktionierende Struktur für ein kleines Softwareprojekt:

CEO (Sonnet)
 ├── CTO (Haiku)
 │    ├── Backend Engineer (Sonnet)
 │    ├── Frontend Engineer (Sonnet)
 │    └── QA Engineer (Haiku)
 └── Technical Writer (Haiku)

Der CEO-Agent hält die Mission und unterteilt sie in Ziele. Der CTO leitet Ziele an die Engineering-Agenten weiter. Ingenieure erledigen die Arbeit. Die Qualitätssicherung validiert. Der Redakteur dokumentiert.

Jeder Agent hat ein Heartbeat-Intervall, die Häufigkeit, mit der er aufwacht, seine zugewiesenen Aufgaben überprüft, arbeitet und beendet wird. Agenten laufen nicht kontinuierlich. Sie wachen auf, führen aus und schlafen. Das verhindert, dass die Kosten explodieren.

Empfohlene Intervalle:

• Codierungsagenten: 600 Sekunden (10 Minuten)
• On-Demand-Agenten: 86.400 Sekunden (einmal täglich) mit aktivierter Wake-on-Demand-Funktion
• Mindestsicheres Intervall: 30 Sekunden (weniger als dies birgt das Risiko von Kostenüberschreitungen und Spam)

Wie der Heartbeat funktioniert

Das Verständnis des Heartbeat-Modells ist entscheidend, um zuverlässige Arbeit von Ihren Agenten zu erhalten.

Jedes Mal, wenn ein Agent aufwacht, folgt er einem Neun-Schritte-Protokoll:

1. Identität über GET /api/agents/me bestätigen
2. Alle ausstehenden Genehmigungs-Callbacks bearbeiten
3. Zugewiesene Aufgaben von GET /api/companies/{companyId}/issues abrufen
4. Priorisieren: Aufgaben in Bearbeitung zuerst, dann To-Do; blockierte Aufgaben überspringen, es sei denn, sie können entsperrt werden
5. Aufgabe über POST /api/issues/{issueId}/checkout auschecken (wenn ein anderer Agent sie bereits übernommen hat, ist die Antwort 409 und dieser Agent fährt fort)
6. Den vollständigen Aufgabenkontext und den Kommentarverlauf lesen
7. Die Arbeit erledigen
8. Die Aufgabe mit Kommentaren und Statusänderungen aktualisieren
9. Bei Bedarf Unteraufgaben mit Eltern- und Ziel-IDs delegieren

Der Auscheckmechanismus in Schritt 5 verhindert doppelte Arbeit. Zwei Agenten können nicht dieselbe Aufgabe übernehmen. Wenn einer daran arbeitet, überspringt der andere sie automatisch.

Paperclip injiziert Kontext in jeden Agentenlauf über Umgebungsvariablen:

PAPERCLIP_TASK_ID          # welche Aufgabe diesen Lauf ausgelöst hat
PAPERCLIP_WAKE_REASON      # warum der Agent aufgewacht ist (Timer, Erwähnung, Zuweisung)
PAPERCLIP_AGENT_ID         # die Identität des Agenten
PAPERCLIP_API_URL          # URL zum Aufruf der Paperclip-API

Agenten können diese nutzen, um Updates zu posten, Unteraufgaben zu erstellen, Genehmigungen anzufordern und zu delegieren – alles innerhalb eines einzigen Heartbeats.

Aufgaben zuweisen und Arbeit verfolgen

Aufgaben in Paperclip funktionieren wie GitHub-Issues in Kombination mit einem Projektmanagement-Tool. Erstellen Sie eine über die Benutzeroberfläche oder CLI:

paperclipai issue create \
  --company-id <id> \
  --title "Add pagination to the orders endpoint" \
  --assignee-agent-id <backend-engineer-id>

Aufgaben können Folgendes haben:

• Übergeordnete Aufgaben zur Aufteilung großer Arbeiten in Unteraufgaben
• Ziellinks, damit Agenten wissen, welchem Unternehmensziel dies dient
• Kommentare für Kontext, Genehmigungsanfragen und Statusaktualisierungen
• @-Erwähnungen, um einen bestimmten Agenten bei Bedarf zu aktivieren (kein Warten auf den nächsten Heartbeat)

Sie können alle offenen Aufgaben über die CLI anzeigen:

paperclipai issue list

Oder im Dashboard, wo Aufgaben ihren aktuellen Eigentümer, Status und den letzten Heartbeat-Lauf anzeigen, der sie berührt hat.

Budgetkontrolle, die tatsächlich funktioniert

Dies ist eine der nützlichsten Funktionen in Paperclip und wird von Neulingen in Multi-Agenten-Setups am meisten übersehen.

Jeder Agent erhält ein monatliches Token-Budget. Wenn es 80 % erreicht, wechselt der Agent automatisch zu kritischen Aufgaben. Bei 100 % pausiert er vollständig.

Legen Sie ein Budget in der Agentenkonfiguration fest. Der von der Community vorgeschlagene Startpunkt liegt bei 20-50 $/Monat pro Agenten-Tier. Sie können die Verbrauchsrate pro Agent, die Kosten pro Heartbeat und die kumulativen monatlichen Ausgaben alle über das Dashboard verfolgen.

Das Kosten-Dashboard zeigt, welche Agenten effizient sind und welche Token für unkonzentrierte Arbeit verbrennen. Wenn die Kosten pro Heartbeat eines Agenten steigen, ist das normalerweise ein Zeichen dafür, dass die Prompts zu vage oder der Aufgabenbereich zu weit gefasst sind. Sie beheben dies, indem Sie die Zuweisung präzisieren, nicht indem Sie das Budget erhöhen.

Ohne Budgetkontrollen kann ein falsch konfigurierter Agent, der mit einem 30-Sekunden-Intervall und aktivierter erweiterter Denkfunktion läuft, Hunderte von Dollar verbrauchen, bevor Sie es merken. Paperclip verhindert dies automatisch.

Laufzeit-Skills: Agenten neue Workflows ohne Umschulung beibringen

Eine der leistungsstärkeren Funktionen in Paperclip ist die Skill-Injektion. Wenn ein Agent läuft, erstellt der Adapter von Paperclip Symlinks zu SKILL.md-Dateien im Konfigurationsverzeichnis des Agenten und übergibt diese über --add-dir. Der Agent liest die Skill-Datei als Teil seines Kontexts und folgt dem Workflow.

Das bedeutet, dass Sie einem Agenten einen neuen Prozess beibringen können, z. B. wie man Commit-Nachrichten schreibt, Datenbankmigrationen handhabt oder API-Dokumentation formatiert, indem Sie eine Markdown-Datei schreiben. Kein Umschreiben von Prompts. Keine erneute Bereitstellung.

Sie schreiben den Skill:

# SKILL: Datenbankmigrationen

Beim Erstellen einer Migration:
1. Niemals bestehende Migrationsdateien ändern
2. Beschreibende Namen verwenden: JJJJMMTT_beschreibung.sql
3. Sowohl Up- als auch Down-SQL einschließen
4. Vor dem Commit lokal testen
5. Einen Kommentar hinzufügen, der den geschäftlichen Grund für die Änderung erläutert

Speichern Sie es im Skills-Verzeichnis, weisen Sie es Ihrem Backend-Agenten zu, und jeder zukünftige Heartbeat folgt diesem Prozess.

Wenn Sie von Ihren Agenten erstellte APIs testen

Wenn Ihre Agenten APIs entwickeln, benötigen Sie eine Möglichkeit, deren Ergebnisse schnell zu testen. Apidog passt hier perfekt. Es handhabt API-Design, Mock-Server und automatisierte Tests an einem Ort, sodass Sie, wenn Ihr Backend-Agent einen Endpunkt liefert, diesen sofort validieren können, ohne zwischen Swagger, Postman und einem separaten Mock-Tool wechseln zu müssen.

Sie können Test-Suites automatisch aus Ihrer OpenAPI-Spezifikation generieren, diese gegen die Ausgabe des Agenten ausführen und die Ergebnisse als Aufgabenkommentar zurückspielen. Der Agent nimmt dies beim nächsten Heartbeat auf und behebt die Fehler. Der vollständige Kreislauf, von Code über Test bis zur Korrektur, läuft ohne menschliches Eingreifen ab.

Apidog unterstützt REST, GraphQL und gRPC und ist kostenlos zu starten.

Mehrere Instanzen verwalten

Paperclip unterstützt mehrere isolierte Instanzen auf einer Maschine über die Umgebungsvariable PAPERCLIP_INSTANCE_ID oder das Flag --instance. Jede Instanz hat ihre eigene Konfiguration, Datenbank, Ports und Arbeitsbereiche.

Für die lokale Entwicklung erstellt der Worktree-Befehl eine vollständig isolierte Entwicklungsinstanz pro Git-Branch:

paperclipai worktree:make feature/orders-pagination

Dies gibt Ihnen separate Ports, Konfigurationen und eine auf diesen Branch zugeschnittene Datenbank. Sie können ein Testunternehmen gegen Feature-Code ausführen, ohne Ihre Produktions-Agentenkonfiguration zu beeinflussen. Wenn Sie fertig sind, reißen Sie es ab und es ist weg.

Funktionierende Multi-Agenten-Setups

Einige Muster, die gut funktionieren, sobald Sie die Grundlagen beherrschen:

• Zielkaskade: Schreiben Sie ein übergeordnetes Ziel auf Unternehmensebene, lassen Sie dann Ihren CEO-Agenten es in Projektziele aufteilen und jeden Manager-Agenten diese in Aufgaben. Agenten leisten bessere Arbeit, wenn sie die Kette des Zwecks verstehen, anstatt isolierte Anweisungen zu erhalten.
• Genehmigungsschranken: Für jede Agentenaktion, die Produktions-, Staging-Umgebungen oder Abrechnungen betrifft, konfigurieren Sie eine Genehmigungsschranke. Der Agent pausiert, sendet Ihnen eine Benachrichtigung und wartet auf eine Zustimmung, bevor er fortfährt. Dies fügt einen manuellen Schritt hinzu, fängt aber Probleme ab, bevor sie teuer werden.
• On-Demand-Aktivierung über @-Erwähnung: Anstatt eines schnellen Heartbeat-Intervalls (und der damit verbundenen Token-Kosten) stellen Sie Agenten auf ein langsames Intervall ein und verwenden Sie @-Erwähnungen in Aufgabenkommentaren, um sie bei Bedarf sofort zu aktivieren. So erhalten Sie schnelle Reaktionszeiten bei wichtiger Arbeit, ohne für ständiges Polling zu bezahlen.
• Separater Arbeitsbereich pro Agent: Jeder Agent hat sein eigenes Arbeitsverzeichnis unter workspaces/<agent-id>/. Halten Sie diese sauber. Agenten, die sich einen Arbeitsbereich teilen, treten sich gegenseitig auf die Füße. Die Isolation ist eingebaut; bekämpfen Sie sie nicht.

Der Einstieg dauert etwa 15 Minuten

Beim ersten Mal dauert das Onboarding weniger als 15 Minuten. Ein Befehl installiert und startet den Server. Das Hinzufügen Ihres ersten Agenten und das Erstellen einer Aufgabe dauert weitere fünf Minuten im Dashboard.

Der schwierigere Teil ist die gute Strukturierung Ihres Unternehmens: eine klare Mission formulieren, das richtige Modell für jede Rolle auswählen und sinnvolle Budgetgrenzen festlegen. Verbringen Sie damit 30 Minuten, bevor Sie mit der Zuweisung von Aufgaben beginnen, und Ihre Agenten werden viel bessere Ergebnisse erzielen, als wenn Sie alles schnell zusammenwürfeln und auf das Beste hoffen.

Wenn Sie bereits mehr als zwei KI-Agenten für ein laufendes Projekt einsetzen, ist dies einen Nachmittag Einrichtungszeit wert. Der Unterschied zwischen einem Terminal-Tab pro Agent und einem strukturierten Unternehmen mit Budgetkontrollen, Aufgabenverantwortung und Audit-Logs ist der Unterschied zwischen einem Nebenprojekt und etwas, das tatsächlich unbeaufsichtigt laufen kann.