Paperclip: Kostenloses Tool verwandelt KI-Agenten in ein Softwareteam

Die meisten Entwickler, die mehrere KI-Agenten betreiben, stoßen spätestens beim fünften Agenten an dieselben Grenzen: Claude Code läuft im Terminal und schreibt den Backend-Dienst um, Codex generiert Tests in einem anderen Fenster, Cursor bearbeitet irgendwo eine Komponente – und mindestens drei weitere Tabs geraten in Vergessenheit. Niemand weiß, was die anderen Agenten tun. Die Kosten steigen unkontrolliert. Zwei Agenten erledigen identische Aufgaben doppelt. Einer läuft sechs Stunden ohne Ergebnis, weil ihm ein klares Ziel fehlt.

Probiere Apidog noch heute aus

Paperclip löst dieses Problem: Eine Open-Source-Orchestrierungsplattform, die verteilte KI-Agenten in eine strukturierte Organisation integriert – mit Organigrammen, zugewiesenen Rollen, Aufgabenmanagement, Budgetlimits und Audit-Logs. Über 35.000 GitHub-Sterne in unter drei Wochen zeigen, wie dringend Entwickler diese Lösung suchten.

In diesem Beitrag lernst du, wie du Paperclip installierst, dein erstes Agenten-Unternehmen strukturierst und produktiv betreibst – damit Agenten sinnvoll arbeiten und du nicht ständig alle Terminals kontrollieren musst.

Was Paperclip ist (und was nicht)

Bevor du installierst, solltest du wissen, was Paperclip bietet.

Paperclip ist eine Orchestrierungsschicht: Es koordiniert Agenten, verfolgt Aufgaben und Budgets, vermittelt Kontext zu Unternehmenszielen. Paperclip erstellt keine Agenten, ersetzt deinen KI-Anbieter nicht, bietet keine Chat-Oberfläche.

Mentales Modell: „Wenn Claude Code ein Mitarbeiter ist, ist Paperclip das Unternehmen.“

• Agenten haben Rollen statt nur Prompts
• Aufgaben haben Verantwortliche statt offene Terminals
• Budgets haben harte Grenzen
• Alles ist im Audit-Trail nachvollziehbar

Paperclip funktioniert mit Claude Code, OpenAI Codex, Cursor, Gemini CLI und jedem Agenten, der Webhooks oder Heartbeats unterstützt. Du bringst die Agenten mit, Paperclip steuert das Unternehmen.

Klar ist auch, was es nicht ist:

• Keine Chatbot-Oberfläche
• Kein Drag-&-Drop-Workflow-Builder wie n8n oder Zapier
• Kein Framework für Agenten-Implementierungen
• Nicht sinnvoll für Einzel-Agenten-Usecases

Für Einzel-Agenten-Setups ist Paperclip überdimensioniert. Ab drei Agenten wird es unerlässlich.

Paperclip installieren

Voraussetzungen: Node.js 20+, pnpm 9.15+. Paperclip bringt eine embedded PostgreSQL mit, du musst keine externe DB konfigurieren.

Schnellstart:

npx paperclipai onboard --yes

Das CLI wird geladen, sinnvolle Defaults übernommen und der Server startet auf Port 3100. Öffne http://127.0.0.1:3100 für das Dashboard.

Für Beiträge oder tiefere Analysen:

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

Mit Docker:

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

Das wird auf der Platte angelegt:

~/.paperclip/instances/default/
  config.json          — Server- und Storage-Config
  db/                  — Embedded PostgreSQL
  secrets/master.key   — Generierter Verschlüsselungsschlüssel
  logs/                — Server-Logs
  data/storage/        — Dateianhänge
  workspaces/<agent>/  — Agent-spezifische Arbeitsverzeichnisse

Standardmäßig nutzt der lokale Modus local_trusted-Auth: keine Anmeldung, ein synthetischer Board-User. Du kannst das Dashboard direkt nutzen.

Gesundheitscheck nach dem Start:

paperclipai doctor

Mit --repair werden viele Fehler automatisch repariert:

paperclipai doctor --repair

Dein erstes Unternehmen einrichten

Ein Unternehmen ist der Container für Agenten, Aufgaben, Ziele und Budgets. Wie ein Projekt, dessen Mitglieder KI-Agenten mit Rollen und Berichtslinien sind.

Im Dashboard kannst du ein Unternehmen anlegen und ein Leitbild formulieren. Das ist nicht optional: Jede Aufgabe wird auf die Mission gemappt. So verstehen Agenten immer das warum hinter dem was. Das ist entscheidend für längere Laufzeiten und bessere Ergebnisse.

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

Erste Agenten hinzufügen

