Bongkar Claude Code Mods: Hook, Event, dan 15 Bagian Layar yang Bisa Diganti

Mod Itu Apa?

Mod itu satu file TypeScript yang nyelip di tengah kerjaan Claude Code. Setiap kali engine mau ngelakuin sesuatu, misalnya jalanin tool, gambar layar, atau ngirim prompt, mod kamu dapet giliran duluan. Dia bisa cuma ngintip, ngubah dulu, atau jawab sendiri tanpa nerusin ke engine.

Yang bikin saya kaget: mod bisa ngegambar ulang tampilan bawaan Claude Code. Tiap tool call bisa diganti jadi satu baris, jawaban model bisa digambar ulang pakai gaya lain, dan blok hasil tool bisa disembunyiin. Ini jauh lebih dalam dari sekadar nambah status line atau popup.

Post ini panduan dari nol. Semua nama event, method, dan props di sini saya ambil dari type declaration yang ditulis Claude Code 2.1.294 sendiri. API-nya masih berlabel early access, jadi detailnya bisa berubah di rilis berikutnya.

Konsep Inti: Rantai Hook

Kalau cuma boleh ingat satu hal dari post ini, ingat gambar ini.

Satu event lewat semua mod dulu, baru sampai ke perilaku bawaan engine. Hasilnya naik lagi lewat jalur yang sama. Jadi setiap mod bisa ngubah input sebelum engine jalan, dan bisa baca atau ngubah hasilnya setelah engine selesai.

Kalau kamu pernah nulis middleware di Express atau Koa, bentuknya mirip banget.

Isinya Cuma Tiga File

Satu mod itu satu folder. Ga ada build step, engine langsung baca TypeScript-nya.

mod-saya/
├─ .claude-plugin/
│  └─ plugin.json      nama, versi, deskripsi
└─ hooks/
   ├─ hooks.json       nunjuk ke register.tsx
   └─ register.tsx     semua logika di sini

Dua file JSON-nya pendek:

// .claude-plugin/plugin.json
{ "name": "mod-saya", "version": "0.1.0", "description": "Toast tiap turn selesai" }

// hooks/hooks.json
{ "modules": ["./register.tsx"] }

Dan ini mod paling kecil yang beneran jalan:

import type { Register } from "claude-code";

export const register: Register = (on, options) => {
  // tiap turn selesai, munculin toast
  on("turn.complete", async ($, e, next) => {
    $.ui.toast("Turn selesai");
    return next(e);
  });
};

Satu hal yang perlu diingat dari awal: mod jalan di environment-nya sendiri. Ga ada Node, ga ada DOM. import fs from "node:fs" ga bakal jalan, dan module yang pakai import() dinamis malah ga di-load sama sekali. Semua akses ke luar lewat $. Parameter options isinya nilai userConfig dari plugin.json.

Rumusnya Satu

Semua mod, sekecil atau segede apa pun, isinya panggilan on(...) kayak gini:

on("tool.call", { tool: "Bash" }, async ($, e, next) => {
  // ...
});

Hook-nya sendiri selalu nerima tiga hal:

Empat Gerakan Hook

Dari tiga parameter itu, cuma ada empat hal yang bisa dilakuin sebuah hook.

1. Terusin Apa Adanya

Cuma ngintip, ga ngubah apa-apa. Paling sering dipakai buat nyatet atau ngitung.

return next(e);

2. Ubah Dulu, Baru Terusin

Mod di bawahnya dan engine cuma ngelihat versi yang udah diubah.

return next({ ...e, command: e.command.trim() });

3. Jawab Sendiri

Ga manggil next. Engine ga pernah jalanin perilaku bawaannya, dan yang di atas nerima jawaban dari hook ini.

return { deny: ".env ga boleh diedit" };

4. Terusin, Terus Baca Hasilnya

Tunggu engine kelar, terus bereaksi ke hasilnya.

const ran = await next(e);
if (ran.isError) $.ui.status("gagal");
return ran;

Satu jebakan penting: hook yang error di-skip, dan rantainya jalan terus. Buat mod tampilan, itu bagus, karena mod yang rusak ga bikin Claude Code ikut rusak. Buat mod penjaga, itu bahaya. Mod yang mestinya nolak rm -rf terus crash berarti command-nya tetap jalan. Makanya hook penjaga dikasih .catch:

