Follow Discord
Sweep 19 Sep 2026 · 02:36Z Build v2.1.278 500 read Stable v2.1.267 Latest v2.1.278 Next v2.1.278 Feeds RSS JSON llms.txt Unofficial
HomeReference
Mods

Building mods.

A mod is a plugin with a hooks module, and the primitive underneath it is the function hook: one async function per event, composed as middleware. Claude Code ships the runtime, generates its own type declarations for it, and documents almost none of it. This is the long form: what the runtime offers, what each piece costs, and which parts do not behave the way the shape suggests.

Everything here was read out of the declarations Claude Code writes about itself and then run against the installed build. Where a page states a behaviour, the command that produced it is on the page.

Pages10start at the top
The short versionone async function per eventregistered hooks wrap each other, earliest outermost
Read against2.1.272Linux, the shipped build

Read the pages in order if you have not written one of these before. The first three are the whole model and nothing works without them; the rest can be read out of order once you have them.

  1. 01 What a mod is The primitive, the gate that turns it on, and a mod that runs in four files.
  2. 02 Anatomy of a mod plugin.json, hooks.json and register(): every file a mod needs and what each one may say.
  3. 03 Tiers, order and next() The five tiers, how a hook wraps the ones below it, and the five things a hook can do with next().
  4. 04 The engine interface Every noun and verb on $, what a call costs, and the load-time scan that decides whether it is allowed.
  5. 05 The event catalogue What you can hook, the shape each event carries, and how a matcher narrows it.
  6. 06 Drawing on the screen Panes, components, focus and scroll: the half of the runtime that puts pixels in the terminal.
  7. 07 userConfig and options Declaring options in the manifest, what register() receives, and the two ways a manifest loads and then fails.
  8. 08 Testing a mod The claude-code/testing module: describe, expect, mock and tier, and the three traps its own docs declare.
  9. 09 Confirmed gotchas Everything on this page was reproduced against the installed build, with the command that did it.
  10. 10 Recipes Worked mods, end to end, each one short enough to read in a sitting.

What this is not

It is not Anthropic's documentation and it does not speak for them. The runtime is gated behind an environment variable, the declarations it generates are theirs rather than this site's, and any of it can change in the next release without a note. Where a page quotes an error string or a type, it is quoting build 2.1.272 and says so.

It is also not complete in the sense of covering every field of every event. The declarations run to hundreds of kilobytes and a good deal of it is the shape of tool inputs you already know. What is here is the part that is load-bearing and the part that is surprising.