Membangun Skuad AI Multi-Agent: Pi + Herdr, dari Instalasi sampai Kerja Paralel dengan Git Worktree

Bayangkan sebuah “runtime” berisi beberapa AI coding agent yang saling ngobrol antar panel terminal — satu jadi pemimpin, satu eksekutor fitur, satu reviewer, satu perombak kode — semuanya bekerja paralel di worktree masing-masing tanpa saling injak. Artikel ini memandunya dari nol: install pi, konfigurasi, pasang skill, lalu merakit skuadnya dengan herdr.

Skuad contoh kita bertema Tensei Shitara Slime Datta Ken: Rimuru (koordinator), Raphael (analis/reviewer), Benimaru (eksekutor fitur), dan Veldora (perombak besar-besaran). Semuanya menjalankan pi.

1. Apa Itu Pi dan Herdr?

Pi (@earendil-works/pi-coding-agent) adalah coding agent berbasis terminal. Ia diberi empat alat dasar — read, write, edit, bash — dan bekerja langsung di direktori proyekmu. Sesi tersimpan otomatis, skill bisa dipasang, dan ia bisa berjalan interaktif maupun one-shot.

Herdr adalah terminal workspace manager untuk AI coding agent. Mirip tmux (server di latar belakang, pane tetap hidup walau kamu detach), tapi mouse-first dan agent-aware: herdr mendeteksi agent yang berjalan di tiap pane dan menampilkan statusnya di sidebar — working, blocked, done, idle, atau unknown. Yang paling penting untuk kita: herdr punya CLI (herdr agent ..., herdr pane ..., herdr worktree ...) sehingga agent bisa mengendalikan agent lain — inilah fondasi “saling ngobrol antar panel terminal”.

Hierarki konsep herdr (urutan belajar yang disarankan):

• Session — namespace server persisten. herdr attach ke session default; herdr session attach work membuat session bernama yang terpisah total.
• Workspace — kontainer level proyek, biasanya satu per repo/tugas.
• Tab — layout di dalam workspace (mis. tab agents, logs, server).
• Pane — terminal sungguhan. Bisa di-split kanan/bawah. Bertahan saat detach.
• Agent — proses yang dikenali herdr di dalam pane, lengkap dengan state lifecycle-nya.

2. Install Pi

Pi didistribusikan sebagai paket npm:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts menonaktifkan lifecycle script dependensi saat install — pi tidak membutuhkannya. Uninstall kapan saja dengan npm uninstall -g @earendil-works/pi-coding-agent (pengaturan dan sesi di ~/.pi/agent/ akan tetap tersimpan).

Jalankan di direktori proyek:

cd /path/to/project
pi

Autentikasi

Ada dua cara:

Opsi 1 — login langganan (Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot):

/login

lalu pilih provider.

Opsi 2 — API key lewat environment variable:

export ANTHROPIC_API_KEY=sk-ant-...
pi

atau simpan permanen lewat /login → pilih provider API-key (kunci disimpan di ~/.pi/agent/auth.json).

Sesi pertama

Summarize this repository and tell me how to run its checks.

Pi langsung bekerja dengan empat alat: read, write, edit, bash. Biasakan proyekmu di bawah git supaya mudah rollback.

3. Konfigurasi Pi

3.1 File pengaturan

Pi memakai JSON settings, dengan scope proyek menimpa global:

Edit manual atau lewat /settings di dalam pi. Default model dan thinking level bisa disimpan interaktif: /model lalu tekan Ctrl+S pada model yang dipilih, begitu juga /thinking.

Contoh isi ~/.pi/agent/settings.json:

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-5",
  "defaultThinkingLevel": "high",
  "theme": "dark",
  "enableSkillCommands": true
}

defaultProjectTrust (ask / always / never) mengatur bagaimana pi memperlakukan pengaturan lokal proyek saat dijalankan non-interaktif — relevan untuk skuad otomatis kita nanti.

3.2 Instruksi proyek: AGENTS.md

Pi memuat file konteks saat startup:

• ~/.pi/agent/AGENTS.md — instruksi global,
• AGENTS.md atau CLAUDE.md di direktori saat ini dan direktori induknya,
• AGENTS.override.md — jika ada, menimpa keduanya.

# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.

Setelah mengubah file konteks: restart pi atau jalankan /reload. Ini penting untuk skuad multi-agent — tulis aturan main di sini supaya semua anggota skuad berperilaku sama.

3.3 Mode non-interaktif (bekal untuk orkestrasi)

pi -p "Summarize this codebase"          # one-shot
cat README.md | pi -p "Summarize this"   # lewat stdin
pi -c                                    # lanjutkan sesi terakhir
pi --session <path|id>                   # buka sesi tertentu

4. Memasang Skill

Skill adalah paket kapabilitas yang dimuat on-demand (progressive disclosure): hanya nama + deskripsinya yang selalu ada di konteks; isi lengkap SKILL.md baru dibaca saat tugasnya cocok. Pi mengimplementasikan standar Agent Skills.

4.1 Lokasi skill

