SpyBara
Go Premium

plugins/mods/reference.md 2026-11-08 22:58 UTC to 2026-11-09 23:02 UTC

This page contains 14 additions and 4 deletions.

2026
Wed 4 23:59 Mon 9 23:02 Tue 10 21: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. Entri mencakup CLI Claude Code dan aplikasi Desktop per v2.1.290, serta ekstensi VS Code per v2.1.299. Setiap entri memberikan nama dan deskripsi satu baris, serta menautkan ke bagian panduan yang menjelaskannya jika ada.

[!NOTE]

Referensi lengkapnya adalah deklarasi TypeScript untuk mod milik Claude Code, yang menjelaskan setiap event, metode, dan elemen, beserta contohnya. Salinan di GitHub bisa lebih lama daripada versi Claude Code yang Anda instal. Jika keduanya tidak sesuai, percayai salinan yang ditulis Claude Code untuk versi Anda.

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, kecuali types di manifest menyebutkan path lain Saat mod menggunakan $.state atau menambahkan namespace ke API mod Mendeklarasikan nilai PluginState dan namespace apa pun yang ditambahkan mod. Untuk menghilangkan types dari manifest, Anda memerlukan v2.1.299 atau yang lebih baru.
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 Hanya di handler .catch. kind adalah throw atau timeout saat hook gagal, dan message adalah teks error. kind adalah re-entry saat hook dilewati karena event berasal dari dalam panggilan API mod oleh hook tersebut atau oleh kode mod Anda di luar hook-nya. re-entry memerlukan Claude Code v2.1.292 atau yang lebih baru.
next.error.cause Hanya ditetapkan saat kind adalah re-entry. rewritten jika hook tool.call atau PreToolUse mengubah panggilan API mod yang menjadi asal event, atau hook agent.spawn mengubah agent yang dimulai oleh panggilan tersebut. lent jika sebuah metode yang ditambahkan mod lain ke API mod memicu event tersebut, kecuali rewritten juga berlaku. lent memerlukan Claude Code v2.1.292 atau yang lebih baru dan rewritten v2.1.300 atau yang lebih baru.
next.called Hanya di handler .catch. true saat hook 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. next(e) atau { decision }, dengan decision diatur ke allow, ask, atau deny dan reason opsional
tool.describe Sekali untuk setiap tool, saat deskripsinya pertama kali dikirim ke Claude. Sekali lagi untuk tool MCP saat Claude memuatnya melalui pencarian tool, dengan e.description diatur ke teks yang dibaca Claude untuk tool yang dimuat tersebut. { description }, secara opsional dengan isDeferred diatur ke true untuk menempatkan tool di balik pencarian tool atau false untuk memuatnya sejak awal. Tambahkan breakPromptCache: true untuk mengirim deskripsi yang diubah pada giliran berikutnya.

Field agent dan organisasi pada tool.check

Dalam hook tool.check, baca field berikut untuk membedakan panggilan subagent dari panggilan percakapan utama, dan untuk melihat apakah organisasi Anda mewajibkan persetujuan untuk tool konektor:

Pada tool.check, e.agentId dan e.ceiling memerlukan Claude Code v2.1.290 atau yang lebih baru.

Field e.isReadOnly pada tool.check

Dalam hook tool.check, e.isReadOnly bernilai true saat tool melaporkan panggilan ini sebagai read-only. Jika tidak, field tersebut tidak ada, bukan false. Nilainya adalah laporan tool itu sendiri, jadi baca Memeriksa apakah panggilan tool bersifat read-only sebelum Anda menyetujui sebuah panggilan hanya berdasarkan field ini.