Jeder Agent besitzt einen Adapter für das jeweilige KI-Tool und die Kommunikationsart.

Unterstützte Adapter:

Agent	Adaptertyp	Paket
Claude Code	claude_local	@paperclipai/adapter-claude-local
OpenAI Codex	codex_local	@paperclipai/adapter-codex-local
Gemini CLI	gemini_local	@paperclipai/adapter-gemini-local
Cursor	cursor	@paperclipai/adapter-cursor-local
HTTP-Webhooks	HTTP-Adapter	benutzerdefinierter Endpunkt

Für Claude Code Agenten via CLI:

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

Der Agent wird gebootet, Skills in ~/.claude/skills installiert und API-Keys generiert. Er erscheint im Organigramm und kann Aufgaben übernehmen.

Beispiel-Konfiguration für Claude-Agenten:

Feld	Funktion
model	Zu nutzendes Claude-Modell (z.B. claude-sonnet-4-6)
cwd	Arbeitsverzeichnis (automatisch erstellt)
promptTemplate	System-Prompt mit {{variable}}-Platzhaltern
maxTurnsPerRun	Maximale Agent-Züge pro Heartbeat (Default: 300)
timeoutSec	Harte Ausführungslimitierung (0 = kein Timeout)

Modellwahl nach Rolle spart Kosten:

• CEO/Orchestrierung: Sonnet (teurer, aber strategisch)
• Manager: Haiku (günstig, delegiert und routet)
• ICs (codierend/kreativ): Sonnet (hohe Qualität)
• Routine-ICs: Haiku (Boilerplate, Tests, Migrations)

Damit sparst du 40–60% gegenüber Sonnet-only-Setups, ohne bei Routineaufgaben Qualität einzubüßen.

Agenten-Organisation strukturieren

Praktisches Beispiel für ein Softwareprojekt:

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

Der CEO hält die Mission und zerlegt sie in Ziele. CTO leitet an Engineering-Agenten weiter. Diese arbeiten ab, QA prüft, Technical Writer dokumentiert.

Jeder Agent besitzt ein Heartbeat-Intervall – wie oft er aufwacht, Aufgaben prüft und arbeitet. Agenten laufen nicht durchgehend, sondern werden periodisch aktiv. Das schont das Budget.

Empfohlene Heartbeat-Intervalle:

• Codierungsagenten: 600 Sekunden (10 Minuten)
• On-Demand-Agenten: 86.400 Sekunden (1x/Tag) mit Wake-on-Demand
• Absolutes Minimum: 30 Sekunden (darunter drohen Kostenexplosion & Spam)

Wie der Heartbeat funktioniert

Das Heartbeat-Modell ist zentral für zuverlässige Agentenarbeit.

Ablauf jedes Heartbeats (9 Schritte):

1. Identität per GET /api/agents/me prüfen
2. Anstehende Genehmigungen abarbeiten
3. Aufgaben via GET /api/companies/{companyId}/issues holen
4. Priorisieren (in Arbeit → To-Do, Blocker überspringen)
5. Aufgabe via POST /api/issues/{issueId}/checkout reservieren (bei 409: andere Agenten fahren fort)
6. Task-Kontext und Kommentarhistorie lesen
7. Arbeit erledigen
8. Aufgabe updaten (Kommentare, Status)
9. Unteraufgaben delegieren (mit Parent- und Ziel-IDs)

Durch den Checkout in Schritt 5 wird doppelte Arbeit verhindert: Pro Aufgabe immer nur ein Agent aktiv.

Kontext wird als Umgebungsvariablen injiziert:

PAPERCLIP_TASK_ID          # Auslösende Aufgabe
PAPERCLIP_WAKE_REASON      # Grund fürs Aufwachen (Timer, Erwähnung, Zuweisung)
PAPERCLIP_AGENT_ID         # Agenten-ID
PAPERCLIP_API_URL          # API-Endpunkt von Paperclip

Agenten nutzen diese Variablen für Updates, Subtasks, Genehmigungen und Delegation – alles im Rahmen eines Heartbeats.

Aufgaben zuweisen & Arbeit tracken

Aufgaben in Paperclip ähneln GitHub-Issues plus PM-Features. Erstelle via UI oder CLI:

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

Features von Aufgaben:

• Parent-Aufgaben für Task-Zerlegung
• Ziellinks für Ziel-Transparenz
• Kommentare für Kontext, Genehmigungen, Status
• @-Erwähnungen aktivieren Agenten sofort (ohne Heartbeat-Wartezeit)

Alle offenen Aufgaben via CLI listen:

paperclipai issue list

Oder direkt im Dashboard: Aufgaben zeigen Eigentümer, Status, letzten Heartbeat.