• Global: ~/.pi/agent/skills/ dan ~/.agents/skills/
• Proyek (setelah proyek di-trust): .pi/skills/ dan .agents/skills/
• Dari package: folder skills/ atau entri pi.skills di package.json
• Settings: array skills berisi file/direktori
• CLI: --skill <path> (bisa diulang)

Struktur minimal sebuah skill:

my-skill/
├── SKILL.md       # wajib: frontmatter + instruksi
├── scripts/       # skrip pembantu (opsional)
└── references/    # dokumen detail, dimuat on-demand (opsional)

dengan frontmatter:

---
name: my-skill
description: What this skill does and when to use it. Be specific.
---

4.2 Install lewat pi packages (npm / git)

pi install npm:@foo/[email protected]          # dari npm
pi install git:github.com/user/repo@v1 # dari git, ref terpin
pi install ./relative/path             # dari path lokal
pi list                                # lihat paket terpasang
pi update --all                        # update pi + semua paket

Paket user masuk ke ~/.pi/agent/npm/ (npm) atau ~/.pi/agent/git/ (git). Tambahkan -l untuk menulis ke settings proyek, bukan settings user. Mau coba tanpa install permanen? Pakai pi -e npm:@foo/bar.

4.3 Install skill lintas-harness dengan npx skills

Untuk skill yang mengikuti open skills CLI (termasuk skill resmi herdr):

npx skills add herdrdev/herdr --skill herdr -g

4.4 Membuat skill sendiri

Buat direktori berisi SKILL.md, taruh di ~/.pi/agent/skills/, selesai. Deskripsi menentukan kapan agent memakainya — buat spesifik:

# Bagus
description: Extracts text from PDF files and merges multiple PDFs. Use when working with PDF documents.

# Buruk
description: Helps with PDFs.

Skill yang sudah terpasang bisa dipanggil manual sebagai slash command /skill:nama (aktifkan "enableSkillCommands": true di settings).

Skill paling penting untuk artikel ini: skill herdr. Ia mengajarkan pi mengendalikan herdr dari dalam pane — split pane, membaca output pane lain, mengirim prompt ke agent lain, dan menunggu state-nya.

5. Install Herdr

Linux/macOS:

curl -fsSL https://herdr.dev/install.sh | sh
herdr

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

Jalankan pertama kali:

cd /path/to/project
herdr

Herdr akan launch/attach ke session default dan membuat workspace otomatis. Pertama kali muncul onboarding flow. Channel update: herdr update, atau pindah ke preview dengan herdr channel set preview.

Konfigurasi herdr

• File konfigurasi: ~/.config/herdr/config.toml (Linux/macOS) — opsional, herdr jalan tanpanya.
• Cetak konfigurasi default lengkap: herdr --default-config.
• Terapkan perubahan ke server yang sedang jalan: herdr server reload-config.
• Area utama: [keys] keybinding, [theme] tema, [ui] sidebar, [terminal] default shell, [update] channel.

Navigasi dasar: mouse-first — klik pane/tab untuk fokus, drag border untuk split, klik kanan untuk menu, drag-select untuk copy. Keyboard datang belakangan: prefix Ctrl+B, lalu prefix+? menampilkan semua binding aktif. Split pane: prefix+v (kanan) / prefix+minus (bawah). Tab baru: prefix+c. Detach: prefix+q — semua tetap berjalan, dan herdr lagi untuk reattach.

6. Merakit Skuad: Rimuru, Raphael, Benimaru, Veldora

Sekarang bagian serunya: beberapa instance pi berjalan paralel, masing-masing punya nama dan peran. Aturan penamaan agent herdr: [a-z][a-z0-9_-]{0,31}, unik di antara agent yang hidup — rimuru, veldora, raphael, benimaru semuanya valid.

Pembagian peran contoh:

6.1 Spawn agent dari dalam herdr (skill herdr di pi)

Pastikan kamu menjalankan pi di dalam pane herdr (HERDR_ENV=1). Dengan skill herdr terpasang, cukup bilang ke Rimuru:

“Spawn Raphael, Benimaru, dan Veldora di pane sebelah, masing-masing menjalankan pi.”

Secara manual, urutannya begini:

# 1) Pastikan kita di dalam herdr
test "${HERDR_ENV:-}" = 1 && echo "di dalam herdr"

# 2) Split pane baru tanpa mencuri fokus, pertahankan cwd
herdr pane split --current --direction right --cwd "$PWD" --no-focus
# → baca pane_id dari JSON .result.pane.pane_id, mis. w1:p2

# 3) Jalankan pi di pane itu dengan nama unik
herdr agent start raphael --kind pi --pane w1:p2

# 4) Ulangi untuk anggota lain
herdr pane split --current --direction right --cwd "$PWD" --no-focus
herdr agent start benimaru --kind pi --pane w1:p3

herdr pane split --current --direction down --cwd "$PWD" --no-focus
herdr agent start veldora --kind pi --pane w1:p4

herdr agent start baru kembali setelah herdr mendeteksi pi di pane tersebut dan siap menerima input (timeout default 30 detik). Jenis agent yang didukung tidak cuma pi — ada claude, codex, gemini, cursor, copilot, dan banyak lagi.

Cek formasi:

herdr agent list
herdr agent get raphael
herdr agent focus raphael

Sidebar herdr akan menampilkan state tiap anggota: working, blocked, done, atau idle.

7. Saling Ngobrol Antar Panel Terminal

Inilah inti “runtime multi-agent”: agent di satu pane bisa mengirim prompt, membaca output, dan menunggu agent di pane lain lewat CLI herdr.

7.1 Kirim prompt dan tunggu selesai

herdr agent prompt raphael \
  "Review diff di branch feat/auth. Laporkan hanya temuan yang actionable." \
  --wait --timeout 120000

--wait menunggu state idle, done, atau blocked pertama setelah prompt terkirim. Kalau agent sudah blocked (menunggu approval/pertanyaan), prompt ditolak dengan agent_blocked sebelum input apa pun dikirim — periksa dulu UI-nya dengan agent read.

7.2 Membaca jawaban agent lain

herdr agent read raphael --source recent-unwrapped --lines 120

Pilihan source:

• visible — viewport yang sedang dirender,
• recent — output terbaru termasuk soft wrap,
• recent-unwrapped — output terbaru dengan soft wrap disatukan (terbaik untuk log/transkrip),
• detection — snapshot teks polos untuk deteksi agent.

7.3 Menunggu event tertentu

herdr agent wait veldora --until blocked --timeout 120000
herdr agent wait benimaru --until done

7.4 Mengirim tombol

herdr agent send-keys raphael esc
herdr agent send-keys raphael ctrl+c

7.5 Pola orkestrasi Rimuru

Dengan skill herdr, Rimuru bisa menjalankan alur seperti ini sepenuhnya sendiri:

1. Terima tugas: “Tambahkan fitur login dan rapikan modul auth lama.”

2. Rimuru membuat worktree untuk tiap sub-tugas (bab berikutnya).

3. Rimuru mengirim prompt ke Benimaru (fitur login) dan Veldora (refactor modul auth) di worktree masing-masing:

   herdr agent prompt benimaru "Implementasikan login dengan OAuth..." --wait
   herdr agent prompt veldora  "Refactor modul auth lama ke struktur baru..." --wait

4. Saat keduanya selesai, Rimuru menyuruh Raphael me-review:

   herdr agent prompt raphael "Review gabungan diff dari branch feat/login dan refactor/auth..." --wait

5. Rimuru membaca hasilnya (agent read), merangkum, dan melapor ke kamu.

Kelebihan besar pola ini: setiap prompt antar-agent terverifikasi — herdr menolak mengirim ke agent yang sedang blocked, dan agent prompt --wait punya deteksi stall (agent_prompt_stalled) sehingga orkestrator tidak menunggu tanpa ujung.

8. Kerja Paralel Tanpa Konflik: Git Worktree

Masalah klasik multi-agent: dua agent mengedit checkout yang sama = konflik. Solusinya git worktree — setiap agent mendapat checkout dan branch sendiri dari repo yang sama. Herdr menyediakan helper khusus:

herdr worktree list
herdr worktree create --help

Contoh membuat worktree untuk Benimaru dan Veldora:

# Worktree fitur login → workspace + checkout baru
herdr worktree create --cwd "$PWD" --branch feat/login --base main --label "login-benimaru"

# Worktree refactor auth
herdr worktree create --cwd "$PWD" --branch refactor/auth --base main --label "auth-veldora"

herdr worktree create membuat worktree git sekaligus membuka workspace herdr di atasnya — setiap anggota skuad kini punya “kamar” sendiri:

founderplus-mono (main)          ← Rimuru + Raphael (koordinasi & review)
founderplus-mono-feat-login      ← Benimaru
founderplus-mono-refactor-auth   ← Veldora

Setelah pekerjaan selesai, merge seperti biasa (git merge / pull request), lalu bersihkan dengan herdr worktree remove.

Alur lengkap skuad dengan worktree:

Kamu → Rimuru
        ├─ worktree create feat/login      → spawn Benimaru → prompt → wait
        ├─ worktree create refactor/auth   → spawn Veldora  → prompt → wait
        ├─ agent read keduanya, kumpulkan ringkasan
        └─ prompt Raphael (review silang kedua diff) → laporkan hasil akhir

Karena tiap agent bekerja di branch berbeda, mereka benar-benar paralel: tidak ada lock file yang bertabrakan, tidak ada git status yang saling mengotori.

9. Resep Operasional & Troubleshooting

Klik untuk membuka tiap resep:

herdr agent list
herdr agent explain raphael --json
herdr integration status

herdr status
herdr status server
herdr status client

10. Ringkasan

Dokumentasi resmi:

• Pi: README + docs/ paket @earendil-works/pi-coding-agent (quickstart, skills, packages, settings)
• Herdr: https://herdr.dev/docs/ — concepts, agents, integrations, CLI reference, socket API

Dengan fondasi ini, satu perintah ke Rimuru bisa berujung pada tiga agent bekerja serentak di tiga worktree, saling mengirim hasil lewat herdr agent prompt, dan berakhir dengan laporan review dari Raphael — terminal kamu resmi jadi markas skuad slime. 🟦⚔️🐉