Pada tool.check, e.isReadOnly memerlukan Claude Code v2.1.304 atau yang lebih baru.

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.autocomplete Pengguna mengetik di kotak prompt dan sebuah kata berakhir di kursor. e.token adalah kata tersebut. Claude Code tidak menunggu hook: baris autocomplete miliknya sendiri ditampilkan lebih dulu. { suggestions }, daftar baris { text, label, description } yang ditampilkan di bawah baris milik Claude Code. Memilih sebuah baris akan menulis text-nya menggantikan kata tersebut.
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. Tambahkan breakPromptCache: true untuk mengirim bagian yang diubah pada giliran berikutnya.
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
prompt.mention Claude Code akan membaca file yang di-@-mention oleh sebuah prompt. Memerlukan Claude Code v2.1.290 atau yang lebih baru. next({ ...e, path }) untuk membaca file lain, atau { deny: reason }
skill.prompt Teks sebuah skill diperluas untuk Claude { text }
attribution.text Claude Code menyusun teks atribusi commit atau pull request { text }

Field sumber dan frontmatter pada skill.prompt

Dalam hook skill.prompt, Anda dapat membaca field berikut bersama dengan nama skill di e.skill dan teks yang dibaca Claude di e.text:

Field Tipe Isinya
e.source string Siapa yang menyediakan skill: policySettings, userSettings, atau projectSettings untuk skill di lokasi enterprise, pribadi, atau proyek, secara berurutan. Sumber lain memberikan kata seperti plugin, mcp, syncedSkills, atau built-in.
e.pluginName string Nama plugin, untuk skill yang e.source-nya adalah plugin
e.path string Path absolut file SKILL.md milik skill, atau file .md-nya untuk skill yang ditulis sebagai file perintah. Tidak ada jika skill tidak memiliki file di mesin ini, seperti pada skill bawaan.
e.frontmatter object Frontmatter dari file skill, sebagai data biasa
e.frontmatterProblem string Alasan e.frontmatter tidak memuat frontmatter file atau salah satu key-nya, seperti dalam is a list or a single value, not a table. Tidak ada jika e.frontmatter memuat seluruh frontmatter atau skill tidak memilikinya.

Hook dapat meneruskan text atau frontmatter yang diubah ke next: hook setelahnya membaca keduanya, dan Claude membaca text akhir. Hook yang mengubah field lain apa pun akan gagal.

Pada skill.prompt, e.source, e.pluginName, e.path, e.frontmatter, dan e.frontmatterProblem memerlukan Claude Code v2.1.299 atau yang lebih baru.

Mengirim bagian system prompt atau deskripsi tool yang diubah dengan breakPromptCache

Untuk mengubah sebuah bagian atau deskripsi tool dalam percakapan yang sedang berjalan, panggil $.ui.invalidate('prompt.section') atau $.ui.invalidate('tool.describe') agar hook Anda dijalankan lagi. Kembalikan { text, breakPromptCache: true } atau { description, breakPromptCache: true } dari hook tersebut. Tanpa field ini, Claude tetap membaca teks yang disimpan bersama percakapan untuk sebuah bagian atau tool yang dimuat sejak awal hingga percakapan baru atau compaction.

Teks yang diubah sampai ke Claude pada giliran berikutnya, dan cache prompt dimulai dari awal, sehingga giliran tersebut lebih lambat dan lebih mahal. Field ini memerlukan Claude Code v2.1.321 atau yang lebih baru. Dari v2.1.299 hingga v2.1.321, percakapan yang sedang berjalan menerima teks yang diubah pada giliran berikutnya.

Perintah dan konfigurasi

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 }
settings.read Sebuah mod memanggil $.settings.read, atau Claude Code membangun pengaturan gabungan sesi. Memerlukan Claude Code v2.1.304 atau yang lebih baru pada pembacaan milik Claude Code sendiri dan untuk e.layers next(e), { value }, atau { deny: reason }

