Agen CLI

Jika Anda sudah memakai Claude Code atau Codex, Anda bisa menjalankannya di dalam Perch. Pilih salah satunya di pemilih model, berikan sebuah folder, dan agen itu bekerja di sana dengan tool-nya sendiri, memakai login Anda sendiri. Chat Perch dan agen Anda berada di satu sidebar, sehingga Anda bisa memantau semuanya dari satu tempat.

Setiap agen bekerja di salinan tersendiri dari repo Anda, di branch-nya sendiri, sehingga beberapa agen bisa bekerja sekaligus tanpa menyentuh checkout Anda. Saat salah satunya selesai, Anda melihat apa yang diubahnya lalu me-merge perubahan itu ke folder Anda dengan satu klik, atau membuka pull request.

Sebelum memulai

• Perch Desktop 2.5.4 atau lebih baru, dalam keadaan masuk ke akun Pro atau Ultra. Agen CLI tidak tersedia di Perch di web.
• Claude Code atau Codex terpasang di komputer ini dan sudah masuk. Jika claude atau codex berjalan di terminal Anda, Perch dapat memulainya. Perch memakai instalasi dan login Anda, dan tidak menyertakan Claude Code maupun Codex.
• Git. Di Windows, pasang Git for Windows. Merge memerlukan git 2.40 atau lebih baru.
• Folder yang sudah Anda tambahkan ke Perch dan berada di repositori git dengan setidaknya satu commit, agar agen bisa memiliki salinannya sendiri.

Memulai agen

Bilah chat menampilkan apa yang sedang dikerjakan agen, nama agen, folder, dan branch-nya, misalnya agent/add-a-dark-mode-toggle-t-7q2m.

Sebuah chat tetap memakai agen yang dipakai saat chat itu dimulai. Untuk kembali ke model milik Perch sendiri, mulai chat baru.

Selama agen bekerja

• Permintaan persetujuan datang kepada Anda. Saat agen meminta izin untuk sesuatu, sebuah kartu bertuliskan Claude asks to go ahead muncul dengan pilihan yang ditawarkan agen.
• Mode mengatur mode milik agen itu sendiri, sama seperti yang ada di CLI-nya, misalnya Accept edits untuk Claude.
• Kirim pesan lanjutan kapan saja. Selama agen bekerja, pesan yang Anda kirim menunggu dan terkirim saat giliran berakhir. Anda dapat melampirkan gambar PNG, JPEG, GIF, atau WebP hingga 5 MB per gambar.
• Diff membuka panel Changes yang berisi setiap file yang telah diubah agen di salinannya.
• Open terminal membuka terminal di samping chat, di salinan repo milik agen.
• Jalankan beberapa sekaligus. Hingga empat agen dapat berjalan pada saat yang sama, masing-masing di salinannya sendiri. Sidebar menunjukkan agen mana yang sedang bekerja.

Salinan tersendiri dari repo Anda

Secara default, setiap agen bekerja di git worktree: checkout kedua dari repo Anda, di folder tersendiri, di branch tersendiri. Folder Anda, branch-nya, dan apa pun yang belum Anda commit tetap seperti semula selama agen bekerja, dan dua agen tidak pernah mengedit file yang sama.

Worktree hanya berisi file yang dilacak git. Perch juga membawa apa yang dibutuhkan sebagian besar proyek untuk berjalan:

• File konfigurasi lokal. File .env dan .env.*, di kedalaman mana pun, disalin jika git mengabaikannya. Untuk menyalin file lain yang diabaikan, seperti pengaturan lokal atau sertifikat, cantumkan file tersebut dalam file .worktreeinclude di root repo, dengan sintaks .gitignore. Sebuah file hanya disalin jika git juga mengabaikannya di salinan, sehingga file itu tidak pernah masuk ke commit. Paling banyak 200 file, masing-masing hingga 10 MB, dan total 50 MB. Symlink dilewati.
• Copy node_modules, di bawah Options di macOS, membuat clone node_modules Anda di dalam salinan. Ini adalah clone copy-on-write: hampir instan, tanpa ruang disk tambahan.
• Setup command, di bawah Options, menjalankan perintah seperti npm install di salinan sebelum agen mulai, di shell Anda (PowerShell di Windows). Perch mengingatnya untuk repo tersebut. Jika perintah itu gagal, atau berjalan lebih dari 15 menit, agen tetap dimulai dan chat memberitahukannya. Setup log di bilah chat menampilkan output-nya.

Options juga berisi Worktree folder, tempat salinan dibuat, dan Account folder: jika Anda punya beberapa login Claude Code atau Codex, pilih folder milik login yang ingin dipakai. Keduanya harus berada di dalam folder home Anda.

Matikan Worktree agar agen bekerja langsung di folder Anda. Perubahannya kemudian masuk ke folder Anda saat agen membuatnya, dan tidak ada langkah diff atau merge.

Membawa hasil kerja kembali

Saat sebuah giliran mengubah file, sebuah kartu di bawah percakapan memberitahukannya, misalnya: "Claude changed 4 files in its own copy of perch-app. They're not in your folder yet." Bilah chat terus menampilkan jumlahnya sampai Anda membawa perubahan itu kembali. Review changes membuka diff-nya.