on("tool.call", { tool: "Bash" }, guard).catch(($, e, next) =>
  next.called ? next(e) : { deny: "guard-nya error" },
);

next.called ngasih tau hook-nya udah sempet manggil next atau belum. Kalau belum, .catch nolak.

Kapan Mod Dipanggil

Ini urutan event dalam satu session, dari buka Claude sampai keluar. Klik tiap langkah buat lihat kapan event-nya jalan, bisa ngapain, dan contoh kodenya.

on("session.start", async ($, e, next) => {
  await $.command.register({
    name: "catatan",
    description: "Buka pane catatan",
  });
  return next(e);
});

on("prompt.submit", async ($, e, next) =>
  e.text.trim() === "tt"
    ? next({ ...e, text: "Jalanin semua test, terus benerin yang gagal" })
    : next(e),
);

on("turn.start", async ($, e, next) => {
  saran = []; // buang saran lama
  $.ui.invalidate("ui.render"); // minta layar digambar ulang
  return next(e);
});

on("turn.step", async function* ($, e, next) {
  const hasil = yield* next(e); // terusin semua potongan apa adanya
  return hasil;
});

on("tool.call", { tool: "Bash" }, async ($, e, next) => {
  const ran = await next(e); // Bash beneran jalan di sini
  const gagal = ran.deny === undefined && ran.isError === true;
  $.ui.status(gagal ? `gagal: ${e.command.slice(0, 40)}` : undefined);
  return ran;
});

on("turn.complete", async ($, e, next) => {
  const result = await next(e);
  if (e.reason === "answer") $.ui.toast(`Jawaban ${e.answer.length} karakter`);
  return result;
});

on("session.end", async ($, e, next) => {
  if (e.reason === "clear") $.ui.log("session di-/clear");
  return next(e);
});

Bagian Layar yang Bisa Diganti

Event ui.render bisa ngegambar ulang 15 component bawaan Claude Code. Gambar di bawah ini skematik, posisi persisnya bisa beda. Label di kanan tiap baris itu nama component-nya. Yang labelnya $.ui.status dan $.ui.toast diisi lewat method, dan kotak input sama sekali ga bisa digambar ulang. Klik baris mana aja buat lihat itu component apa dan mod mana yang udah ngutak-atiknya.

Satu yang ga kegambar di atas: AskUserQuestion, dialog pertanyaan pilihan ganda. Itu juga bisa di-hook.

Hook ui.render punya tiga cara ngegambar. return next(e) biarin tampilan bawaan. next({ ...e, props }) ngubah props-nya dulu. Atau balikin tree sendiri pakai elemen dari $.ui.resolve(e). Semua surface punya Box, Text, Button, Link, Code, dan Markdown. Terminal juga punya Raster (grid warna, cocok buat sparkline) dan Image.

e.surface bisa terminal, desktop, vscode, atau mobile. Mod tampilan biasanya ngecek ini dulu, karena tree yang bagus di terminal belum tentu cocok di desktop.

$: Remote ke Engine

Mod ga bisa nyentuh apa-apa secara langsung. Semuanya lewat $.<noun>.<method>(). Kolom terakhir nandain noun yang bisa nyentuh mesin atau internet kamu.

Detail yang menarik: panggilan $ juga lewat rantai yang sama kayak event. fs.read, http.fetch, dan process.run semuanya bisa di-hook. Artinya satu mod bisa nge-deny $.http.fetch punya mod lain.

Contoh Kasus

Delapan kasus, dari yang paling sering ditemuin. Dua yang pertama mod beneran yang ada di GitHub. Sisanya contoh resmi dari skill plugin-authoring bawaan Claude Code, atau dari doc di type declaration-nya.

● tool_call: Read(src/app.ts)
● tool_call: Bash(git status)
● tool_call: Bash(npm test) - error
● tool_call: Edit(src/app.ts)

on("ui.render", { component: "ToolResult" }, async ($, e, next) => {
  if (e.surface !== "terminal") return next(e);
  const { Box } = $.ui.resolve(e);
  return Box({}); // kosong: blok hasil ga digambar
});