e.layers dan e.source pada settings.read

  • e.layers: satu objek { source, settings } untuk setiap sumber yang digunakan yang memuat pengaturan, dengan prioritas terendah lebih dulu. Lihat Apa yang diterima hook settings.read.
  • e.source: satu sumber yang diminta oleh mod, seperti dalam $.settings.read({ source: 'policy' }). Tidak ada pada pembacaan milik Claude Code sendiri dan pada pembacaan pengaturan gabungan

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 }) dengan message.content yang diubah, untuk menulis ulang blok teks baris tersebut atau content dari blok tool_result di dalamnya
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 atau rekan tim dalam tim agent akan dimulai:

Event Dipicu saat Hook dapat mengembalikan
agent.offer Sebuah tipe subagent ditawarkan kepada Claude { isOffered: false } untuk menahannya
agent.spawn Sebuah subagent atau rekan tim dalam tim agent akan dimulai, atau subagent yang telah selesai atau berhenti akan dijalankan lagi. Untuk rekan tim, e.isTeammate bernilai true. Untuk eksekusi yang dilanjutkan, e.resume diatur. next({ ...e, model }) untuk memilih model dari yang sedang dimulai, atau { deny: reason }

Hook agent.spawn Anda juga dijalankan saat subagent yang telah selesai atau berhenti akan dijalankan lagi, seperti saat Claude mengirim pesan kepadanya dengan tool SendMessage. Pada event tersebut, e.resume adalah { agentId }. Jika hook Anda menghitung subagent, lewati event yang e.resume-nya diatur, agar subagent yang dilanjutkan tidak dihitung lagi.

Kembalikan { deny: reason } untuk menolak eksekusi yang dilanjutkan. Eksekusi tidak dimulai, dan subagent tetap seperti semula. Saat sebuah panggilan SendMessage yang meminta eksekusi tersebut, Claude membaca a plugin declined the resume: diikuti alasan Anda sebagai hasil panggilan tersebut. Jika Anda meneruskan event yang diubah ke next untuk eksekusi yang dilanjutkan, seperti model yang berbeda, Claude Code mengabaikan perubahan tersebut.

[!NOTE]

Event untuk eksekusi yang dilanjutkan memerlukan Claude Code v2.1.299 atau yang lebih baru. Sebelum v2.1.299, hook agent.spawn Anda tidak dijalankan saat subagent dilanjutkan. Pada versi tersebut, untuk menolak panggilan SendMessage yang melanjutkan subagent, cocokkan tool tersebut dalam hook tool.call.

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
ui.fault Sebuah elemen Client yang digambar mod Anda gagal dimuat, digambar, atau dijalankan. e.phase adalah load, render, atau run, dan e.reason adalah pesan kesalahannya. Memerlukan Claude Code v2.1.289 atau yang lebih baru.

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. Mod di luar tingkat user juga dapat menahan salah satunya.

Saat hook mod lain memanggil metode pada namespace yang Anda tambahkan dalam engine.create, panggilan $ dari metode Anda dijalankan dalam konteks hook tersebut hingga setiap hook pada event tersebut kembali. Misalnya, path relatif di-resolve terhadap direktori kerja hook tersebut, dan $.prompt.submit ditolak selama giliran sedang menunggu hook tersebut. Panggilan yang dilakukan metode Anda setelah itu dijalankan dalam konteks mod Anda sendiri.

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, place, focus, scroll, toast, notify, status, log, notice, ask, copy, selection, blit, view. view memerlukan Claude Code v2.1.300 atau yang lebih baru dan place memerlukan v2.1.314 atau yang lebih baru.
$.theme set, clear: mengatur latar belakang (backdrop) untuk digambar oleh aplikasi Desktop atau seluler, dan menghapus latar belakang tersebut. Memerlukan Claude Code v2.1.319 atau yang lebih baru.
$.command register, run, list
$.tool register, call, check, list
$.agent register, spawn, list. list() mengembalikan subagent dan rekan tim (teammate) sesi ini, masing-masing dengan status berupa pending, running, waiting, idle, completed, failed, atau killed, di mana idle dan waiting memerlukan Claude Code v2.1.289 atau yang lebih baru.
$.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 menyebutkan aplikasi yang sedang menggambar, seperti terminal, desktop, atau vscode. Mengubah apa yang sudah digambar Claude Code menunjukkan apa yang dapat dilakukan hook di sebuah titik, dengan contoh untuk setiap pilihan.

