Tab-tab tersebut adalah dua tombol dalam satu baris. Mod melacak mana yang aktif dan menggambar konten tab tersebut di bawah baris.

1. Buat plugin

Mod adalah plugin dengan manifest, hooks.json yang menunjuk ke kode Anda, dan file kode. Buat mod menjelaskan masing-masing. Buat direktori bernama hello-tabs dengan direktori .claude-plugin dan hooks di dalamnya, kemudian simpan dua file pertama.

Simpan manifest sebagai hello-tabs/.claude-plugin/plugin.json:

{
  "name": "hello-tabs",
  "version": "0.1.0",
  "description": "Opens a pane with two tabs and a counter",
  "author": { "name": "Your Name" }
}

Beri nama titik masuk Anda di hello-tabs/hooks/hooks.json:

{
  "modules": ["./register.js"]
}

2. Tulis kodenya

Daftar ini menjelaskan apa yang dilakukan setiap hook, sesuai urutan kemunculannya dalam kode:

• Menambahkan perintah /hello-tabs, dan memuat hitungan yang disimpan sesi sebelumnya
• Membuka panel saat Anda menjalankan perintah tersebut
• Menggambar konten panel: baris tab dan badan tab yang terbuka

Dua variabel tingkat modul, tab dan count, menyimpan status panel.

Simpan ini sebagai hello-tabs/hooks/register.js:

// ID panel, digunakan untuk membuka panel dan mengenalinya saat menggambar
const PANE = 'hello-tabs'

// Apa yang ditampilkan panel: tab mana yang terbuka, dan nilai penghitung
let tab = 'one'
let count = 0

export function register(on) {
  // Berjalan sebelum prompt pertama Anda, dan lagi setelah reload
  on('session.start', async ($, e, next) => {
    await $.command.register({ name: 'hello-tabs', description: 'Open the hello-tabs pane' })
    // Muat hitungan yang disimpan sesi sebelumnya, jika ada
    const saved = await $.store.get('count')
    if (typeof saved === 'number') count = saved
    return next(e)
  })

  // Berjalan saat Anda mengetik /hello-tabs
  on('command.run', { command: 'hello-tabs' }, async ($) => {
    // Buka panel, berikan keyboard, dan biarkan Esc menutupnya
    await $.ui.open({ id: PANE, title: 'Hello tabs', focus: true, closeOnEscape: true })
    // Cetak tidak ada dalam transkrip
    return {}
  })

  // Berjalan setiap kali Claude Code menggambar panel
  on('ui.render', { component: 'Pane' }, async ($, e, next) => {
    // Biarkan panel mod lain saja
    if (e.requestId !== PANE) return next(e)
    // Dapatkan elemen yang dapat digambar aplikasi ini
    const { Box, Text, Button } = $.ui.resolve(e)
    // Minta Claude Code menjalankan hook ini lagi
    const redraw = () => $.ui.invalidate('ui.render')

    // Satu tab: tombol yang beralih ke tabnya saat ditekan
    const tabButton = (name, label, hotkey) =>
      Button({
        key: 'tab-' + name,
        label,
        hotkey,
        plain: true,
        // Redup tab yang tidak terbuka
        dimColor: tab !== name,
        onPress: () => {
          tab = name
          redraw()
        },
      })

    // Apa yang ada di bawah tab, tergantung mana yang terbuka
    const body =
      tab === 'one'
        ? [Text({ children: ['This is the first tab.'] })]
        : [
            Box({
              flexDirection: 'row',
              columnGap: 2,
              children: [
                Button({
                  key: 'more',
                  label: 'Add one',
                  hotkey: 'a',
                  onPress: async () => {
                    count += 1
                    redraw()
                    // Simpan hitungan sehingga ada setelah restart
                    await $.store.set('count', count)
                  },
                }),
                Text({ children: ['Count: ' + count] }),
              ],
            }),
          ]

    // Seluruh panel: baris tab, baris kosong, kemudian badan
    return Box({
      flexDirection: 'column',
      children: [
        Box({
          flexDirection: 'row',
          columnGap: 3,
          children: [tabButton('one', 'One', '1'), tabButton('two', 'Two', '2')],
        }),
        Text({ children: [' '] }),
        ...body,
      ],
    })
  })
}

Setiap hook juga melakukan sesuatu yang tidak jelas dari kode:

• session.start juga membaca hitungan yang disimpan dari $.store, penyimpanan kunci-nilai yang bertahan antar sesi.
• command.run hanya memberi tahu Claude Code bahwa panel ada. Membuka panel tidak menggambar apa pun dengan sendirinya: Claude Code kemudian menaikkan ui.render untuk menanyakan apa yang ada di dalamnya.
• ui.render mengembalikan pohon elemen, Box yang menyimpan kotak lain, teks, dan tombol, dan membangunnya lagi dari tab dan count setiap kali berjalan.

Menekan tombol menjalankan callback onPress-nya, yang mengubah variabel dan memanggil redraw. Claude Code kemudian menjalankan hook ui.render lagi, dan hook membangun pohon baru dari nilai baru. Setiap gambar interaktif menggunakan siklus render itu: callback mengubah status, dan hook merender lagi dari status baru.

3. Buka panel

Di shell Anda, mulai Claude Code dengan claude --plugin-dir ./hello-tabs. Di prompt Claude Code, jalankan /hello-tabs. Panel terbuka dengan 1: One dan 2: Two di seluruh bagian atas. Tekan 2, kemudian tekan a, pintasan keyboard untuk Add one, beberapa kali. Hitungan naik.

4. Periksa bahwa hitungan disimpan

