Guide / Build Your First Mod

Build Your First Claude Code Mod

Updated October 5, 2026 · Covers Claude Code v2.1.287 and later

There are two ways to build a mod: describe it in plain language and let Claude Code scaffold it (fastest, and genuinely good), or assemble the files by hand (full control). This page covers both, plus the iteration loop and the validate/test steps to run before you share.

Path 1: Let Claude Code scaffold it (recommended)

This is the fastest path and, unusually for generated code, a good one — the model knows the mod API well. Describe the mod the way you would describe it to a colleague: which pipeline event it should watch, what it should draw, what happens on Proceed or Cancel. Claude Code generates the plugin skeleton and the module; you iterate with hot reload until it behaves, then copy the folder out to keep or share.

Be specific about the trigger. "A live line showing my test status" is vague; "a live line above the prompt that turns red when the last command exited non-zero" gives the scaffolder something to hook onto. The event you name determines which pipeline subscription it generates.

Path 2: The manual skeleton

A mod is three things: metadata, event subscriptions, and the module itself.

my-first-mod/
  plugin.json         # the mod's metadata (name, version, description)
  hooks/hooks.json    # which pipeline events this mod subscribes to
  mod.ts              # the module: exports register()

The module is where the work happens. It exports a register function that subscribes to events in the agent's execution pipeline — requests going out, responses coming back, tool calls being made. When an event fires, your code runs and can observe, transform, or block what happens next. For anything visual or stateful, use the dedicated $ API (rendering, state, files, HTTP, tools) — the rule from early mod authors is simple: use $ for everything, never reach for Node or the DOM.

// mod.ts — structural sketch. Exact event names live in
// .claude-plugin/types/ for your installed Claude Code version;
// read those before guessing.
export function register() {
  // 1. subscribe to the pipeline events you care about
  // 2. on each event: observe, transform, or block — then optionally draw UI
  // 3. build all UI with the $ API, never Node or the DOM
}

Read the types — they are the ground truth

The type definitions for your installed Claude Code version live in .claude-plugin/types/. Event names, the shape of the $ API, what your register function receives — all of it is in there. The ecosystem is days old and blog posts go stale fast; the types do not. When in doubt, read the types.

Iterate with hot reload

Do not package while you develop. Load the folder directly and let the terminal hot-reload your changes inside a live session:

claude --plugin-dir ./my-first-mod

Edit the module, watch the UI update, repeat. Iterating on a mod feels closer to web development than to plugin development — which is exactly why the first wave of mods was built in days, not weeks.

Validate and test before you share

claude plugin validate ./my-first-mod
claude plugin test ./my-first-mod

validate checks the packaging (metadata, hooks declarations); test exercises the mod. Run both before pushing to GitHub — and write a README showing the install commands (/plugin marketplace add <you>/<repo>), because the next person's first question will be how to install it. See How to Install Claude Code Mods.

Good first mods

• A live line for something you check compulsively — CI status, token spend, the time. Small, visible, immediately useful.
• A guard for a rule you keep forgetting — never commit without running the linter, never paste secrets. Guards are the highest-impact mod primitive for everyday work.
• A pane for something you re-read — plan progress, background tasks. If you find yourself scrolling up for it, it belongs above the prompt.

Browse the directory for inspiration →