Rendering di ekstensi VS Code memerlukan ekstensi versi 2.1.299 atau lebih baru. Sesi yang tidak mengambil feature flag memerlukan versi 2.1.304 atau lebih baru. Menggambar di ekstensi VS Code mencantumkan apa yang digambar secara berbeda oleh ekstensi tersebut.

Titik e.props e.requestId Dirender di
Pane title, isFocused, bodyColumns, placement, scroll, view id panel Terminal, Desktop, VS Code
AbovePrompt hasSurvey, isWorking, maxRows, bodyColumns, scroll, view Satu instans Terminal, Desktop
Placed id, plugin, onScreen requestId yang dikembalikan oleh $.ui.place Terminal
Backdrop id, plugin, glass, colorScheme backdrop Surface desktop dan mobile. Hook Anda berjalan saat aplikasi Desktop atau aplikasi seluler meminta untuk menggambar backdrop.
UserMessage text, origin, isExpanded, dan task atau from tergantung origin id pesan Terminal, Desktop, VS Code
AssistantMessage Teks balasan id pesan Terminal, Desktop, VS Code
ToolUse, ToolResult, ToolGroup Nama, input, dan hasil tool id panggilan tool Terminal, Desktop, VS Code
CommandOutput command, text id pesan Terminal, Desktop
AskUserQuestion Pertanyaan dan opsi id panggilan tool Terminal, Desktop, VS Code
ToolProgress kind id panggilan tool Terminal
Spinner word, message, suffix, mode id agent Terminal, Desktop, VS Code
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. Di terminal dan aplikasi Desktop, nilai ini tidak ada sampai aplikasi telah mengukur jendelanya. Di sana, rows-nya adalah tinggi seluruh jendela, bukan tinggi panel Anda. Di ekstensi VS Code, nilai ini selalu ada.

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 untuk tree Anda
  • Tinggi sebuah Pane di atas prompt: jika e.props.placement adalah 'inline', panel bertambah sesuai tree Anda hingga suatu batas, dan bodyRows adalah batas tersebut. Untuk meminta batas yang berbeda, lihat field rows dari $.ui.open.

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 VS Code
Box key, tata letak flex, gap, padding, margin, width, height, minWidth, minHeight, borderStyle, borderColor, borderDimColor, backgroundColor, position, top, left, right, bottom, overflow, display, hover ✓ ✓ ✓
Text color, backgroundColor, bold, italic, underline, strikethrough, dimColor, inverse, wrap, size, weight, mono, tabular, hover ✓ ✓ ✓
Button key, label, children, onPress, hotkey, plain, dimColor, autoFocus, action, variant, role, hover ✓ ✓ ✓
Link href, label. Lihat Batasan. ✓ ✓ ✓
Code source, language, path, startLine, format, wrap ✓ ✓ ✓
Markdown text, key, dimColor, onLinkPress, pressableLinks ✓ ✓ ✓
Input key, label, placeholder, value, submitLabel, rows, onSubmit, onInput, autoFocus ✓ ✓ ✓
Select key, label, options, value, onSelect, autoFocus ✓ ✓ ✓
Svg source berupa markup SVG hingga 131.072 karakter, teks alt, width, height, dan isInteractive ✓ ✓
Client module, key, props, width, height, flexGrow ✓ ✓
Raster key, columns hingga 512, rows hingga 256, cells. Lihat Menggambar grid sel berwarna. ✓
Image key, source seperti byte PNG atau RGBA hingga 2 MiB, atau path file, columns dan rows hingga 255, serta teks alt. Lihat terminal mana yang menggambarnya. ✓

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 digit pada band: hotkey berupa digit pada tombol di band juga terpicu saat pengguna mengetik digit tersebut saja ke dalam prompt kosong lalu berhenti sejenak
  • Band yang diciutkan: selama band diciutkan, baik pintasan action maupun hotkey tidak menekan tombol di dalamnya
  • Dua tombol dengan satu hotkey: jika dua tombol dalam satu gambar menyebutkan hotkey yang sama, tombol yang lebih belakang yang mendapatkannya
  • variant: primary atau secondary, dan nilai lain apa pun akan melempar error. Di terminal, tombol primary digambar dengan warna aksen kecuali tombol tersebut plain.
  • role: dismiss menandai tombol tutup, dan nilai lain apa pun akan melempar error. Lakukan penutupan di onPress Anda. Pada band yang berisi teks dan sebaris tombol, aplikasi Desktop dapat menggambar tombol dismiss pertama pada baris tersebut sebagai kontrol tutupnya sendiri. Terminal menggambar tombol tersebut seperti halnya tanpa role.