Merge ke branch Anda

Merge into main, yang namanya mengikuti branch tempat folder Anda berada, menaruh semua perubahan agen di branch Anda sebagai satu commit. Pesan commit awalnya berisi judul chat, dan Anda bisa mengeditnya. Setelahnya, Remove the copy menghapus worktree dan branch milik agen.

Perch tidak pernah melakukan stash, reset, atau menimpa apa pun di folder Anda untuk merge. Sebagai gantinya, Perch berhenti dan memberi tahu Anda saat:

• Folder Anda memiliki perubahan yang belum di-commit. Commit dulu perubahan itu, lalu merge.
• File yang sama berubah di branch Anda dan di salinan agen. Ask Claude to fix mengirim pesan kepada agen untuk membereskannya di salinannya. Setelah agen selesai, merge lagi.
• Folder Anda tidak berada di sebuah branch, atau versi git lebih lama dari 2.40.

Cara lain untuk menyelesaikan

Menu di samping tombol merge berisi dua pilihan lagi:

• Commit only melakukan commit perubahan di branch milik agen sendiri. Folder Anda tidak berubah.
• Open pull request melakukan push branch agen ke origin dan membuka pull request. Jika GitHub CLI (gh) terpasang, Perch membukanya untuk Anda. Tanpa itu, Perch membuka halaman GitHub untuk pull request baru. Untuk host git lain, Perch melakukan push branch tersebut, dan Anda membuka pull request di sana.

Menutup chat

Jika Anda menutup chat yang salinannya masih memiliki perubahan yang belum ada di folder Anda, Perch bertanya terlebih dahulu: Merge first, Keep the copy (worktree dan branch-nya tetap di tempatnya), atau Discard (menghapus salinan beserta branch-nya, termasuk perubahannya).

Paket Anda sendiri

Agen CLI berjalan dengan login Claude Code atau Codex Anda sendiri, sehingga penggunaannya dihitung ke paket tersebut, bukan ke penggunaan Perch Anda. Pesan kepada agen-agen itu tidak memakai penggunaan yang sudah termasuk di paket Perch Anda.

Perch menampilkan batas milik masing-masing agen sesuai yang dilaporkan agen itu, yaitu 5-hour limit dan Weekly limit, beserta kapan masing-masing direset. Anda bisa menemukannya di kartu agen di pemilih model dan di Settings › Usage di bawah On this computer, dan sebuah catatan di atas kotak pesan memperingatkan Anda saat sebuah agen hampir mencapai batasnya. Batas ini muncul setelah balasan pertama agen di komputer ini.

Privasi

• Chat tetap di komputer ini. Chat agen CLI tidak disimpan ke akun Perch Anda, sehingga tidak muncul di Perch di web atau di ponsel Anda.
• Agen berkomunikasi dengan layanannya sendiri. Pesan Anda dikirim dari Claude Code ke Anthropic, atau dari Codex ke OpenAI, sama seperti saat Anda sendiri memakai CLI tersebut. Pesan itu tidak melewati server Perch.
• Setiap agen hanya mendapatkan apa yang dibutuhkannya. Perch memulainya dengan daftar singkat variabel lingkungan Anda: tanpa kunci agen lain dan tanpa apa pun milik Perch.

Dengan subsesi

Perch dapat menyerahkan sebagian pekerjaan kepada Claude Code atau Codex. Sampaikan permintaan Anda, misalnya "minta Codex memperbaiki tes yang flaky di sesinya sendiri", dan Perch menyarankan subsesi yang berjalan di agen tersebut, di worktree baru dari folder chat itu. Seperti subsesi lainnya, subsesi ini hanya dimulai saat Anda memilih Start, dan melapor kembali ke chat yang memulainya. Permintaan persetujuan agen tetap datang kepada Anda.

Pemecahan masalah

Saya tidak melihat On this computer di pemilih model. Pastikan Anda masuk ke akun Pro atau Ultra di Perch Desktop 2.5.4 atau lebih baru.

Sebuah agen menampilkan Not installed. Pasang agen itu agar claude atau codex ada di PATH Anda, lalu keluar dari Perch dan buka kembali.

Agen menampilkan Needs sign-in. Pilih Sign in in a terminal, yang menjalankan claude atau codex login untuk Anda. Selesaikan proses masuk, lalu pilih Try again.

Agen menyatakan CLI-nya lebih lama dari yang dibutuhkan Perch. Perbarui CLI tersebut. Untuk Claude Code, jalankan claude update. Perbarui Codex dengan cara yang sama seperti saat Anda memasangnya, dengan npm atau Homebrew.

Agen menyatakan butuh Node 22. Pesan itu berasal dari build desktop sebelum 2.5.4. Perbarui Perch Desktop, yang menjalankan agen tanpa Node.

Folder tidak bisa memiliki worktree. Folder itu harus berada di repositori git dengan setidaknya satu commit. Anda juga bisa mematikan Worktree.

Di Windows, salinan tidak bisa dihapus. Ada file di dalamnya yang sedang terbuka di program lain. Tutup file itu, lalu coba lagi.