Paperclip: Alat Gratis yang Mengubah Agen AI Menjadi Tim Software

Sebagian besar pengembang yang menjalankan banyak agen AI akan mengalami masalah yang sama setelah agen kelima. Anda punya Claude Code di satu terminal untuk menulis ulang backend, Codex di terminal lain untuk generate testing, Cursor yang mengedit komponen, dan tiga tab lain yang lupa dicek—semua bekerja sendiri-sendiri, biaya membengkak, pekerjaan dobel, dan tidak ada tujuan jelas yang tersampaikan ke tiap agen.

Coba Apidog hari ini

Paperclip adalah solusi untuk masalah itu. Paperclip adalah platform orkestrasi open source yang mengubah agen-agen AI Anda menjadi organisasi terstruktur—dengan bagan organisasi, peran, manajemen tugas, batas anggaran, dan audit log. Dalam waktu kurang dari tiga minggu, Paperclip sudah mendapatkan 35.000+ bintang GitHub—bukti banyak dev yang punya masalah sama.

Artikel ini membahas cara setup, membuat perusahaan agen pertama, dan menjalankannya agar pekerjaan selesai otomatis tanpa harus mantengin terminal terus.

Apa itu Paperclip (dan Bukan)

Sebelum install, pahami dulu apa yang akan Anda dapatkan.

Paperclip adalah lapisan orkestrasi. Ia mengoordinasi agen, memonitor pekerjaan, mengontrol anggaran, dan memberi konteks tujuan perusahaan. Bukan alat untuk membangun agen baru, bukan pengganti provider AI Anda, dan bukan UI chat.

Model mental Paperclip: "Jika Claude Code adalah karyawan, Paperclip adalah perusahaannya."

Artinya:

• Agen punya peran (bukan sekadar prompt)
• Tugas punya pemilik (bukan sekadar terminal)
• Anggaran punya batas keras
• Semua tercatat di audit log

Paperclip kompatibel dengan Claude Code, OpenAI Codex, Cursor, Gemini CLI, dan agen mana pun yang bisa menerima webhook atau heartbeat. Anda bawa agennya, Paperclip jadi sistem organisasinya.

Bukan untuk:

• Chatbot UI
• Workflow builder drag-n-drop kayak n8n/Zapier
• Framework penulisan agen
• Single agent use-case

Kalau hanya pakai satu agen AI, Paperclip terlalu kompleks. Tapi kalau sudah tiga atau lebih, ini alat yang Anda butuhkan.

Instalasi Paperclip

Prasyarat: Node.js 20+, pnpm 9.15+. Tidak perlu eksternal DB; Paperclip sudah include embedded PostgreSQL.

Cara tercepat:

npx paperclipai onboard --yes

Ini auto-download CLI, jalankan onboarding, dan start server di port 3100. Buka http://127.0.0.1:3100 untuk dashboard.

Untuk kontribusi atau eksplorasi kode:

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

Atau via Docker:

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

Struktur file di disk:

~/.paperclip/instances/default/
  config.json          — setting server & storage
  db/                  — file data PostgreSQL embedded
  secrets/master.key   — kunci enkripsi
  logs/                — log server
  data/storage/        — file attachment
  workspaces/<agent>/  — direktori kerja per agen

Mode lokal default pakai auth local_trusted, jadi Anda langsung akses dashboard tanpa buat akun.

Cek kesehatan setup:

paperclipai doctor

Jika ada masalah:

paperclipai doctor --repair

Mendirikan Perusahaan Pertama

"Perusahaan" di Paperclip = wadah utama untuk agen, tugas, tujuan, dan anggaran. Dari dashboard, buat perusahaan baru dan isi mission statement. Ini sangat penting, karena setiap tugas akan punya konteks "mengapa", bukan sekadar "apa".

Contoh misi:

Membangun dan memelihara REST API untuk manajemen pesanan pelanggan. Prioritaskan kebenaran daripada kecepatan. Dokumentasikan setiap endpoint publik.

Statement ini jadi filter keputusan tiap agen.

Menambahkan Agen Pertama

Setiap agen di Paperclip pakai adapter untuk menentukan AI tool & cara komunikasi.

Adapter yang didukung:

Agen	Jenis Adapter	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	Adapter HTTP	endpoint custom

Tambah agen Claude Code via CLI:

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

Agen akan terinstal, termasuk skill di ~/.claude/skills, dan dapat kredensial API. Agen langsung muncul di org chart dan siap terima tugas.

Konfigurasi Agen Claude: (UI atau file config)
| Bidang | Fungsi |
|----------------------|------------------------------------------------------------------|
| model | Model Claude yang digunakan (misal: claude-sonnet-4-6) |
| cwd | Direktori kerja untuk agen |
| promptTemplate | Prompt sistem, bisa pakai {{variable}} |
| maxTurnsPerRun | Maks giliran per heartbeat (default: 300) |
| timeoutSec | Batas eksekusi (0 = no limit) |

Alokasi model per peran (hemat biaya):

• CEO/Orkestrator: Sonnet (strategis)
• Manager: Haiku (routing/delegasi)
• IC kreatif/koding: Sonnet (butuh kualitas)
• IC rutin: Haiku (boilerplate, migrasi)

Dengan ini, pengeluaran bulanan bisa turun 40-60% tanpa kehilangan kualitas.

Menyusun Organisasi Agen

Struktur tim proyek kecil (contoh):

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

CEO pegang misi, CTO bagi tugas ke engineer, engineer eksekusi, QA validasi, writer dokumentasi.

Setiap agen punya heartbeat interval: frekuensi bangun, cek tugas, kerja, lalu tidur lagi.

Rekomendasi interval:

• Agen coding: 600 detik (10 menit)
• Agen on-demand: 86400 detik (1 hari) + wake-on-demand
• Minimum aman: 30 detik (lebih rendah = biaya membengkak)

Cara Kerja Heartbeat

Setiap heartbeat, agen jalankan 9 langkah:

1. Konfirmasi identitas (GET /api/agents/me)
2. Tangani callback approval tertunda
3. Ambil tugas (GET /api/companies/{companyId}/issues)
4. Prioritas: ongoing > todo; skip blocked
5. Checkout tugas (POST /api/issues/{issueId}/checkout) (kalau sudah diambil agen lain, lanjut tugas lain)
6. Baca konteks & thread komentar
7. Kerjakan tugas
8. Update tugas dengan komentar/status
9. Delegasi subtugas jika perlu

Checkout (step 5) mencegah tugas dobel. Paperclip juga inject env vars:

PAPERCLIP_TASK_ID          # tugas trigger
PAPERCLIP_WAKE_REASON      # alasan bangun (timer, mention, assignment)
PAPERCLIP_AGENT_ID         # id agen
PAPERCLIP_API_URL          # endpoint API Paperclip

Agen bisa update status, buat subtugas, request approval, dst dalam satu heartbeat.

Menugaskan dan Melacak Tugas

Tugas Paperclip seperti GitHub Issue + project management.

Buat tugas via CLI:

paperclipai issue create \
  --company-id <id> \
  --title "Tambahkan penomoran halaman ke endpoint pesanan" \
  --assignee-agent-id <backend-engineer-id>

Tugas bisa punya:

• Tugas induk (breakdown)
• Goal link (konteks perusahaan)
• Komentar (status/approval)
• @-mention (bangunkan agen on-demand)

Lihat semua tugas:

paperclipai issue list

Atau lewat dashboard, lengkap dengan owner, status, dan heartbeat terakhir.

Kontrol Anggaran yang Efektif

Setiap agen dapat anggaran token bulanan. 80% tercapai: switch ke tugas kritis. 100%: stop.

Set anggaran di konfigurasi agen. Rekomendasi: $20-50/bulan per level agen. Lacak burn rate, biaya/heartbeat, dan total pengeluaran di dashboard.

Jika biaya/heartbeat naik, biasanya prompt terlalu luas atau tugas kurang jelas—solusi: perbaiki assignment, bukan tambah anggaran.

Tanpa kontrol, agen yang salah setting bisa habiskan ratusan dolar tanpa disadari. Paperclip otomatis cegah hal itu.

Keterampilan Runtime: Ajari Agen Alur Kerja Baru

Skill injection memungkinkan Anda tambahkan workflow baru ke agen hanya dengan file markdown.

Contoh SKILL.md:

# KETERAMPILAN: Migrasi database

Saat membuat migrasi:
1. Jangan pernah ubah file migrasi lama
2. Nama file: YYYYMMDD_deskripsi.sql
3. Sertakan SQL naik & turun
4. Uji lokal sebelum commit
5. Tambahkan komentar alasan bisnis

Simpan ke folder skill, assign ke agen backend, dan workflow baru langsung berlaku pada heartbeat berikutnya—tanpa retrain/prompt rewrite.

Jika Anda Menguji API Hasil Agen

Saat agen membangun API, Anda butuh testing cepat. Apidog sangat cocok: desain API, mock server, dan automated testing dalam satu tool. Endpoint dari agen backend bisa langsung divalidasi tanpa gonta-ganti Swagger, Postman, dsb.

Generate suite test otomatis dari spesifikasi OpenAPI, jalankan ke hasil agen, dan kirim hasilnya kembali sebagai komentar tugas. Agen baca di heartbeat berikutnya dan perbaiki gagal test secara otomatis.

Apidog mendukung REST, GraphQL, gRPC, dan bisa dipakai gratis.

Mengelola Banyak Instance

Paperclip mendukung multi-instance di satu mesin via env var PAPERCLIP_INSTANCE_ID atau flag --instance. Setiap instance punya config, DB, port, dan workspace sendiri.

Untuk development, fitur worktree membuat instance dev per branch git:

paperclipai worktree:make feature/orders-pagination

Setiap branch dapat instance, port, dan DB terpisah—uji fitur tanpa ganggu agen produksi. Selesai? Destroy, clean.

Pola Multi-Agen yang Terbukti Efektif

Beberapa pola yang terbukti ampuh:

• Cascading goal: Satu goal utama di perusahaan, CEO agen breakdown ke project, manager agen breakdown ke tugas. Agen kerja lebih baik jika paham rantai goal.
• Approval gate: Untuk action ke production/staging/billing, set approval gate. Agen stop, Anda approve dulu, baru lanjut.
• On-demand via @-mention: Set interval heartbeat lambat, pakai @-mention untuk bangunkan agen kalau perlu—respons cepat tanpa biaya polling tinggi.
• Isolasi workspace: Setiap agen di folder sendiri (workspaces/<agent-id>/). Jangan share workspace antar agen untuk cegah konflik.

Setup 15 Menit, Hasil Nyata

Setup awal Paperclip kurang dari 15 menit: install & start server, tambah agen, buat tugas—semua bisa dari dashboard.

Bagian tersulit: susun struktur perusahaan, tulis misi jelas, pilih model tiap peran, set anggaran tepat. Investasikan 30 menit di sini; hasilnya jauh lebih baik daripada setup asal-asalan.

Jika Anda sudah jalan lebih dari dua agen AI di satu proyek, habiskan waktu satu sore untuk setup Paperclip. Bedanya sangat terasa: dari proyek kecil jadi sistem otonom dengan kontrol anggaran, ownership tugas, dan audit log—bisa jalan sendiri tanpa pengawasan.