Build a Claude Code mod

Write a feature brief

A narrow brief gives a smaller, safer mod. Edit the brackets, then put the result into the Mod Maker prompt's square brackets.

Feature: [one sentence, e.g. "show how long the current turn has run in the status line"]
Shape: [status line entry, band above the prompt, side pane, toast, sound, slash command, or a hook on tool calls or prompts]
Reads: [only what it needs, e.g. turn start and end]
Must not: [no network, no model calls, no file reads unless named here]
If it can block or change something: [what it does when the mod itself fails]
Done when: [the behaviour a test can prove on terminal and desktop]

Use the Mod Maker starter

Describe the feature you wish Claude Code had. Get a tested, installable mod. The prompt below is shown from the site's current catalogue data; the pinned review in the footer covers the reference prose. It asks Claude to pick the shape, keep reach small, fail safe, write tests for terminal and desktop, and run claude plugin validate and claude plugin test until both pass.

The repository layout

From CONTRIBUTING.md. Every listed mod comes with the prompt that built it, with the frontmatter the catalogue reads: mod, title, tagline, category, surfaces and model_calls.

prompts/<mod>.md                  the prompt, with catalogue frontmatter
mods/<mod>/.claude-plugin/plugin.json
mods/<mod>/hooks/hooks.json       { "modules": ["./register.tsx"] }
mods/<mod>/hooks/register.tsx     the hooks module
mods/<mod>/tests/*.test.ts(x)     behaviour tests, terminal and desktop
mods/<mod>/README.md              install, use, settings, what it can touch, limits

Walk through Redline's source

The manifest

plugin.json fields and their roles:

name

"redline". Must match the prompt frontmatter mod, or the catalogue script stops. Cannot start with claude-.

version

"0.1.3". Installed copies update only when this moves.

description

The one-line tagline.

homepage, documentationUrl

The mod page on this site and the README on GitHub.

repository, supportUrl

The repository and its issues.

privacyPolicyUrl, termsOfServiceUrl

This site's privacy and terms pages.

author, license, keywords

"modmyclaude", "MIT" and search keywords.

types

"./types/index.d.ts", the mod's own type declarations.

The module list

hooks/hooks.json is one line, { "modules": ["./register.tsx"] }, pointing Claude Code at the hooks module.

The hooks module

In register.tsx, look for three patterns worth copying:

• A safely wrapper that logs a failure to the debug log so a display bug never stands in a turn's way.
• A command .catch that shows a toast instead of failing silently.
• A band render that draws what next(e) returns before its own line, so what other mods draw above the prompt stays in place.

The tests

tests/wiring.test.tsx raises events and mounts the band and pane on both the terminal and desktop surfaces. See testing and compatibility for what that does and does not prove.

This page does not include a minimal code example, because we have not tested one. Read the source and the types Claude Code generates for your version.

Load it locally

Run the commands on this page from the root of a local clone of claude-code-mods, after npm ci, with Node 20 or later and Claude Code 2.1.287 or later (see testing and compatibility).

Replace <mod> with a mod name, such as redline, before running a command.

Load a folder straight into a session:

claude --plugin-dir mods/<mod>

Or install from your clone the way users install from GitHub. Sessions then read your folder, so /reload-plugins picks up each edit.

claude plugin marketplace add "$PWD"
claude plugin install <mod>@modmyclaude

Release checklist

1. Open a Mod idea issue first, so the scope and reach are agreed.
2. Add prompts/<mod>.md with catalogue frontmatter.
3. Run the strict gate with STRICT=1, including the type check (see testing).
4. Bump version and add one CHANGELOG.md line for any shipped change, then run npm run versions -- origin/main.
5. Run npm run catalog, npm run links and npm run smoke.
6. Open one pull request per mod, titled mod(<name>): <what>. A second maintainer reviews it against its prompt.

npm ci
STRICT=1 npm run check -- mods/<mod>
npm run versions -- origin/main
npm run catalog
npm run links
npm run smoke

Generated files and draft handling are covered in the repository reference.