Button dapat berisi children sebagai pengganti label:

  • Apa saja yang dapat menjadi children: string dan elemen Text, seperti nama yang diikuti detail redup atau chip berwarna. Claude Code menolak elemen lain apa pun di dalam Button.
  • Memberi nama tombol: label memberi nama tombol dan secara default bernilai teks dari children-nya. Berikan key atau label pada tombol yang children-nya bukan satu string.
  • Di terminal: children digambar di tempat label seharusnya berada, dan tekanan di mana pun pada children tersebut dihitung sebagai satu tekanan, sehingga Anda dapat menjadikan setiap baris dalam daftar sebagai satu tombol
  • Di aplikasi Desktop dan ekstensi VS Code: tombol menggambar label-nya

[!NOTE]

Button dengan children selain satu string memerlukan Claude Code v2.1.295 atau yang lebih baru.

autoFocus hanya menerima true pada kontrol apa pun, jadi hilangkan prop tersebut untuk menonaktifkannya.

Ekstensi VS Code mengabaikan beberapa prop elemen dan menggambar elemen seolah-olah Anda tidak menyertakannya:

  • Box: position beserta top, left, right, dan bottom-nya, alignSelf, borderDimColor, dan hover
  • Text: size, mono, tabular, dan hover
  • Button: hotkey, plain, autoFocus, action, dan hover, sehingga pengguna menekan tombol di sana dengan klik, atau dengan Enter setelah tombol tersebut mendapatkan fokus. Ekstensi ini juga mengabaikan variant dan role.
  • Code: language, path, startLine, format, dan wrap, sehingga kode digambar tanpa warna atau nomor baris, dan blok format: 'diff' menampilkan teks mentah diff tersebut
  • Input dan Select: autoFocus, serta rows pada Input
  • Svg: isInteractive

Gaya border Box

Untuk menggambar border di sekeliling Box, atur borderStyle-nya ke salah satu nama berikut, seperti pada borderStyle: 'round'. Setiap baris menjelaskan apa yang digambar terminal untuk nama tersebut dan menunjukkan tepi atas border.

borderStyle Yang digambar terminal Tepi atas
'single' Garis tipis dengan sudut persegi ┌──┐
'double' Garis ganda ╔══╗
'round' Garis tipis dengan sudut membulat ╭──╮
'bold' Garis tebal ┏━━┓
'singleDouble' Garis tipis di atas dan bawah, garis ganda di sisi ╓──╖
'doubleSingle' Garis ganda di atas dan bawah, garis tipis di sisi ╒══╕
'classic' Karakter ASCII +, -, dan | +--+
'arrow' Panah yang menunjuk ke dalam Box ↘↓↓↙
'dashed' Garis putus-putus dengan sudut kosong ╌╌
'quote' Sebuah bar, ▎, di sepanjang sisi kiri dan sel kosong di tiga sisi lainnya Kosong

Box yang borderStyle-nya menyebutkan nama lain, seperti 'rounded', digambar tanpa border.