on("ui.render", { component: "ToolUse" }, async ($, e, next) => {
  if (e.surface !== "terminal") return next(e);
  const { Box, Text } = $.ui.resolve(e);
  const color = e.props.isErrored
    ? "error"
    : e.props.isRunning || e.props.output === undefined
      ? "warning"
      : "success";
  return Box({
    flexDirection: "row",
    children: [
      Text({ color, children: ["●"] }),
      Text({ dimColor: true, children: ["tool_call: "] }),
      Text({ bold: true, children: [e.props.tool] }),
    ],
  });
});

// grup read/search dibuka, tiap isinya lewat hook ToolUse di atas
on("ui.render", { component: "ToolGroup" }, async ($, e, next) =>
  next({ ...e, props: { ...e.props, isExpanded: true } }),
);

next:
  1: jalanin test yang barusan ditulis
  2: lakuin hal yang sama buat halaman settings
  3: /code-review high
  0: dismiss

let saran: string[] = [];

on("turn.start", async ($, e, next) => {
  saran = [];
  $.ui.invalidate("ui.render");
  return next(e);
});

on("turn.complete", async ($, e, next) => {
  const result = await next(e);
  if (e.reason !== "answer") return result;
  void (async () => {
    // jalan di belakang, turn ga nunggu
    const reply = await $.model.fork({
      prompt:
        "Jangan lanjutin task. Tebak 3 prompt berikutnya. Jawab JSON array of string.",
    });
    try {
      saran = reply.isAnswered ? JSON.parse(reply.text) : [];
    } catch {
      saran = [];
    }
    $.ui.invalidate("ui.render");
  })();
  return result;
});

on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => {
  const below = await next(e);
  if (saran.length === 0 || e.props.isWorking) return below;
  const { Box, Button } = $.ui.resolve(e);
  return (
    <Box flexDirection="column">
      {below}
      {saran.map((p, i) => (
        <Button
          key={`s${i}`}
          hotkey={String(i + 1)}
          plain
          label={p}
          onPress={() => $.prompt.fill({ text: p })}
        />
      ))}
    </Box>
  );
});

const PROTECTED = /(^|\/)\.env(\.|$)/;

on("tool.call", { tool: "Edit" }, ($, e, next) =>
  PROTECTED.test(e.file_path)
    ? { deny: `${$.plugin.name}: ${e.file_path} is protected here.` }
    : next(e),
).catch(($, e, next) =>
  next.called ? next(e) : { deny: `${$.plugin.name}: its guard failed.` },
);

let startedAt = 0;

on("prompt.submit", async ($, e, next) => {
  startedAt = await $.clock.now();
  return next(e);
});

on("turn.complete", async ($, e, next) => {
  const seconds = Math.round(((await $.clock.now()) - startedAt) / 1000);
  if (seconds > 120) $.ui.toast(`Turn tadi ${seconds} detik`);
  return next(e);
});

on("session.start", async ($, e, next) => {
  await $.command.register({
    name: "catatan",
    description: "Buka pane catatan",
  });
  return next(e);
});

on("command.run", { command: "catatan" }, async ($) => {
  await $.ui.open({ id: "catatan", title: "Catatan" });
  return { text: "Pane catatan dibuka." };
});

on("ui.render", { component: "Pane", requestId: "catatan" }, async ($, e) => {
  const { Box, Text } = $.ui.resolve(e);
  return (
    <Box>
      <Text>Isi pane di sini</Text>
    </Box>
  );
});

const SINGKATAN: Record<string, string> = {
  tt: "Jalanin semua test, terus benerin yang gagal",
  cm: "Commit perubahan ini dengan message yang jelas",
};

on("prompt.submit", async ($, e, next) => {
  const panjang = SINGKATAN[e.text.trim()];
  return panjang ? next({ ...e, text: panjang }) : next(e);
});

on("prompt.compose", async ($, e, next) => {
  const { sections } = await next(e);
  return {
    sections: [
      ...sections,
      {
        id: "aturan-tim",
        text: "Commit message selalu bahasa Inggris.",
        scope: "session",
      },
    ],
  };
});