Budgetkontrolle, die wirklich funktioniert

Jeder Agent erhält ein monatliches Token-Budget. Bei 80% Budget nutzt der Agent nur noch kritische Aufgaben, bei 100% pausiert er komplett.

Budget in der Agentenkonfiguration setzen. Community-Empfehlung: 20–50 $/Monat pro Agenten-Tier. Verbrauch und Kosten pro Heartbeat siehst du im Dashboard.

Steigende Heartbeat-Kosten deuten meist auf vage Prompts oder unklare Aufgabenbereiche hin – nicht auf zu wenig Budget. Präzisiere die Aufgaben, statt das Limit zu erhöhen.

Paperclip verhindert Kostenexplosionen durch falsch konfigurierte Agenten (z.B. 30-Sekunden-Intervalle mit „Denken an“-Option).

Laufzeit-Skills: Workflows per Markdown beibringen

Skill-Injektion macht Agenten flexibel: Paperclip legt Symlinks zu SKILL.md-Dateien ins Agentenverzeichnis und übergibt sie als Kontext. Der Agent liest SKILL.md und folgt dem beschriebenen Workflow.

So bringst du einem Agenten neue Prozesse (z.B. Commit-Konventionen, Migrationsregeln, API-Dokumentation) per Markdown bei – ohne Prompt-Änderung oder Redeployment.

# 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

Lege die Datei im Skills-Verzeichnis ab, weise sie dem Backend-Agenten zu – ab sofort befolgt jeder Heartbeat diesen Ablauf.

APIs deiner Agenten testen

Entwickeln Agenten APIs, brauchst du schnelle Tests. Apidog ist dafür ideal: API-Design, Mockserver und automatisierte Tests an einem Ort. Wenn dein Backend-Agent einen Endpoint liefert, kannst du ihn sofort validieren – ohne zwischen Swagger, Postman und Mocktools zu wechseln.

Generiere Test-Suites automatisch aus deiner OpenAPI-Spezifikation, führe sie gegen die Agenten-Ausgabe aus und poste die Ergebnisse als Aufgabenkommentar zurück. Der Agent erkennt Fehler beim nächsten Heartbeat und korrigiert sie. Der gesamte Kreislauf – Code, Test, Fix – läuft automatisiert.

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

Mehrere Instanzen verwalten

Paperclip unterstützt isolierte Instanzen per PAPERCLIP_INSTANCE_ID oder --instance-Flag. Jede Instanz hat eigene Config, DB, Ports und Workspaces.

Für lokale Entwicklung generiert worktree:make eine eigene Instanz pro Git-Branch:

paperclipai worktree:make feature/orders-pagination

So entsteht für jeden Branch eine eigene Umgebung mit separaten Ports, Configs und Datenbank. Teste neue Features isoliert, ohne die Produktions-Agenten zu beeinflussen. Nach Abschluss: Instanz löschen, alles sauber.

Bewährte Multi-Agenten-Muster

• Zielkaskade: Übergeordnetes Unternehmensziel, CEO-Agent teilt es auf, Manager-Agenten leiten weiter. Agenten arbeiten besser, wenn sie den gesamten Zielpfad kennen.
• Genehmigungsschranken: Für produktionskritische Aktionen Genehmigung erzwingen. Agent pausiert, wartet auf Freigabe – schützt vor teuren Fehlern.
• On-Demand-Aktivierung via @-Erwähnung: Statt schnellem Heartbeat-Intervall Agenten auf langsam schalten und bei Bedarf via @-Kommentar sofort aktivieren. Spart Kosten, hält Reaktionszeiten kurz.
• Separater Workspace pro Agent: Jeder Agent nutzt workspaces/<agent-id>/. Gemeinsame Verzeichnisse vermeiden! Isolation ist Standard und verhindert Konflikte.

Der Einstieg: 15 Minuten bis zum produktiven Setup

Das Onboarding dauert ca. 15 Minuten: Ein Befehl installiert und startet den Server. Einen Agenten hinzufügen und erste Aufgabe anlegen – weitere fünf Minuten.

Wichtiger als die Technik ist die gute Struktur: Klare Mission, richtige Modellverteilung, sinnvolle Budgetgrenzen. Investiere ca. 30 Minuten in diese Planung, bevor du Aufgaben verteilst – das zahlt sich mehrfach aus.

Wenn du bereits mehr als zwei KI-Agenten im Projekt nutzt, lohnt sich ein Nachmittag für die Einrichtung. Der Unterschied zu einzelnen Terminal-Tabs: Budgetkontrolle, Verantwortlichkeiten und Audit-Logs machen dein Projekt vom Nebenjob zum produktiven, automatisierten Betrieb.