SpyBara
Go Premium

plugins/mods/reference.md 2026-10-01 23:59 UTC to 2026-10-02 19:58 UTC

This page contains 326 additions and 0 deletions.

2026
Fri 2 20:57

Referensi mod

Referensi lengkap untuk mod Claude Code: tata letak modul hook, event, metode API mod, titik render, elemen per surface, batas, dan pengaturan.

Cari event apa pun yang dapat ditangani oleh sebuah mod, metode API mod yang dapat dipanggilnya, atau titik render tempat ia dapat menggambar, untuk CLI Claude Code dan aplikasi Desktop per v2.1.287. Setiap entri memberikan nama dan deskripsi satu baris, serta menautkan ke bagian panduan yang menjelaskannya jika ada.

File

Sebuah mod adalah direktori plugin dengan file-file berikut:

File Wajib Isi
.claude-plugin/plugin.json Ya Manifest plugin. Mod tidak menambahkan field wajib.
hooks/hooks.json Ya modules: sebuah array dengan satu path, relatif terhadap file ini, ke modul hook, seperti dalam "modules": ["./register.js"]. Juga dapat memuat hook pengaturan di bawah hooks.
Modul hook, seperti hooks/register.js Ya Titik masuk mod. Mengekspor register(on, options). Bernama .js, .mjs, .cjs, .jsx, .ts, .mts, .cts, atau .tsx. Sebuah modul ES.
types/index.d.ts, dinamai oleh types di manifest Saat mod menggunakan $.state atau menambahkan namespace ke API mod Mendeklarasikan nilai PluginState dan namespace apa pun yang ditambahkan mod
File yang namanya berakhiran .test.ts atau .test.tsx Tidak Tes yang dijalankan oleh claude plugin test

register menerima on dan options. options memuat nilai-nilai field userConfig yang dideklarasikan manifest, dengan nilai default yang sudah diisi.

Fungsi hook

Sebuah mod mendaftarkan setiap hook-nya, yang merupakan handler event, dengan memanggil on di dalam register. on menerima nama event, matcher opsional, yaitu filter pada field event, dan hook itu sendiri, seperti dalam on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)). on mengembalikan sebuah registrasi dengan satu metode, .catch(handler), yang menetapkan handler error hook tersebut.

Argumen Apa itu
$ API mod: setiap metode dalam metode API mod. Tulis setiap panggilan secara lengkap, namespace lalu metode, seperti dalam $.fs.read('notes.md').
e Input event, sebagai data biasa yang dibekukan secara mendalam. Untuk mengubahnya, teruskan salinannya ke next.
next(e) Handler berikutnya, seperti pada middleware. Menjalankan hook setelah hook ini, lalu perilaku Claude Code. Resolve ke hasil event.
next.signal Sebuah AbortSignal yang dibatalkan saat event ditinggalkan
next.origin { plugin, tier } dari pihak yang memicu event. Claude Code sendiri adalah { plugin: 'engine', tier: 'core' }. tier sebuah mod adalah grup prioritasnya dalam urutan mod dijalankan: prepend, user, append, atau builtin.
next.budget Batas waktu hook dalam milidetik: next.budget.ms adalah seluruh batas, dan next.budget.remainingMs adalah sisa waktu saat ini
next.to(e, tier) Melompat ke tier yang lebih belakang, yaitu append, builtin, atau core. next.to(e, 'append') melewati mod yang diinstal pengguna. Hanya mod di prependPlugins atau appendPlugins yang dapat memanggilnya.
next.error, next.called Hanya di handler .catch. next.error.kind adalah throw atau timeout, next.error.message adalah teks error, dan next.called bernilai true saat hook yang gagal telah memanggil next.

Event

Event dikelompokkan berdasarkan apa yang menjadi perhatiannya, masing-masing dengan kapan dipicu dan apa yang dapat dikembalikan oleh hook padanya. Hook pada turn.step dan process.spawn adalah async generator, dan hook lainnya adalah fungsi async.