Tekan Esc untuk menutup panel, kemudian keluar dari sesi. Di shell Anda, mulai Claude Code lagi dengan perintah claude --plugin-dir ./hello-tabs yang sama, dan di prompt Claude Code jalankan /hello-tabs. Hitungan ada di mana Anda meninggalkannya.

Untuk menghapus hitungan, buat mod memanggil $.store.delete('count'). Jaga status mencakup berapa lama setiap jenis nilai bertahan.

Pilih di mana menggambar

Hook ui.render berjalan untuk setiap render site kecuali Anda mempersempit ke yang Anda inginkan. Untuk memilih render site, teruskan filter, disebut matcher, sebagai argumen kedua ke on. { component: 'Pane' } menjalankan hook hanya untuk panel. Dalam hook, e.component menamai situs, e.surface mengatakan aplikasi mana yang menggambar, dan e.props menyimpan data situs sendiri. Untuk panel, e.requestId adalah id yang Anda buka dengannya.

Panel dan pita kosong sampai mod mengisinya. Pilih tab untuk melihat apa itu masing-masing dan cara menggambar di dalamnya:

[tab] Pane

Panel adalah sidebar di samping transkrip dalam terminal fullscreen yang lebar, atau wilayah berbingkai di atas prompt sebaliknya. Dengan beberapa panel terbuka, masing-masing mendapat tab yang menampilkan judulnya.

Panel muncul saat mod Anda memanggil $.ui.open dengan id yang Anda pilih, seperti dalam $.ui.open({ id: 'hello-tabs' }). Buka panel pada waktu yang tepat mencakup bidang lain dan kapan panel menunggu terminal yang lebih lebar.

Untuk menggambar di panel Anda, filter pada { component: 'Pane' } dan periksa bahwa e.requestId adalah id Anda.

[tab] Band above the prompt

Pita adalah strip langsung di atas input prompt. Selalu ada, dan setiap mod berbaginya.

Hook Anda mengembalikan pohon untuk menampilkan sesuatu di pita, atau next(e) untuk menampilkan tidak ada. Pohon menggantikan apa yang mod setelah Anda gambar di sana. Untuk menjaga milik mereka, letakkan hasil await next(e) di antara anak-anak Box dalam pohon Anda.

Untuk menggambar di pita, filter pada { component: 'AbovePrompt' }.

Ubah apa yang sudah digambar Claude Code

Claude Code menggambar sebagian besar antarmukanya sendiri: pesan, baris panggilan tool, spinner, dan lainnya. Masing-masing bagian itu adalah render site juga, jadi mod dapat mengubah gaya atau menggantinya. Untuk mengubah satu, filter hook ui.render Anda pada namanya dari tabel ini:

Pane, AskUserQuestion, Spinner, UserMessage, AssistantMessage, dan titik render panggilan tool bekerja di terminal, aplikasi Desktop, dan ekstensi VS Code. Tabel titik render mencantumkan di mana masing-masing titik render lainnya dimunculkan.

Di situs yang sudah digambar Claude Code, hook Anda dapat mengubah detail, mengganti gambar, atau membiarkannya. Pilih tab untuk melihat masing-masing diterapkan pada spinner. Contoh membaca variabel calls yang hook lain hitung, seperti dalam mod tutorial.

[tab] Change a detail

Untuk menjaga gambar Claude Code dan mengubah satu bagian darinya, teruskan next salinan event dengan props yang diubah. Hook ini mengubah teks setelah kata spinner:

on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
  // Jaga spinner Claude Code, dan ubah teks setelah katanya
  return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
})

Spinner menjaga animasi dan katanya, dan teks Anda mengikuti kata:

Thinking · tool calls: 2…

[tab] Replace the drawing

Untuk menggambar sesuatu milik Anda sendiri di tempat situs, kembalikan pohon dan jangan panggil next. Hook ini menggambar satu baris teks di mana spinner akan berada:

on('ui.render', { component: 'Spinner' }, async ($, e) => {
  const { Text } = $.ui.resolve(e)
  // Tidak ada panggilan ke next, jadi baris ini digambar di tempat spinner
  return Text({ children: ['Claude has made ' + calls + ' tool calls'] })
})

Saat Claude bekerja, baris Anda menampilkan dan spinner Claude Code tidak:

Claude has made 2 tool calls

[tab] Leave it alone

Untuk meninggalkan situs seperti yang digambar Claude Code, kembalikan next(e). Hook sering melakukan itu untuk beberapa event dan tidak untuk yang lain. Hook ini meninggalkan spinner saja sampai ada panggilan untuk dihitung:

on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
  // Tidak ada yang ditampilkan dulu, jadi teruskan event tanpa perubahan
  if (calls === 0) return next(e)
  return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
})

Sebelum panggilan tool pertama, spinner terlihat seperti tanpa mod:

Thinking…

Di situs-situs ini, next(e) mengembalikan referensi ke gambar Claude Code, { type: 'engine', ref }, kecuali mod yang berjalan setelah milik Anda mengembalikan pohonnya sendiri. Untuk mengubah isi gambar tersebut, teruskan next salinan event dengan props yang berbeda, seperti yang dilakukan tab Change a detail. Anda dapat mengembalikan referensi apa adanya, atau menempatkannya dalam Box di samping elemen Anda sendiri:

on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
  const { Box, Text } = $.ui.resolve(e)
  const theirs = await next(e)
  return Box({ flexDirection: 'column', children: [theirs, Text({ children: ['under the spinner'] })] })
})

Saat Claude bekerja, spinner beranimasi seperti sebelumnya, dan under the spinner muncul di bawahnya.

Dialog izin bukan render site, jadi mod tidak dapat mengubah apa yang ditampilkannya. Dialog pertanyaan, AskUserQuestion, adalah satu, jadi mod dapat mengubah itu. Pohon untuk dialog tersebut harus memuat referensi tepat satu kali, dengan elemen Anda di atasnya. Jika tidak, Claude Code menggambar dialognya sendiri.