Langkah spasi Box

Prop spasi Box adalah gap, columnGap, rowGap, padding, margin, serta bentuk satu sisi dan satu sumbu dari padding dan margin, seperti paddingX dan marginTop. Masing-masing menerima jumlah sel terminal seperti gap: 1, atau nama langkah seperti gap: 'md'. Di terminal dan ekstensi VS Code, setiap langkah bernilai sejumlah sel berikut:

Langkah Sel mendatar Sel menurun
'xs' 1 0
'sm' 1 0
'md' 2 1
'lg' 3 1
'xl' 4 2

Jika Anda mengatur gap, padding, atau margin ke sebuah langkah, langkah tersebut berlaku secara mendatar dan menurun sekaligus. Misalnya, di terminal dan ekstensi VS Code, padding: 'md' berarti dua sel di setiap sisi dan satu baris di atas dan di bawah.

Nama langkah memerlukan Claude Code v2.1.299 atau yang lebih baru. Pada rilis yang lebih lama, tree yang menggunakan nama langkah tidak digambar.

Prop tipografi Text

Atur size, weight, mono, atau tabular pada Text untuk meminta aplikasi yang menggambar tree Anda menggunakan ukuran teks, ketebalan, jenis huruf monospace, atau digit dengan lebar yang sama. Sebelum Anda mengandalkan sebuah prop, periksa apa yang dilakukan terminal dan ekstensi VS Code terhadapnya. Jika suatu aplikasi mengabaikan prop yang Anda atur, tree Anda tetap digambar di sana, dengan teks seolah-olah Anda tidak menyertakan prop tersebut.

Prop Nilai Di terminal Di ekstensi VS Code
size 'caption', 'footnote', 'body', 'heading', atau 'title' Diabaikan: terminal hanya memiliki satu ukuran teks Diabaikan
weight 'regular', 'medium', 'semibold', atau 'bold' semibold dan bold digambar sebagai teks tebal semibold dan bold digambar sebagai teks tebal
mono true untuk meminta jenis huruf monospace aplikasi Diabaikan: terminal selalu monospace Diabaikan, sehingga teks tetap menggunakan jenis huruf ekstensi itu sendiri
tabular true untuk meminta digit dengan lebar yang sama, sehingga angka yang diperbarui di tempat atau kolom angka tetap sejajar Diabaikan: digit terminal sudah selebar satu sel Diabaikan

Keempat prop ini memerlukan Claude Code v2.1.299 atau yang lebih baru. Pada rilis yang lebih lama, tree yang mengatur size, weight, mono, atau tabular tidak digambar.

Mengganti bold dengan weight

bold pada Text sudah deprecated dan digantikan oleh weight, tetapi masih berfungsi. Untuk menggantinya pada Text yang tidak memiliki weight, ubah bold: true menjadi weight: 'semibold' untuk hasil yang sama pada Claude Code v2.1.299 atau yang lebih baru.

Pada rilis yang lebih lama dari v2.1.299, tree yang mengatur weight tidak digambar. Jika Anda mengatur bold dan weight sekaligus pada Text, bold tidak berpengaruh.

Batas