Kolom terakhir setiap tabel menggunakan singkatan. next(e) meneruskan event tanpa perubahan. next({ ...e, text }) meneruskan salinan dengan field yang disebutkan diubah, seperti dalam next({ ...e, text: e.text.trim() }). Sebuah objek menjawab event tanpa memanggil next, dan kata seperti reason mewakili string yang Anda tulis, seperti dalam { deny: 'Use the file tools.' }.

Tool

Event tool dipicu di sekitar setiap panggilan tool yang dibuat Claude, mulai dari deskripsi yang dibaca Claude hingga keputusan apakah panggilan tersebut dijalankan:

Event Dipicu saat Hook dapat mengembalikan
tool.call Sebuah tool akan dijalankan next(e), { deny: reason }, atau { result }
tool.check Claude Code memutuskan apakah panggilan tool boleh dijalankan, setelah hook tool.call dan PreToolUse. next(e) resolve ke keputusan yang dicapai oleh aturan, mode izin, dan hook-hook tersebut. { decision }, yaitu allow, ask, atau deny
tool.describe Sekali untuk setiap tool, saat deskripsinya pertama kali dikirim ke Claude { description }

Prompt dan apa yang dibaca Claude

Event prompt mencakup teks yang diketik pengguna dan teks yang dikirim Claude Code ke Claude atas inisiatifnya sendiri, seperti system prompt dan pengingat:

Event Dipicu saat Hook dapat mengembalikan
prompt.submit Sebuah prompt dikirim next({ ...e, text }), next({ ...e, context }), atau { drop: reason }
prompt.fill, prompt.suggest Teks akan dimasukkan ke kotak prompt sebagai draf, atau sebagai saran redup next(e) dengan teks yang diubah
prompt.edit Pengguna mengedit kotak prompt next(e)
prompt.compose Claude Code merender system prompt { sections }, daftar { id, text, scope } dalam urutan pengirimannya
prompt.section Sekali untuk setiap bagian bernama dari system prompt. e.name adalah id bagian tersebut di prompt.compose. { text }, atau { text: null } untuk menghilangkan bagian tersebut
prompt.context Sekali untuk setiap percakapan, untuk konteks yang dikirim bersama pesan pertama { blocks }
prompt.attachment Claude Code menambahkan pesannya sendiri untuk Claude, seperti pengingat. e.type menyebutkan jenisnya, dan untuk jenis yang dideklarasikan oleh types, e.detail memuat fakta yang menjadi dasar penulisan teks tersebut. { text }, atau { text: null } untuk menghilangkannya
skill.prompt Teks sebuah skill diperluas untuk Claude { text }
attribution.text Claude Code menyusun teks atribusi commit atau pull request { text }

Perintah dan konfigurasi

Event perintah dan konfigurasi dipicu saat perintah dijalankan atau dicantumkan, dan saat baris /config ditampilkan atau diubah:

Event Dipicu saat Hook dapat mengembalikan
command.run Sebuah perintah akan dijalankan { text }, {}, atau next(e)
command.describe Sekali untuk setiap perintah, untuk daftar perintah { description, argumentHint, isHidden }
config.set Sebuah baris /config akan berubah next({ ...e, value }) atau { deny: reason }
config.describe Sekali untuk setiap baris /config { label, description, isHidden }

Giliran

Event giliran mengikuti satu jawaban dari awal hingga akhir, termasuk setiap permintaan ke model di dalamnya:

Event Dipicu saat Hook dapat mengembalikan
turn.start Sebuah giliran dimulai next(e)
turn.step Satu permintaan akan dikirim ke model yield* next(e), atau next({ ...e, model }), next({ ...e, effort })
turn.complete Sebuah giliran berakhir next(e), atau { text } untuk menampilkan baris di bawah jawaban

Sesi

Event sesi menandai sesi yang dimulai, berakhir, dipadatkan, dan bertukar pesan dengan sesi lain:

Event Dipicu saat Hook dapat mengembalikan
session.start Sekali untuk setiap mod yang dimuat, sebelum prompt pertama, dan sekali lagi setelah mod tersebut dimuat ulang. Tidak setelah /clear, /resume, atau /branch. next(e)
session.end Sesi berakhir, atau /clear, /resume, atau /branch dijalankan. e.reason adalah clear, resume, logout, prompt_input_exit, atau other. /branch melaporkan resume. next(e)
session.compact Percakapan akan dipadatkan { skip: reason }
session.receive, session.send Sebuah pesan tiba dari, atau akan dikirim ke, agent atau sesi lain. Lihat Mengirim dan menerima pesan antarsesi. { consumed: reason } untuk receive, { isDelivered: false, reason } untuk send
session.append Sekali untuk setiap baris yang disimpan percakapan, seperti prompt, blok respons, hasil tool, atau pemberitahuan, sebelum disimpan next({ ...e, message }) untuk menulis ulang content baris tersebut
session.attach, session.detach Aplikasi lain terhubung ke atau terputus dari sesi next(e)
session.measure Setelah setiap giliran, dan saat persentase penggunaan batas paket berubah next(e)

Subagent

Event subagent dipicu saat sebuah tipe subagent ditawarkan kepada Claude dan saat subagent akan dimulai:

Event Dipicu saat Hook dapat mengembalikan
agent.offer Sebuah tipe subagent ditawarkan kepada Claude { isOffered: false } untuk menahannya
agent.spawn Sebuah subagent akan dimulai { model } atau { deny: reason }

Antarmuka

Event antarmuka dipicu saat Claude Code menggambar titik render dan saat pengguna menggunakan kontrol yang digambar oleh mod. Menggambar di antarmuka menunjukkan apa yang dikembalikan oleh hook ui.render:

Event Dipicu saat
ui.render Sebuah titik render akan digambar
ui.resolve Mod dimuat, sekali untuk setiap aplikasi, titik render, dan mod. Hasilnya adalah tabel elemen yang dibaca oleh $.ui.resolve(e).
ui.press, ui.input, ui.select Sebuah Button, Input, atau Select yang digambar mod digunakan
ui.focus, ui.scroll Kontrol yang difokuskan atau posisi gulir sebuah panel atau band akan berubah
ui.close Sebuah panel akan ditutup. e.id adalah panel tersebut dan e.origin.kind adalah plugin, person, atau unload.
ui.message Sebuah elemen Client mengirim data ke mod-nya

Mod lain

Event ini memungkinkan sebuah mod bertindak atas mod lain saat dimuat, untuk menolak salah satunya atau mengubah API mod yang diterimanya:

Event Dipicu saat Hook dapat mengembalikan
plugin.register Sebuah modul hook akan dimuat. e.uses mencantumkan event, panggilan API mod, environment variable, dan state-nya, sebagaimana dicetak oleh claude plugin validate. Setiap panggilan ditulis tanpa prefiks $., seperti fs.read. { refuse: reason }
engine.create API mod sedang dibangun untuk mod ini API mod yang diubah, untuk menambahkan namespace atau menahannya

Telemetri

Event telemetri dipicu untuk catatan penggunaan yang ditulis Claude Code ke log:

Event Dipicu saat Hook dapat mengembalikan
telemetry.log, telemetry.mark Sebuah catatan telemetri akan ditulis ke log, atau satu penggunaan fitur ditandai. Pada mod yang Anda instal, berikan hook telemetri filter { to: 'collector' }, seperti dalam on('telemetry.log', { to: 'collector' }, hook). Tanpa filter tersebut, mod gagal dalam claude plugin validate. * tidak cocok dengan event ini. next(e), atau { deny: reason }

Event hook pengaturan

Setiap event hook pengaturan adalah event bernama classic.<Event>, seperti classic.Stop atau classic.PostToolUse. e adalah JSON stdin hook tersebut.

Panggilan API mod

Setiap metode API mod juga merupakan event, dinamai sesuai namespace dan metodenya, seperti fs.read, model.complete, atau ui.open. Hook pada salah satunya mencegat panggilan dari mod yang dijalankan setelahnya, dan dapat mengembalikan next(e), { deny: reason }, atau { value }.

Metode API mod

API mod adalah argumen $ yang diterima setiap hook. Metodenya dikelompokkan dalam namespace, seperti $.ui. Tabel ini mencantumkan metode setiap namespace berdasarkan nama, sehingga open pada baris $.ui adalah panggilan $.ui.open(...). Panduan menunjukkan penggunaan metode yang umum, dan types untuk build Anda mendokumentasikan setiap metode beserta contohnya.

