AI
Background Agent Claude Code: Model Supervisor-nya
Agustus 202613 menit baca
Ada tiga cara: claude agents membuka UI pengelolaan dan mengirim tugas dari sana, claude --bg dengan sebuah prompt mengirim dari shell mana pun, dan /bg atau /fork memindahkan maupun menyalin percakapan yang sedang hidup ke background. Sesinya bertahan bahkan setelah Anda menutup agent view atau terminal, karena sebuah proses supervisor yang menampungnya, bukan shell Anda.
Sebuah proses per pengguna yang menampung setiap sesi background. Ia menyala otomatis pada pengiriman background pertama Anda, menyimpan worker yang sudah dipanaskan agar pengiriman cepat, bertahan melewati auto-update dengan memulai ulang ke versi baru, menghentikan sesi idle tanpa pin setelah sekitar satu jam, dan menghidupkan kembali proses yang berhenti ketika Anda attach atau membalas.
Tidak pada file. Sebelum mengedit, tiap sesi background berpindah ke git worktree-nya sendiri di bawah .claude/worktrees/ supaya sesi paralel tidak bertabrakan. Isolasinya dilewati ketika Anda sudah berada di worktree tertaut, di luar repository git, atau menulis di luar working directory, dan ia bisa dimatikan lewat setting worktree bgIsolation.
Supervisor mewarisi environment dari shell mana pun yang pertama menyalakannya, dan supervisor yang dipasang OS sama sekali tidak mendapat environment shell. Variabel yang hanya di-export di shell Anda akan sampai ke background agent ketika shell itu kebetulan menyalakan supervisor dari dingin, dan diam-diam tidak sampai bila tidak. Letakkan di blok env sebuah file setting.
Rate limit berlaku per akun, jadi sepuluh sesi paralel menghabiskan kira-kira sepuluh kali kuota — tidak ada anggaran terpisah untuk pekerjaan background. Paralelismenya juga lokal: sesi berjalan di mesin Anda dan berhenti ketika mesinnya mati. Untuk pekerjaan yang harus hidup lebih lama dari mesinnya, pakai sesi cloud atau routine.
Ringkasan Utama
Sesi background Claude Code berjalan tanpa terminal yang menempel, ditampung sebuah proses supervisor per pengguna yang bertahan melewati auto-update dan hidup lebih lama daripada shell yang memulainya. Sebelum mengedit file, tiap sesi berpindah ke git worktree-nya sendiri supaya sesi paralel tidak bertabrakan. Sepuluh sesi paralel menghabiskan kira-kira sepuluh kali kuota.
Saya mengirim empat sesi background, menutup terminalnya, lalu kembali dan menemukan keempatnya masih bekerja. Itu memang intinya, dan tetap sedikit mengejutkan. Yang memungkinkannya adalah sebuah proses yang keberadaannya tidak saya ketahui: supervisor yang menyala pada pengiriman background pertama saya, mengambil alih kepemilikan setiap sesi, dan tidak punya hubungan apa pun dengan terminal yang kebetulan saya pakai untuk meluncurkannya.
Hampir setiap perilaku tak kentara di sini mengikuti dari arsitektur tersebut, termasuk satu yang sudah pernah menggigit saya di konteks yang sama sekali berbeda. Tulisan ini membahas cara-cara mengirim tugas, supervisor dan apa yang diwarisinya, isolasi worktree yang membuat paralelismenya aman, apa yang selamat ketika Anda memindahkan sesi ke background, dan biaya jujur menjalankan sepuluh agent sekaligus.
Ada UI pengelolaan dan ada shell, dan keduanya menjangkau hal yang sama. Perbedaan yang layak dipahami sejak awal adalah antara dua cara mendorong percakapan yang sedang hidup ke background, karena salah satunya meninggalkan Anda tanpa apa pun di depan mata.
# Three ways to start work that outlives your terminal.
claude agents # the full-terminal management UI
claude --bg "investigate the flaky test"
claude --bg --name "test-fix" --model opus "..."
claude --bg --exec 'pytest -x' # a SHELL job, not a Claude session
# From inside an interactive session:
/bg <prompt> # MOVE this conversation to the background
/fork <prompt> # COPY it to the background and keep working here
← # background and return to agent view
# Inside agent view, the dispatch line understands:
# <agent-name> <prompt> run a custom subagent
# @<agent-name> mention a subagent anywhere
# @<repo> dispatch to a specific directory
# ! <command> run a shell job
# #<number> or a PR URL attach to the session on that PR
# Shift+Enter dispatch AND attach immediatelyBackgrounding memindahkan percakapannya — terminal Anda bebas dan pekerjaannya berlanjut di tempat lain. Fork menyalinnya, jadi sesi background membawa konteksnya dan Anda tetap memegang percakapan yang sedang Anda kerjakan. Fork hampir selalu yang Anda inginkan ketika Anda sedang di tengah investigasi dan ingin satu tugas sampingan dijalankan tanpa kehilangan posisi.
Satu proses supervisor per pengguna menampung setiap sesi background, dan ia berperilaku lebih seperti sebuah service daripada job shell:
Supervisor mewarisi environment dari shell mana pun yang pertama menyalakannya, dan itu fakta struktural yang sama yang membuat variabel proxy dan sertifikat hasil export shell tidak andal bagi background agent. Itu juga berarti endpoint gateway hanya menjangkau sesi background pada kondisi tertentu — supervisornya harus dinyalakan dari shell bergateway, dan sesinya dikirim ke direktori itu atau di-background dari sana. Letakkan apa pun yang harus berlaku universal di file setting, bukan di profil shell.
Inilah keputusan desain yang membuat menjalankan empat agent sekaligus terasa masuk akal alih-alih sembrono. Sebelum menyentuh file, sesi background berpindah ke git worktree-nya sendiri, sehingga dua sesi yang mengerjakan repository yang sama tidak saling menimpa. Ia menyala secara default dan ada setting untuk mematikannya, yang sebaiknya Anda pikirkan matang sebelum dipakai.
# Before editing files, a background session moves into a git
# worktree under .claude/worktrees/ so parallel sessions do not
# collide. Skipped when: already in a linked worktree, not a git
# repository, or the write is outside the working directory.
{
"worktree": { "bgIsolation": "none" } // turn it off
}
# What CARRIES OVER when you background a session:
# running background shell commands
# backgrounded subagents
# dynamic workflows
# scheduled tasks from /loop
# directories added with /add-dir
# flags: --mcp-config --settings --add-dir --plugin-dir
# --fallback-model
#
# What STOPS:
# running monitors
# MCP servers awaiting input — anything needing an attached
# terminal, such as the settings list in /mcpMenghapus sebuah sesi di agent view menghapus worktree-nya. Kalau sesi itu menghasilkan pekerjaan yang belum Anda commit, ia ikut hilang. Tombol stop-dan-hapus butuh dua tekan chord yang sama, dan itu disengaja, tetapi kebiasaan yang layak dibangun adalah melakukan commit dari worktree sesi background sebelum menghapusnya — atau memakai perintah remove, yang mengeluarkannya dari daftar dan mempertahankan transkripnya.
UI-nya berupa daftar baris yang dikelompokkan menurut keadaan, dan dua tombol yang paling layak dipelajari lebih dulu adalah peek dan attach — peek menampilkan keluaran terbaru atau pertanyaan yang memblokir sebuah sesi tanpa mengikat Anda padanya, dan itu persis yang Anda inginkan saat memindai empat baris untuk menemukan satu yang membutuhkan Anda.
# Agent view keys
↑ ↓ navigate rows
Space peek — latest output, or the blocking question
Enter / → attach to the full session
← background it again and come back here
Ctrl+T PIN — keep the process running while idle
Ctrl+R rename
Ctrl+X ×2 stop and delete
Ctrl+S toggle grouping: by state, or by directory
# From any shell, without the UI:
claude agents --json # list sessions as JSON
claude attach <id>
claude logs <id>
claude stop <id>
claude rm <id> # remove from the list, KEEPS the transcript
claude respawn <id> # restart with the conversation intact
claude daemon status
claude daemon stop --any # add --keep-workers to preserve sessionsKeadaan-keadaannya, dan apa yang dikatakan masing-masing:
| Keadaan | Artinya |
|---|---|
| Needs input | Menunggu persetujuan, jawaban, atau permission — satu-satunya keadaan yang membutuhkan Anda sekarang |
| Working | Sedang aktif memproses; pakai peek untuk melihat sejauh mana |
| Idle | Siap untuk prompt berikutnya. Tanpa dipin, ia dihentikan setelah sekitar satu jam |
| Completed atau Failed | Selesai. Failed berarti ia berakhir dengan error, bukan dihentikan |
Daftar yang ikut terbawa lebih murah hati daripada dugaan Anda: perintah shell yang sedang berjalan, subagent yang di-background, dynamic workflow, tugas loop terjadwal, direktori yang ditambahkan, dan sebagian besar flag peluncuran semuanya ikut. Artinya sesi yang sedang di tengah workflow bisa didorong ke background tanpa kehilangan workflow-nya.
Dua hal berhenti, dan keduanya dengan alasan sama: mereka butuh terminal. Monitor yang sedang berjalan berhenti, dan MCP server mana pun yang menunggu input berhenti — termasuk perintah yang membuka daftar setting atau alur instalasi. Kalau sesi Anda sedang mengerjakan sesuatu yang menuntut Anda menjawab di sebuah picker, selesaikan itu dulu lalu pindahkan ke background.
Pin adalah jawaban untuk penghentian idle satu jam itu. Sesi yang dipin menjaga prosesnya tetap hidup bahkan saat idle, dan itu penting ketika sesi tersebut memegang keadaan mahal yang tidak ingin Anda bangun ulang — cache yang sudah panas, percakapan panjang, environment yang sudah dimuat. Selebihnya lebih baik tidak dipin supaya supervisor bisa mengambilnya kembali.
Tiga batasan menentukan apakah ini cocok dengan alur kerja Anda, dan yang pertama soal aritmetika, bukan pendapat:
Pola yang paling berhasil bagi saya adalah satu investigasi per pertanyaan independen, dikirim lalu ditinggalkan. Test yang labil, satu putaran dokumentasi, dan sebuah refactor adalah tiga hal yang tidak perlu saling bicara, dan menjalankannya paralel berbiaya tiga kali token dan kira-kira sepertiga wall-clock time. Itu pertukaran yang bagus ketika tokennya lebih murah daripada perhatian Anda.
Itu pertukaran yang buruk ketika tugasnya sebenarnya satu tugas. Tiga sesi pada subsistem yang sama akan menghasilkan tiga kumpulan edit yang saling tumpang tindih dan tidak konsisten di tiga worktree, dan menggabungkannya lebih buruk daripada mengerjakannya sekali. Worktree mencegah mereka saling merusak; ia tidak mencegah mereka saling bertentangan.
Pegang supervisor itu dalam pikiran dan sisa fitur ini berhenti mengejutkan: itulah sebabnya sesi hidup lebih lama daripada terminal Anda, kenapa environment variable harus tinggal di setting alih-alih di shell, kenapa sesi yang crash kembali sendiri, dan kenapa menghentikan daemon-nya adalah operasi sungguhan alih-alih menutup jendela. Kirimkan hal-hal yang memang independen, pin hanya yang memegang keadaan mahal, dan lakukan commit sebelum menghapus — itu sudah sebagian besar yang Anda butuhkan.
Sumber & bacaan lanjutan