Hook dan panggilan API mod berjalan di bawah batas waktu dan ukuran. Claude Code melewati hook yang melampaui batas waktu. Tree yang melampaui batas kedalaman bersarang, elemen, sel Raster, atau byte Image tidak digambar.

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, atau 50 milidetik untuk hook prompt.edit
Waktu eksekusi handler .catch 1 detik
Semua hook session.end secara keseluruhan Selama anggaran hook SessionEnd, 1,5 detik kecuali Anda mengubahnya, dihitung sejak hook SessionEnd di pengaturan Anda selesai
Timeout $.process.run 30 detik secara default, paling lama 10 menit
stdout dan stderr $.process.run Masing-masing 4 MiB. isStdoutTruncated atau isStderrTruncated bernilai true jika salah satunya dipotong.
maxTokens $.model.complete 1024 secara default, hingga 64.000 atau batas output model
$.fs.read dan $.fs.write 4 MiB untuk satu file
Body permintaan $.http.fetch 4 MiB, dihitung dalam karakter. Panggilan dengan body yang lebih besar akan ditolak (reject).
Body respons $.http.fetch 4 MiB. text berisi 4 MiB pertama dan sisanya tidak dibaca. Ketika header Content-Length menyatakan ukuran yang lebih besar, panggilan tersebut justru ditolak (reject), dengan alasan yang diakhiri is over the 4194304-byte limit, kecuali jika permintaan terakhir setelah semua redirect menggunakan metode HEAD. Pengecualian HEAD memerlukan Claude Code v2.1.296 atau yang lebih baru.
Satu panggilan $.http.fetch, termasuk redirect dan body 30 detik
Redirect yang diikuti oleh satu panggilan $.http.fetch 5
Alasan drop dari hook atau alasan deny dari config.set 4.096 karakter. Bagian akhir dari alasan yang lebih panjang dipotong, dan drop atau deny tetap berlaku. Pemotongan ini memerlukan Claude Code v2.1.292 atau yang lebih baru, dan pada versi sebelumnya hook tersebut gagal sebagai gantinya.
Teks dalam satu tree 100.000 karakter pertama yang digambar
language atau path dari Code, value dari opsi Select, atau module dari Client 10.000 karakter. Jika salah satunya lebih panjang, hook ui.render yang mengembalikannya gagal.
href dari Link 2.048 karakter. Jika lebih panjang, hook ui.render yang mengembalikannya gagal.
Kedalaman bersarang satu tree 32 level di bawah elemen root
Elemen dan anak teks dalam satu tree 20.000
Sel Raster dalam satu tree, yaitu columns dikali rows dari setiap Raster 262.144
Byte PNG atau RGBA dari semua Image dalam satu tree 2 MiB
$.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 }. Di renderer klasik, toast yang lebih baru dari sebuah mod dapat menggantikan toast lamanya yang sedang ditampilkan atau menunggu untuk ditampilkan.
Panel yang dibuka tanpa diminta pengguna Ditempatkan mulai dari 144 kolom terminal, 110 setelah pengguna pernah membukanya sekali
Baris dari $.ui.place yang dimiliki satu mod dalam satu percakapan pada satu waktu 500. Saat batas tercapai, panggilan dengan id baru akan resolve menjadi { isPlaced: false, reason: 'a plugin holds at most 500 placed rows' }.
Kedalaman bersarang argumen panggilan API mod 28.000 level. Melewati batas itu, panggilan ditolak (reject) dengan pesan yang diakhiri nesting deeper than 28000 levels is not supported. Memerlukan Claude Code v2.1.299 atau yang lebih baru.
Kedalaman bersarang event yang diubah dan diteruskan ke next, di luar hook async generator seperti hook pada turn.step 28.000 level. Melewati batas itu, next ditolak (reject) dengan pesan yang diakhiri nesting deeper than 28000 levels is not supported. Memerlukan Claude Code v2.1.299 atau yang lebih baru.
Kedalaman bersarang nilai kembalian hook, di luar ui.render, ui.resolve, dan hook async generator 28.000 level. Melewati batas itu, hasil hook ditolak, dan pemberitahuan yang melaporkannya menyertakan nesting deeper than 28000 levels is not supported. Memerlukan Claude Code v2.1.299 atau yang lebih baru.
Cakupan, seperti fungsi, blok, dan loop, yang bersarang satu di dalam yang lain dalam satu file modul hook 2.000
Nama perintah, tool, tipe subagent, dan panel, serta id dari baris yang ditempatkan atau backdrop 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, dalam sesi yang kredensialnya bukan /login 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 menjalankan hook-nya. 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 dalam sesi yang kredensialnya adalah /login 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