Namespace Metode
$.plugin name, root: nama dan direktori plugin ini
$.ui resolve, invalidate, open, close, panes, focus, scroll, toast, status, log, notice, ask, copy, blit
$.command register, run, list
$.tool register, call, check, list
$.agent register, spawn, list
$.model complete, fork, classify
$.prompt submit, read, fill, suggest, compose. Claude membaca teks dari submit({ text }) setelah sebuah kalimat yang menyebut mod Anda sebagai pengirim. submit({ text, asUser: true }) mengirim teks sebagai kata-kata pengguna sendiri, tanpa kalimat tersebut.
$.turn abort
$.session messages, cwd, root, model, turns, id, repo, surfaces, usage, version, compact, send, append, authorize. usage() mengembalikan { startedAt, context, rateLimits, cost }: context memiliki tokens, window, dan percent, dan rateLimits adalah daftar { kind, percentUsed, resetsAt }.
$.config list, set
$.settings read
$.env get, set
$.fs read, write, list, exists, stat, ancestors. write tidak atomik: ia mengganti isi file di tempat, sehingga proses lain dapat membaca file yang baru ditulis sebagian. Simpan data yang diubah oleh beberapa sesi di $.store.
$.store get, set, delete, keys. Penyimpanan key-value yang dibagikan oleh setiap sesi di mesin. Lihat Menyimpan dari lebih dari satu sesi.
$.state State reaktif: get, set, dengan helper atom, read, update, derive, dan memberOf yang diimpor dari claude-code
$.clock now, sleep, after, every
$.http fetch
$.process run, spawn
$.mcp call, connect. connect(server) menghubungkan server MCP yang tercantum di manifest plugin Anda sendiri.
$.audio play, speak
$.telemetry log, mark. Sebuah catatan hanya dikirim saat Claude Code atau mod bawaan melakukan panggilan tersebut.

Titik render

Titik render adalah titik ekstensi di antarmuka Claude Code. Setiap baris adalah nilai e.component dalam hook ui.render, dengan field e.props dan aplikasi yang merendernya. e.surface adalah terminal atau desktop. Mengubah apa yang sudah digambar Claude Code menunjukkan apa yang dapat dilakukan hook di sebuah titik, dengan contoh untuk setiap pilihan.

Titik e.props e.requestId Dirender di
Pane title, isFocused, bodyColumns, placement, scroll, view id panel Terminal, Desktop
AbovePrompt hasSurvey, isWorking, maxRows, bodyColumns, scroll, view Satu instans Terminal, Desktop
UserMessage text, origin, isExpanded, dan task atau from tergantung origin id pesan Terminal, Desktop
AssistantMessage Teks balasan id pesan Terminal, Desktop
ToolUse, ToolResult, ToolGroup Nama, input, dan hasil tool id panggilan tool Terminal, Desktop
CommandOutput command, text id pesan Terminal, Desktop
AskUserQuestion Pertanyaan dan opsi id panggilan tool Terminal, Desktop
ToolProgress kind id panggilan tool Terminal
Spinner word, message, suffix, mode id agent Terminal, Desktop
TurnDuration word, durationMs id pesan Terminal
InfoNotice text, command id pesan Terminal
SessionMode modes Satu instans Terminal, Desktop
PromptHint isDraft, isWorking, hint Satu instans Terminal, Desktop

e.viewport memuat columns, rows, dan isFullscreen. Nilai ini tidak ada sampai aplikasi telah mengukur jendelanya. rows-nya adalah tinggi seluruh jendela, bukan tinggi panel Anda.

Untuk menyesuaikan sebuah tree dengan titiknya, baca prop berikut di dalam hook:

  • Lebar sebuah Pane atau band: gambar sesuai e.props.bodyColumns
  • Tinggi sebuah Pane di samping transkrip: jika e.props.placement adalah 'dock', e.props.scroll.bodyRows adalah jumlah baris yang dimiliki panel
  • Tinggi sebuah Pane di atas prompt: jika e.props.placement adalah 'inline', panel bertambah sesuai tree Anda hingga suatu batas, dan bodyRows hanya menghitung baris yang ditampilkan saat ini. Field rows dari $.ui.open meminta batas yang berbeda.