on("agent.spawn", ($, e, next) => next({ ...e, model: "haiku" }));

Daftar Lengkap 46 Event

Ini semua event yang bisa dipasang di on(...) di Claude Code 2.1.294. Ketik buat nyari, atau pilih satu grup.

Selain 46 itu masih ada dua keluarga lagi. Yang pertama classic.*, hook settings model lama kayak classic.Stop atau classic.SessionEnd, dengan e yang sama persis kayak yang mereka terima di stdin. Yang kedua semua panggilan $ kayak fs.read atau http.fetch, yang udah dibahas di bagian remote tadi.

Sebelum Install Mod Orang

Mod jalan di dalam Claude Code, dan lewat $ dia bisa baca file, jalanin program, dan akses internet. Lima hal ini cukup buat menilai satu mod dalam beberapa menit:

1. Cari $.fs, $.process, $.http, dan $.env. Empat noun ini yang bisa nyentuh disk, shell, internet, dan token kamu. Mod tampilan harusnya ga butuh satu pun.
2. Cari tool.call, prompt.submit, prompt.compose, dan session.send. Ini yang bisa ngubah apa yang dikerjain atau dibaca model.
3. Cari $.model. fork dan complete makan kuota model kamu tiap kali dipanggil.
4. Jalanin claude plugin validate <folder>. Dia ngelaporin semua yang di-hook dan dipanggil module itu, plus semua yang bakal ditolak engine.
5. Pin commit-nya. Kalau install-nya lewat clone, tiap git pull berarti kode baru jalan di dalam Claude Code. Baca diff-nya dulu.

Sebagai contoh, ini hasilnya buat tiga mod yang saya bahas di atas:

Kalau mau nyari inspirasi, katalog awesome-claude-code-mods nge-scan GitHub dan nyatet akses tiap mod pakai validator yang sama. Mod buatan Anthropic sendiri (diff, agents-md, sec-default, telemetry) ada di anthropics/claude-code , dan itu contoh kode yang paling bisa dipercaya.

Bikin Mod Pertama

1. Minta Claude Bikinin

Cara paling cepat: bilang “bikin mod yang …” di session Claude Code. Skill plugin-authoring bawaannya nulis tiga file tadi di ~/.claude/dev-mods/<session>/<mod>/, terus nanya “Enable hot reloading for this session?”. Kalau dijawab enable, mod-nya langsung jalan begitu turn selesai.

2. Atau Jalanin Folder Sendiri

claude --plugin-dir ./mod-saya

Folder-nya di-watch. Tiap kali file di-save, module-nya di-load ulang. Variabel module ke-reset, sedangkan $.state dan $.store tetap.

3. Cek Sebelum Dipakai

claude plugin validate ./mod-saya
claude plugin test ./mod-saya   # jalanin *.test.ts

4. Kalau Mod-nya Diam Aja

Jalanin claude --debug. Hook yang gagal dan tree yang ditolak tercatat di debug log. Selama hot reload, transcript juga nampilin satu baris redup kayak mod-saya: ui.render (ToolUse) refused: …; the engine drew its own.

5. Share

Taruh .claude-plugin/marketplace.json di repo-nya. Orang lain cukup install pakai satu baris:

/plugin install mod-saya --marketplace <owner>/<repo>

Kesimpulan

• Mod itu satu file TypeScript yang nyelip di rantai hook. Setiap event lewat semua mod dulu, baru sampai ke perilaku bawaan engine.
• Rumusnya cuma on(event, matcher, hook), dan hook-nya cuma bisa empat hal: terusin, ubah dulu, jawab sendiri, atau baca hasilnya.
• ui.render bisa ngegambar ulang 15 component bawaan. Kotak input dan dialog izin ga termasuk.
• Semua akses ke luar lewat $, dan $.fs, $.process, $.http, serta $.env itu yang perlu dicek dulu sebelum install mod orang.
• Hook yang error di-skip. Buat mod penjaga, selalu pasang .catch.

Saya sendiri masih di tahap ngoprek. Kalau kamu udah bikin mod yang seru, kasih tau saya, siapa tau bisa masuk post berikutnya 🚀