Buka panel pada waktu yang tepat

Panel hanya muncul saat mod Anda membukanya. Bagaimana dan kapan Anda membukanya menentukan apakah itu mengambil fokus keyboard, berapa banyak ruang yang dimintanya, dan apakah itu menampilkan sama sekali di terminal yang sempit.

Untuk membuka panel, panggil $.ui.open dengan id yang Anda pilih. id adalah nama panel: hook ui.render Anda memeriksanya, dan Anda meneruskannya lagi untuk menutup panel.

await $.ui.open({ id: 'hello-tabs', title: 'Hello tabs', focus: true })

Untuk menutup panel, panggil $.ui.close dengan id yang Anda buka dengannya:

await $.ui.close({ id: 'hello-tabs' })

Selain id, $.ui.open mengambil bidang opsional ini:

Ekstensi VS Code mengabaikan rows dan columns dan menentukan ukuran panel sendiri.

focus, closeOnEscape, dan holdToasts bersifat opsional dan hanya menerima true. Untuk menghilangkan satu, hilangkan saja. Melewatkan false melempar kesalahan seperti ui.open: focus is true or left out. Untuk menetapkan salah satu dari mereka secara kondisional, tambahkan bidang hanya ketika kondisi berlaku. Panggilan ini meminta fokus keyboard hanya ketika items tidak kosong:

const pane = { id: 'hello-tabs', title: 'Hello tabs' }
await $.ui.open(items.length > 0 ? { ...pane, focus: true } : pane)

Untuk membiarkan perintah membuka panel saat Claude bekerja, tambahkan immediate: true saat Anda mendaftarkan perintah. Tanpanya, perintah yang diketik selama giliran menunggu giliran berakhir.

Tahan toast di balik dialog

Teruskan holdToasts: true ke $.ui.open ketika panel adalah dialog yang dijawab pengguna lalu ditinggalkan, sehingga toast tidak muncul saat mereka memutuskan. Di terminal, penahanan berlangsung selama panel tersebut yang sedang ditampilkan, dan toast yang dimunculkan dalam waktu itu menunggu sampai penahanan berakhir.

Claude Code menahan toast dari mod lain dan notifikasi singkatnya sendiri, serta toast yang dimunculkan mod Anda dengan $.ui.toast. Jangan gunakan bidang ini pada panel yang tetap terbuka, sehingga pengguna tetap melihatnya.

Ketika panel menunggu terminal yang lebih lebar

Panel yang dibuka mod Anda tanpa diminta tidak muncul di terminal sempit, jadi tidak dapat mengambil alih layar kecil. Apakah itu muncul tergantung pada apa yang membukanya:

• Dibuka oleh sesuatu yang dilakukan pengguna, seperti perintah yang mereka jalankan atau tombol yang mereka tekan, panel muncul pada lebar apa pun
• Dibuka oleh mod Anda bertindak sendiri, seperti dari timer atau hook turn.start, panel hanya muncul di terminal setidaknya 144 kolom lebar. Setelah pengguna telah membuka panel itu sendiri sekali, 110 kolom cukup.

Ketika panel muncul, $.ui.open diselesaikan ke { isPlaced: true }. Ketika panel menunggu, isPlaced adalah false dan reason adalah string yang mengatakan mengapa. Panel yang menunggu muncul saat pengguna membukanya atau memperlebar terminal. Untuk mengatakan sesuatu tersedia tanpa membuka panel, panggil $.ui.toast('Your message'), yang menampilkan notifikasi toast.

Menggambar di ekstensi VS Code

Di ekstensi VS Code, apa yang digambar mod muncul di panel obrolan dengan ekstensi versi 2.1.299 atau lebih baru. Sesi yang tidak mengambil feature flag, seperti sesi di Amazon Bedrock, memerlukan versi 2.1.304 atau lebih baru. Dalam hook ui.render untuk panel tersebut, e.surface adalah vscode. Untuk memeriksa titik render dan elemen mana yang digambar panel, dan prop mana yang diabaikannya, lihat tabel titik render dan elemen.

Agar mod bekerja di panel obrolan maupun di terminal, perhatikan perbedaan berikut:

• Panel: di panel obrolan dengan lebar 800 piksel atau lebih, panel menempel di samping percakapan, e.props.placement adalah 'dock', dan e.viewport.isFullscreen adalah true. Di panel obrolan yang lebih sempit, panel digambar di atas kotak prompt, placement adalah 'inline', dan panel menampilkan 12 baris sebelum dapat digulir.
• Toast dan baris status: keduanya berada dalam satu tumpukan tepat di atas kotak prompt, bersama dengan panel ketika panel obrolan sempit, dengan satu baris status per mod. Tumpukan ini disembunyikan selama permintaan izin atau dialog ditampilkan.
• Label: panel obrolan membingkai apa yang digambar atau ditulis ulang oleh mod dan memberinya label dengan nama plugin, seperti From the token-chart plugin atau Edited by the token-chart plugin.
• Keyboard: tombol tidak memiliki hotkey, sehingga pengguna mengklik tombol atau menekan Enter padanya setelah tombol tersebut mendapat fokus.
• Fokus keyboard: panel obrolan mengabulkan permintaan focus: true dari sebuah panel hanya ketika panel obrolan memiliki fokus, Claude sedang idle tanpa pertanyaan yang menunggu, dan kotak prompt kosong.
• Dialog pertanyaan: di AskUserQuestion, panel obrolan mempertahankan kartu pertanyaannya sendiri dan menggambar elemen Anda di atasnya. Prop yang Anda teruskan ke next tidak mengubah kartu tersebut.
• Saran prompt: $.prompt.suggest diselesaikan dengan isShown: false dan tidak menampilkan apa pun, karena panel obrolan menyimpan teks saran redup di kotak prompt untuk saran Claude sendiri.
• Batas teks: panel obrolan memotong baris status pada 200 karakter atau dua baris, dan toast pada 500 karakter.

