Write a Claude Code mod in TypeScript

1. Define one behavior

Build a small /hello command before adding storage, background work or network access. Use a current Claude Code version that supports mods. The generated declarations from your installed version are the authority when they differ from an online example.

2. Create the three files

Put the manifest at .claude-plugin/plugin.json, the module list at hooks/hooks.json and the entry at hooks/register.tsx. The module path is relative to hooks.json. Use the starter generator to download them; choose “slash-command”.

3. Register handlers

Import the Register type from claude-code with a type-only import. Register the command on session.start and handle it on command.run. Passing next(e) preserves the normal event flow; returning a result from the command handler supplies its response. Do not introduce a runtime dependency on a Node package just to obtain a type.

4. Validate locally

Load the plugin directory in a trusted test project, inspect the .claude-plugin/types declarations generated by that CLI, and run claude plugin validate with the plugin path. Test /hello, reload and disable the plugin. Validation is separate from verifying every runtime behavior.

5. Expand with evidence

Add one feature at a time. For UI elements use the element table returned by the supported surface, not browser DOM or React assumptions. Document versions, permissions, installation and removal. Test error paths before sharing; a working happy path is not enough.

Official mod creation guide · Official API reference

import type { Register } from "claude-code";
export const register: Register = (on) => {
  on("session.start", async ($, e, next) => {
    await $.command.register({ name: "hello", description: "Say hello" });
    return next(e);
  });
  on("command.run", { command: "hello" }, async () => ({ text: "Hello" }));
};