Tree yang lebih tinggi daripada panel akan bergulir secara keseluruhan.

Elemen

Elemen adalah blok penyusun tree yang dikembalikan oleh hook ui.render, dan Anda mendapatkannya dari $.ui.resolve(e). Membangun tree dari elemen menunjukkan elemen yang umum beserta cara terminal menggambarnya, dan galeri antarmuka memiliki tangkapan layar sebagian besar elemen. Tanda centang berarti aplikasi dapat menggambar elemen tersebut.

Elemen Prop utama Terminal Desktop
Box key, tata letak flex, gap, padding, margin, width, height, borderStyle, backgroundColor, position, hover ✓ ✓
Text color, backgroundColor, bold, italic, underline, dimColor, inverse, wrap ✓ ✓
Button key, label, onPress, hotkey, plain, dimColor, autoFocus, action ✓ ✓
Link href, label ✓ ✓
Code Kode, hingga 10.000 karakter ✓ ✓
Markdown text, hingga 10.000 karakter, key, dimColor, onLinkPress, pressableLinks ✓ ✓
Input key, label, placeholder, value, submitLabel, onSubmit, onInput, autoFocus ✓ ✓
Select key, label, options, value, onSelect, autoFocus ✓ ✓
Svg Dokumen SVG, hingga 131.072 karakter ✓
Client module, key ✓ ✓
Raster key, columns hingga 512, rows hingga 256, cells. Lihat Menggambar grid sel berwarna. ✓
Image Byte PNG atau RGBA hingga 2 MiB, atau path file ✓

Aturan Button lainnya: action menyebutkan salah satu aksi pintasan keyboard milik Claude Code sendiri, dan pintasan keyboard pengguna untuk aksi tersebut akan menekan tombol jika pintasan itu berupa chord atau tombol dengan modifier. hotkey berupa digit pada tombol di band juga terpicu saat pengguna mengetik digit tersebut saja ke dalam prompt kosong lalu berhenti sejenak. Jika dua tombol dalam satu gambar menyebutkan hotkey yang sama, tombol yang lebih belakang yang mendapatkannya. autoFocus hanya menerima true pada kontrol apa pun, jadi hilangkan prop tersebut untuk menonaktifkannya.

Batas

Hook dan panggilan API mod berjalan di bawah batas waktu dan ukuran. Claude Code melewati hook yang melampaui batas waktu dan menolak panggilan yang melampaui batas ukuran.

Batas Nilai
Waktu eksekusi hook itu sendiri untuk satu event, tidak termasuk waktu di dalam next atau panggilan API mod selain $.clock.sleep 10 detik
Waktu eksekusi handler .catch 1 detik
Semua hook session.end secara keseluruhan 1,5 detik
Timeout $.process.run 30 detik secara default, paling lama 10 menit
maxTokens $.model.complete 1024 secara default, hingga 64.000 atau batas output model
$.fs.read dan $.fs.write 4 MiB untuk satu file
Satu child string dari Text 10.000 karakter
$.store Total 4 MiB JSON
$.session.messages() 4.096 entri terbaru
Penggambaran ulang $.ui.invalidate('ui.render') Dibatasi hingga 10 per detik, atau 30 di terminal untuk panel yang terlihat, band yang diperluas, dan baris petunjuk di bawah prompt. Panggilan yang datang lebih cepat digabungkan.
$.ui.toast Ditampilkan selama 4 detik kecuali Anda meneruskan { timeoutMs }
Panel yang dibuka tanpa diminta pengguna Ditempatkan mulai dari 144 kolom terminal, 110 setelah pengguna pernah membukanya sekali
Nama perintah, tool, tipe subagent, dan panel Huruf, digit, _, dan -, hingga 64 karakter
Satu tes claude plugin test 5 detik kecuali tes tersebut menetapkan timeoutMs

Pengaturan dan environment variable

Berikut adalah pengaturan dan environment variable yang memengaruhi mod. Kolom Lokasi menyebutkan file pengaturan atau environment tempat masing-masing dibaca:

Nama Lokasi Fungsinya
CLAUDE_CODE_PLUGIN_DIRS Environment, atau env di ~/.claude/settings.json Direktori plugin yang dimuat seperti --plugin-dir, untuk aplikasi yang tidak dapat Anda berikan flag. Path absolut yang dipisahkan oleh :, atau ; di Windows.
CLAUDE_CODE_PLUGIN_DIR_WATCH Environment 1 membuat sesi non-interaktif yang berjalan lama memuat ulang mod --plugin-dir saat disimpan
prependPlugins, appendPlugins Pengaturan terkelola. Pengaturan pengguna hanya pada mesin tanpa pengaturan terkelola, untuk pengguna yang tidak masuk dengan paket Team atau Enterprise. Daftar id plugin, seperti acme-guard@acme-tools. Mod di prependPlugins berjalan sebelum setiap mod yang diinstal pengguna, dan mod di appendPlugins berjalan setelahnya, sesuai urutan yang tercantum. Lihat Urutan mod dijalankan.
allowManagedModsOnly Pengaturan terkelola, sebagai opsi pada penjaga bawaan Hanya mod yang terhitung sebagai milik organisasi Anda, dan mod bawaan Claude Code, yang dimuat. Hook pengaturan pengguna tetap berjalan.
allowModsToOverrideDenyRules Pengaturan terkelola, sebagai opsi pada penjaga bawaan Mengizinkan mod yang diinstal pengguna menyetujui panggilan tool yang ditolak oleh aturan deny
allowManagedHooksOnly Pengaturan terkelola Memblokir hook dan mod terinstal yang bukan milik organisasi Anda. Lihat apa yang tetap berjalan.
disableAllHooks File pengaturan apa pun Di pengaturan terkelola, tidak ada mod atau hook dari plugin terinstal yang berjalan. Di pengaturan Anda sendiri, apa yang dikelola organisasi Anda tetap berjalan. Lihat disableAllHooks.
disableSideloadFlags Pengaturan terkelola Menolak --plugin-dir dan --plugin-url saat startup
pluginConfigs Pengaturan pengguna atau terkelola Memuat nilai userConfig untuk sebuah mod, dengan kunci berupa id plugin, seperti acme-guard@acme-tools, atau namanya dan @inline, seperti first-mod@inline, untuk mod yang dimuat dengan --plugin-dir

sec-default@builtin adalah penjaga bawaan Claude Code, tercantum sebagai cc-plugin-sec-default di /plugin dan log debug. Penjaga ini dimuat sebelum setiap mod yang diinstal seseorang pada mesin dengan pengaturan terkelola, atau untuk pengguna yang masuk dengan paket Team atau Enterprise. Jika prependPlugins terkelola ditetapkan, penjaga ini hanya dimuat jika daftar tersebut menyebutkannya, pada posisi yang tercantum. Sumbernya ada di direktori mods/sec-default dari repositori Claude Code.

Perintah

Perintah dan flag berikut memuat, memeriksa, dan menguji sebuah mod. Perintah claude dijalankan di shell Anda dan perintah / di prompt Claude Code. Dalam tabel, <directory> mewakili path yang Anda ketik, seperti dalam claude plugin validate ./first-mod. Tanda kurung siku menandai argumen opsional.

Perintah Fungsinya
/plugin Menampilkan baris seperti 1 mod active · first-mod di bawah tab-nya saat mod yang bukan bawaan telah dimuat
claude plugin validate <directory> Membaca manifest dan modul hook sebuah plugin lalu melaporkan error, event yang ditanganinya, dan panggilan API mod yang dilakukannya. --strict memperlakukan peringatan sebagai error dan --json mencetak laporan yang dapat dibaca mesin.
claude plugin test [directory] Menjalankan setiap file di bawah direktori, atau direktori saat ini jika Anda tidak memberikannya, yang namanya berakhiran .test.ts atau .test.tsx. Keluar dengan status 1 saat sebuah tes gagal.
claude --plugin-dir <directory> Memuat direktori plugin untuk satu sesi dan memuat ulang modul hook-nya saat Anda menyimpan. Ulangi flag untuk memuat beberapa.
/reload-plugins Memuat ulang plugin saat Anda menjalankannya