Bangun pohon dari elemen

Apa yang dikembalikan hook ui.render adalah pohon elemen: deskripsi apa yang akan digambar, terbuat dari kotak, teks, dan kontrol bersarang di dalam satu sama lain. Anda mendeskripsikan gambar, dan Claude Code merendernya di aplikasi mana pun yang dibuka pengguna: terminal, aplikasi Desktop, atau ekstensi VS Code.

Untuk mendapatkan elemen, panggil $.ui.resolve(e) dalam hook Anda, seperti dalam const { Box, Text, Button } = $.ui.resolve(e). Setiap elemen adalah fungsi. Anda meneruskan prop, dan Anda menempatkan elemen dan string yang ada di dalamnya dalam children.

Pilih tab untuk melihat setiap elemen yang paling umum dan cara terminal menggambarnya:

[tab] Text

Text menggambar string, dengan gaya opsional seperti bold dan color:

Text({ children: ['This is the first tab.'] })

This is the first tab.

[tab] Box

Box mengatur apa yang ada di dalamnya, dalam baris atau kolom. Ini menempatkan tombol dan baris teks berdampingan, dua kolom terpisah:

Box({
  flexDirection: 'row',
  columnGap: 2,
  children: [
    Button({ key: 'more', label: 'Add one', onPress: addOne }),
    Text({ children: ['Count: 0'] }),
  ],
})

[ Add one ]  Count: 0

[tab] Button

Button adalah kontrol yang dapat ditekan pengguna. Ini menjalankan callback onPress Anda. Dengan plain: true tidak memiliki tanda kurung dan menampilkan pintasan keyboard:

Button({ key: 'more', label: 'Add one', onPress: addOne })
Button({ key: 'tab-one', label: 'One', hotkey: '1', plain: true, onPress: showTabOne })

[ Add one ]
1: One

[tab] Input

Input adalah bidang teks. Ini menjalankan callback onSubmit Anda dengan teks saat pengguna menekan Enter:

Input({
  key: 'new-note',
  label: 'Note',
  placeholder: 'Type a note and press Enter',
  value: '',
  submitLabel: 'add',
  onSubmit: addNote,
})

Note: Type a note and press Enter

Atur rows ke 2 atau lebih untuk bidang yang menampung beberapa baris.

Galeri antarmuka memiliki contoh dan tangkapan layar dari sebagian besar elemen. Tabel ini mencantumkan setiap elemen:

Jika modul Anda adalah file .tsx atau .jsx, Anda dapat menulis pohon sebagai JSX. Dekonstruksi elemen dari $.ui.resolve(e) terlebih dahulu.

Jika gambar Anda tidak muncul, periksa pohonnya untuk prop yang tidak diambil oleh elemen atau anak di tempat yang tidak seharusnya ada. Hook yang mengembalikan pohon seperti itu gagal, dan baris hook skipped menyebutkan mod Anda dan aturan yang dilanggar pohon tersebut. Untuk Text di panel dengan prop bernama bogusProp, baris itu berbunyi:

my-mod: ui.render hook skipped: returned the wrong shape (a tree Pane refuses: Text prop "bogusProp" is not allowed)

Link di aplikasi Desktop dan VS Code

Di aplikasi Desktop dan ekstensi VS Code, Link digambar sebagai teks biasa kecuali href-nya memenuhi persyaratan berikut:

• Skema dan host: URL https:, atau URL http://localhost seperti http://localhost:3000
• Tanpa @: tulis @ di path atau query sebagai %40
• Ejaan: apa yang dikembalikan new URL(href).href, selain / yang tidak ada setelah host. Hal itu mengecualikan host dengan huruf besar, spasi, dan :443 pada URL https:.

Di terminal, persyaratan ini tidak berlaku.

Saat Client gagal

Di terminal, saat file yang dijalankan Client gagal, baris redup seperti my-mod: Client client/spinner.js: boom menggantikan tempat Client, dan sisa gambar Anda tetap ditampilkan.

Jika mod Anda menangani ui.fault, Claude Code kemudian menggambar situs lagi.

Gambar grid sel berwarna

Untuk peta panas, sparkline, atau papan permainan di terminal, gambar satu Raster dan bukan Box untuk setiap sel. Raster mengambil key, ukurannya dalam columns dan rows, dan cells, string base64 yang mengemas setiap sel. Setiap sel adalah tiga angka: titik kode karakter, warnanya, dan warna latar belakangnya. Warna adalah nilai RGB 24-bit dalam heksadesimal, seperti 0xc62828 untuk merah. Nilai 0x01000000, satu di atas rentang tersebut, berarti default terminal.

Aplikasi selain terminal tidak memiliki Raster, jadi periksa e.surface dan gambar teks di sana. Badan panel ini menggambar peta panas tiga kali dua:

// The value that means "use the terminal's default color"
const DEFAULT_COLOR = 0x01000000

// Pack rows of [character, color] pairs into the one string a Raster takes
// One cell is three numbers: the character's code point, its color, and its background
function cellsOf(rows) {
  const numbers = rows.flat().flatMap(([char, color]) => [char.codePointAt(0), color, DEFAULT_COLOR])
  return new Uint8Array(Uint32Array.from(numbers).buffer).toBase64()
}

on('ui.render', { component: 'Pane' }, async ($, e, next) => {
  // Draw only in the pane opened with the id 'heat'
  if (e.requestId !== 'heat') return next(e)
  const { Box, Text, Raster } = $.ui.resolve(e)
  // Two rows of three cells, each a block character and its color
  const rows = [
    [['█', 0x2e7d32], ['█', 0xf9a825], ['█', 0xc62828]],
    [['█', 0x2e7d32], ['█', 0x2e7d32], ['█', 0xf9a825]],
  ]
  if (e.surface !== 'terminal') {
    return Text({ children: ['The heat map needs the terminal.'] })
  }
  return Box({
    flexDirection: 'column',
    children: [Raster({ key: 'grid', columns: 3, rows: 2, cells: cellsOf(rows) })],
  })
})

Di terminal, panel menampilkan grid:

Array rows adalah bagian yang akan Anda ubah, dan cellsOf mengubahnya menjadi string yang dikemas. Hook menggambar hanya di panel yang id-nya adalah heat, jadi buka satu dengan $.ui.open({ id: 'heat' }) dari perintah, seperti contoh hello-tabs membuka panelnya.

Setiap karakter harus lebar satu sel. Untuk menganimasikan Raster yang sudah di layar, panggil $.ui.blit dengan id panel sebagai requestId, key Raster, ukuran yang sama, dan sel baru. Untuk contoh ini, itu adalah $.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) }). Itu melukis ulang elemen itu saja tanpa menjalankan hook ui.render Anda lagi.

Merespons penekanan dan pengetikan

Ketika pengguna menekan tombol, mengetik ke bidang, atau memilih dari daftar yang digambar mod Anda, Claude Code memanggil callback kontrol itu, yang berjalan dalam modul Anda. Setiap kontrol mengambil callback-nya sendiri:

• Button: mengambil onPress(e), di mana e.surface adalah aplikasi tempat penekanan berasal
• Input: mengambil onSubmit(value) dan onInput(value)
• Select: mengambil onSelect(value) dengan pilihan dalam options, daftar setidaknya satu pilihan dengan nilai unik, seperti [{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]

Kontrol mana yang memerlukan key

Berikan prop key pada setiap Input dan Select, seperti key: 'size'. Button boleh tidak memiliki key ketika memiliki prop label atau satu anak berupa string. Key-nya kemudian adalah nilai label atau string tersebut.

Tes dan mod lain mengidentifikasi kontrol berdasarkan key-nya:

• Tes: sebuah tes menekan atau mengetik ke kontrol berdasarkan key-nya.
• Mod lain: Claude Code menembakkan ui.press, ui.input, atau ui.select dengan key kontrol dalam e.element sebelum menjalankan callback kontrol tersebut. Hook mod lain untuk event tersebut melihat apa yang pengguna ketik ke Input Anda dan dapat mengubah teks itu atau mencegah callback Anda berjalan. API mods tidak memberi mod tersebut metode untuk menekan tombol Anda.

Jika sebuah pesan mengatakan needs a key atau is drawn twice, temukan penyebabnya berdasarkan pesan tersebut.

Fokus keyboard dan pintasan keyboard

Mod Anda tidak pernah membaca keyboard itu sendiri. Pengguna menekan kunci, Claude Code memutuskan kontrol mana yang dimaksudkan, dan callback kontrol itu berjalan. Kecuali untuk pintasan keyboard digit di pita atau pengikatan action, itu hanya terjadi saat panel atau pita Anda memiliki fokus keyboard. Sisa waktu, kunci pergi ke prompt.

Di ekstensi VS Code, tombol tidak memiliki pintasan keyboard: pengguna mengklik tombol atau menekan Enter padanya, dan mengetik ke bidang.

Bagaimana panel mendapat fokus keyboard

Panel mendapat fokus keyboard ketika:

• Mod Anda membukanya dengan focus: true dari perintah atau penekanan
• Pengguna menekan Ctrl+X kemudian Tab
• Pengguna mengkliknya, yang di terminal memerlukan rendering layar penuh

Claude Code memberikan focus: true hanya saat prompt kosong dan tidak ada yang lain memiliki fokus keyboard. Panel yang terbuka saat pengguna mengetik tidak mengambil keystroke mereka.

Apa yang dilakukan setiap kunci

Tabel ini mencantumkan apa yang dilakukan kunci saat panel atau pita Anda memiliki fokus keyboard:

Mod tidak dapat mengikat Tab atau tombol panah ke apa pun yang lain, jadi permainan mengarahkan dengan w, a, s, dan d.

Atur pintasan keyboard dan fokus pertama

• hotkey: untuk membiarkan pengguna menekan Button dengan satu kunci, berikan hotkey dari satu digit atau satu huruf kecil, seperti dalam hotkey: 'a'
• autoFocus: untuk memilih kontrol mana yang memiliki fokus saat panel terbuka, tambahkan autoFocus: true ke dalamnya. Di ekstensi VS Code, autoFocus tidak melakukan apa-apa: kontrol digambar seolah-olah Anda tidak menyertakannya, dan Anda tidak perlu mengubah apa pun. Prop ini hanya menerima true, jadi hilangkan pada kontrol lainnya.

Bagaimana pintasan keyboard ditampilkan tergantung pada tombol dan aplikasi:

Di terminal, beri nama kunci dalam label tombol berbingkai, atau gunakan plain: true, sehingga pengguna dapat melihat apa yang harus ditekan. Referensi elemen memiliki aturan Button lainnya: action, pintasan keyboard digit di pita, dan dua tombol pada satu pintasan keyboard.

Saat pengguna menciutkan pita

Di terminal, saat mod menggambar di pita, pengguna dapat menciutkan pita menjadi satu baris agar tidak menghalangi:

• Klik [-]: saat pita dibentangkan, Claude Code menggambar tanda ini di ujung kanan baris pertamanya. Dalam rendering layar penuh, pengguna mengkliknya untuk menciutkan pita.
• Tekan Ctrl+X kemudian Ctrl+A: ini berfungsi baik saat prompt, pita, atau panel yang memiliki fokus keyboard. Pengguna dapat mengikat kunci lain ke sini melalui aksi abovePrompt:toggle.

Pita yang diciutkan menyembunyikan semua yang digambar mod di sana dan sebagai gantinya menampilkan satu baris redup, yang menyebutkan kunci untuk membentangkannya sesuai pengikatan yang dimiliki pengguna:

▸ plugin panel hidden · ctrl+x ctrl+a or click to show

Kunci yang sama, atau dalam rendering layar penuh sebuah klik pada baris tersebut, membentangkan pita kembali. Sampai saat itu, tidak ada yang menekan tombol di dalamnya: tidak ada pintasan keyboard, tidak ada digit yang diketik ke prompt kosong, dan tidak ada pintasan keyboard untuk action sebuah tombol. Jika pita memiliki fokus keyboard saat pengguna menciutkannya, fokus kembali ke prompt, dan Ctrl+X kemudian Tab melewati pita selama pita diciutkan.

Pita tetap diciutkan sampai pengguna membentangkannya, bahkan setelah /clear, dan dibentangkan kembali saat Claude Code dimulai berikutnya. Mod Anda tidak dapat membentangkannya atau mengetahui bahwa pita sedang diciutkan: hook ui.render tetap berjalan, dan tidak ada apa pun dalam e.props yang menunjukkannya. Jangan jadikan pita sebagai satu-satunya tempat mod Anda menampilkan sesuatu yang harus dijawab pengguna.

Ambil input yang diketik dan gambar baris untuk setiap item

Banyak panel adalah bidang teks dengan daftar di bawahnya. Contoh di bagian ini adalah panel catatan: Anda mengetik catatan dan menekan Enter untuk menambahkannya, dan setiap catatan memiliki tombol x yang menghapusnya. Dengan dua catatan ditambahkan, terminal menggambar panel dengan cara ini:

╭────────────────────────────────────────────────────────✕─╮
│ Note: Type a note and press Enter ⏎ add                  │
│ x buy milk │
│ x call bob │
╰──────────────────────────────────────────────────────────╯

✕ di batas atas adalah tanda milik Claude Code sendiri untuk menutup panel.

Contoh menggunakan teknik berikut:

• Ambil input yang diketik: Input memanggil onSubmit(value) dengan teks bidang saat pengguna menekan Enter, dan onInput(value) pada setiap perubahan
• Gambar daftar: petakan data Anda ke satu baris masing-masing, dan berikan setiap tombol baris key-nya sendiri

Hook ini menggambar konten panel:

// Daftar yang digambar panel
let notes = []

on('ui.render', { component: 'Pane' }, async ($, e, next) => {
  // Gambar hanya di panel yang dibuka dengan id 'notes'
  if (e.requestId !== 'notes') return next(e)
  const { Box, Text, Button, Input } = $.ui.resolve(e)
  const redraw = () => $.ui.invalidate('ui.render')

  return Box({
    flexDirection: 'column',
    children: [
      Input({
        key: 'new-note',
        label: 'Note',
        placeholder: 'Type a note and press Enter',
        // Teks awal bidang
        value: '',
        submitLabel: 'add',
        autoFocus: true,
        // Berjalan saat Anda menekan Enter di bidang
        onSubmit: async (value) => {
          // Abaikan baris kosong
          if (!value.trim()) return
          notes = [...notes, value.trim()]
          redraw()
          await $.store.set('notes', notes)
        },
      }),
      // Satu baris untuk setiap catatan: tombol hapus, kemudian teks catatan
      ...notes.map((note, i) =>
        Box({
          flexDirection: 'row',
          columnGap: 1,
          children: [
            Button({
              // Kunci miliknya sendiri, jadi setiap tombol baris dapat dibedakan
              key: 'delete-' + i,
              label: 'x',
              plain: true,
              onPress: async () => {
                notes = notes.filter((_, j) => j !== i)
                redraw()
                await $.store.set('notes', notes)
              },
            }),
            Text({ children: [note] }),
          ],
        }),
      ),
    ],
  })
})

Untuk mencoba panel:

• Tambahkan catatan: ketik baris dan tekan Enter. Baris muncul sebagai baris baru, dan bidang kosong.
• Hapus catatan: tekan Tab sampai tombol x catatan memiliki fokus, kemudian tekan Enter. x adalah label tombol dan bukan pintasan keyboard, jadi mengetik huruf tidak menekan itu.

Setiap perubahan mengikuti siklus render yang sama seperti hello-tabs: callback mengubah notes, memanggil redraw, dan menyimpan daftar ke $.store. Jika hook Anda menggambar panel lagi saat pengguna sedang mengetik catatan, bidang mempertahankan teks mereka selama hook meneruskan value yang sama setiap kali. Untuk mengganti teks mereka dengan teks Anda sendiri, teruskan value yang berbeda.

Contoh menyimpan catatan dan tidak memuatnya. Untuk membawanya kembali di sesi berikutnya, bacalah dalam hook session.start, cara hello-tabs membaca count.

Prop berikut membentuk baris bidang, Note: Type a note and press Enter ⏎ add:

Mengirimkan Input tidak memulai giliran kecuali callback Anda memanggil $.prompt.submit.

Gambar ulang situs

Gambar adalah snapshot: itu menunjukkan apa yang dikembalikan hook ui.render Anda terakhir kali hook berjalan. Untuk menampilkan sesuatu yang baru, hook harus berjalan lagi. Claude Code menjalankannya lagi untuk beberapa perubahan, dan mod Anda meminta sisanya.

Ketika Claude Code menggambar ulang tanpa diminta

Claude Code menjalankan hook ui.render Anda lagi ketika prop situs berubah atau lebar terminal berubah. Ketika sebuah Client di situs gagal dan mod Anda menangani ui.fault, Claude Code menjalankan hook sekali lagi setelah hook ui.fault Anda kembali, sehingga hook ui.render Anda dapat menghilangkan Client tersebut. Itu tidak menjalankan hook pada timer, dan itu tidak dapat mengatakan ketika variabel dalam modul Anda berubah.

Gambar ulang saat data Anda berubah

Untuk memiliki situs Anda digambar lagi setelah data Anda sendiri berubah, panggil $.ui.invalidate('ui.render'). Panel ini menghitung penekanan. Callback tombol mengubah count, kemudian meminta redraw:

let count = 0

on('ui.render', { component: 'Pane' }, async ($, e, next) => {
  if (e.requestId !== 'counter') return next(e)
  const { Box, Text, Button } = $.ui.resolve(e)
  return Box({
    flexDirection: 'row',
    columnGap: 2,
    children: [
      Button({
        key: 'more',
        label: 'Add one',
        onPress: () => {
          count += 1
          // Data berubah, jadi minta Claude Code menggambar panel lagi
          $.ui.invalidate('ui.render')
        },
      }),
      Text({ children: ['Count: ' + count] }),
    ],
  })
})

Setiap penekanan menaikkan angka di panel. Contoh hello-tabs membungkus panggilan yang sama dalam fungsi redraw-nya.

Nilai yang Anda simpan dalam $.state tidak memerlukan panggilan, karena menulis nilai menggambar ulang situs yang membacanya.

Gambar ulang pada timer

Untuk menjaga jam, hitung mundur, atau nilai dari luar sesi saat ini, gambar ulang sesuai jadwal. Mulai timer dalam hook session.start modul. Jika modul sudah memiliki satu, seperti hello-tabs, tambahkan baris $.clock.every ke dalamnya:

on('session.start', async ($, e, next) => {
  // Setiap 1000 milidetik, minta Claude Code menggambar situs Anda lagi
  $.clock.every(1000, () => $.ui.invalidate('ui.render'))
  return next(e)
})

Claude Code sekarang menjalankan hook ui.render Anda sekali per detik. Timer berhenti saat modul dimuat ulang, dan instans baru modul memulai miliknya sendiri.

Seberapa sering situs dapat digambar ulang

Claude Code membatasi frekuensi penggambaran ulang situs, jadi mod Anda dapat memanggil $.ui.invalidate sesering data berubah. Untuk seberapa sering setiap situs dapat digambar ulang, lihat tabel batas.

Panggilan yang datang lebih cepat dari batas digabungkan menjadi satu redraw. Redraw itu menjalankan hook Anda sekali, dan hook membaca data Anda seperti adanya saat itu, jadi nilai terbaru ditampilkan dan nilai di antaranya tidak. Animasi tidak dapat berjalan lebih cepat dari batas.

Jaga status

Tempat mod menyimpan nilai menentukan berapa lama nilai bertahan: sampai modul dimuat ulang, sampai sesi berakhir, atau dari satu sesi ke sesi berikutnya. Pilih berdasarkan berapa lama nilai harus bertahan:

$.store.get(key) diselesaikan ke nilai atau undefined, dan $.store.set(key, value) mengambil nilai JSON apa pun.

Simpan nilai dalam $.state

$.state menyimpan nilai untuk panjang sesi, dan itu menggambar ulang untuk Anda. Ini adalah status reaktif: hook ui.render yang membaca nilai berlangganan ke dalamnya, jadi Claude Code menggambar ulang situs itu setiap kali Anda menulis nilai, dan Anda tidak memanggil $.ui.invalidate. Nilai dalam $.state juga bertahan reload modul, yang variabel tidak.

Untuk mengaturnya, deklarasikan nilai Anda, arahkan manifest Anda ke deklarasi, kemudian tentukan dan gunakan setiap nilai. Contoh memindahkan count dari hello-tabs ke dalam $.state.

Deklarasikan nilai

Deklarasikan nilai dalam file deklarasi tipe. Kunci luar adalah nama plugin Anda, dan setiap entri di bawahnya adalah nilai dan tipenya. Simpan ini sebagai hello-tabs/types/index.d.ts:

declare module 'claude-code' {
  interface PluginState {
    'hello-tabs': {
      tab: 'one' | 'two'
      count: number
    }
  }
}

Arahkan manifest ke deklarasi

Untuk membiarkan claude plugin validate memeriksa kode Anda terhadap file itu, tambahkan bidang types ke manifest dengan jalurnya:

{
  "name": "hello-tabs",
  "version": "0.1.0",
  "description": "Opens a pane with two tabs and a counter",
  "author": { "name": "Your Name" },
  "types": "./types/index.d.ts"
}

Tentukan, baca, dan tulis nilai

Dalam modul Anda, tentukan setiap nilai dengan default, bacalah saat menggambar, dan tulislah dari callback. atom menamai nilai dan defaultnya, read mengembalikannya, dan update menulisnya. Tiga pembantu memanggil $.state.get dan $.state.set untuk Anda:

import { atom, read, update } from 'claude-code'

// Di atas modul: beri nama nilai dan berikan defaultnya
const count = atom({ plugin: 'hello-tabs', key: 'count' }, 0)

// Dalam hook ui.render: baca nilai untuk menggambarnya
const n = await read($, count)

// Dalam Tombol: tulis nilai baru dari yang lama
onPress: () => update($, count, (value) => value + 1)

Karena hook ui.render membaca count, Claude Code menjalankan hook lagi setiap kali tombol menulisnya.

Aturan berikut berlaku untuk kode:

• Tulis plugin dan key sebagai string literal: claude plugin validate membacanya dari sumber Anda
• Simpan hasil setiap panggilan atom dalam const: jika Anda mendeklarasikan count dengan let, validasi gagal dengan takes a source the scan can read
• Deklarasikan setiap nilai dalam file deklarasi tipe: jika tidak, validasi gagal dengan hello-tabs.count is not declared
• Tulis dari callback atau hook event lain: hook ui.render dapat membaca status dan tidak dapat menulisnya, jadi tulis dari onPress, onSubmit, atau hook untuk event lain

Ubah hello-tabs untuk menggunakan $.state

Untuk memindahkan count dalam hello-tabs ke dalam $.state, ubah setiap baris yang menggunakannya:

• Di atas modul: tambahkan baris import, dan ganti let count = 0 dengan baris atom
• Dalam hook ui.render: tambahkan baris read sebelum tabButton, dan gambar 'Count: ' + n dalam Text
• Dalam tombol Add one: ganti onPress dengan yang dalam Simpan dari lebih dari satu sesi, yang menyimpan hitungan serta menulisnya
• Dalam hook session.start: ganti dua baris yang membaca saved dengan panggilan loadCount dari Muat nilai yang disimpan lagi setelah /clear

Simpan redraw untuk tombol tab, karena tab masih variabel.

Muat nilai yang disimpan lagi setelah /clear

Jika mod Anda menyalin nilai yang disimpan dari $.store ke dalam $.state pada session.start, itu harus menyalinnya lagi setelah /clear, /resume, atau /branch. Perintah tersebut mengembalikan setiap nilai $.state ke defaultnya, dan session.start tidak dipicu lagi. classic.SessionStart dipicu setelah masing-masing, dengan e.source diatur ke clear, resume, atau fork, jadi salin nilai lagi dalam hook di atasnya. Jika tidak, gambar Anda menampilkan default, dan callback yang menyimpan nilai $.state menulis default di atas apa yang Anda simpan.

Kode ini memuat count dari kedua hook. Itu dibangun di atas versi $.state dari hello-tabs, di mana count adalah atom dan update diimpor. Letakkan loadCount di atas register, dan tambahkan panggilan loadCount ke hook session.start yang sudah Anda miliki. classic.SessionStart juga dipicu saat startup dan setelah compaction, yang tidak mengatur ulang $.state, jadi filter pada source menjaga hook ke tiga reset:

// Salin hitungan yang disimpan dari $.store ke dalam $.state, atau 0 jika tidak ada yang disimpan
async function loadCount($) {
  const saved = Number((await $.store.get('count')) ?? 0)
  await update($, count, () => saved)
}

// Berjalan sebelum prompt pertama Anda, dan lagi setelah reload
on('session.start', async ($, e, next) => {
  await loadCount($)
  return next(e)
})

// Berjalan lagi setelah /clear, /resume, dan /branch, yang melaporkan fork
on('classic.SessionStart', { source: ['clear', 'resume', 'fork'] }, async ($, e, next) => {
  await loadCount($)
  return next(e)
})

Dengan kedua hook di tempat, panel menampilkan hitungan yang disimpan setelah /clear dan bukan 0, dan penekanan berikutnya dari Add one menambah ke hitungan yang disimpan.

loadCount menulis nilai yang disimpan di atas yang ada dalam $.state, dan session.start dipicu lagi setiap kali modul dimuat ulang. Untuk menjaga penyimpanan agar tidak tertinggal, simpan pada setiap perubahan, seperti yang dilakukan tombol Add one.

Untuk memeriksa reload tanpa sesi, uji gambar setelah /clear.

Simpan dari lebih dari satu sesi

Setiap sesi di mesin Anda yang menjalankan mod Anda berbagi satu $.store. get diikuti oleh set bukan atomik. Ketika dua sesi masing-masing membaca nilai, mengubahnya, dan menulisnya kembali, mereka bersaing, dan penulisan kedua menggantikan yang pertama.

Untuk membuat hal itu kurang mungkin terjadi:

• Berikan setiap item kuncinya sendiri: set mengubah hanya kuncinya sendiri, jadi sesi yang menulis kunci berbeda tidak menimpa satu sama lain
• Baca lagi tepat sebelum Anda menulis: untuk nilai yang beberapa sesi ubah, get kunci dalam callback dan bangun nilai baru dari itu, bukan dari salinan yang Anda muat pada session.start. Penulisan sesi lain masih hilang jika mendarat antara get dan set Anda.

Tombol ini menambahkan satu ke apa pun yang disimpan sekarang, kemudian memperbarui gambar:

onPress: async () => {
  // Baca apa yang disimpan sekarang, yang sesi lain mungkin telah ubah
  const saved = Number((await $.store.get('count')) ?? 0)
  // Simpan hitungan baru, kemudian tampilkan
  await $.store.set('count', saved + 1)
  await update($, count, () => saved + 1)
}

Jika sesi kedua telah menekan tombolnya sendiri tiga kali sejak sesi ini dimulai, penekanan ini menampilkan dan menyimpan hitungan yang mencakup ketiga itu.

Langkah berikutnya

• Bereaksi terhadap event: umpan gambar Anda dari panggilan alat dan giliran
• Gunakan API mods: umpan gambar Anda dari timer dan panggilan model
• Uji gambar: tekan tombol Anda dari tes, di lebih dari satu permukaan
• Render sites dan elemen: prop setiap situs dan prop setiap elemen