On this page

Mod Creator

inherit CC 2.1.287+ · verified 2.1.300

View agent file on GitHub (opens in a new tab)

Quick reference

Field	Value
Agent	brewcode:mod-creator
Triggers	create mod, hooks module, mod API
Model	inherit: uses the session model
Tools	Read, Write, Edit, Glob, Grep, Bash, Skill, WebFetch, WebSearch
Output	Mod files, gate exit codes, drift verdict

Mod Creator builds Claude Code mods: hooks-module plugins whose TypeScript register.ts registers handlers on engine events and $ nouns. Mods are early access, on by default from Claude Code 2.1.287. See Brewcode mods; prompt placeholders and plan-mode effort were built with this agent.

The installed engine decides what the API accepts, not memory: every run starts with a drift check against the live types file, and a symbol missing there does not exist for the agent. Every interactive control a mod ships carries its key hint, proven live key by key (reference mods-patterns.md section 12).

When to use

Scenario	Prompt
New mod from an idea	Create a mod that ... with events and behavior
Pick events and nouns	Which mod events cover X?
Mod does not load	Mod does not load, debug it
Tests for an existing mod	Add plugin tests for the mod in <dir>
Port to a new build	Re-verify the mod against the installed build
Ship	Add the mod to the marketplace and check the install

Examples

Create a mod that adds a one-line effort hint to the prompt bar in plan mode.
Own the new mod directory only. Fail open in every hook, write plugin tests,
and report the gate results. Do not touch git.

Check whether the mod in ./my-mod still matches the installed Claude Code build
and list every drifted symbol.

How it works

One bounded deliverable per run; oversized briefs return a split proposal (scope guard). The agent refuses to write under ~/.claude/dev-mods/ unless asked.

▶ Step 0 and self-update

#	Action	Pass
1	claude --version	Hint only; the build is X in the last line of the drift check
2	Load the plugin-authoring skill, derive the types file path	Derived each run, never stored
3	mods-ref-check.mjs with types file and references dir	Exit 0 + first line CLEAN; exit 1 + DRIFT; anything else is an error, not drift. Last line VERSION types X references Y

On drift the agent works from the live types and reports every DRIFT row. The maintainer update (refresh references, add a changes entry, bump verified_on in all five files, re-run to exit 0) happens only when the brief asks and both markers exist at the git root: brewcode/.claude-plugin/plugin.json and .claude/scripts/bump-version.sh. Offline tests: brewcode/skills/agents/tests/run.sh; set MODS_TYPES for the live check.

▶ Key rules

Full list in the agent file; each rule is sourced from validate output or a live probe.

Rule	Else
Static import only: no import(), JSON or .md import, require	Module does not load
Never pass or alias $; spell $.noun.event(...) at each call site	Validate refuses
Fail open: no blanket try/catch; refusing guards get .catch	Refusal lost, or the mod blocks the prompt
No I/O in prompt.edit	Per-keystroke lag
hooks/hooks.json carries { "modules": ["./register.ts"] }; a classic "hooks" sibling is allowed	Second modules entry refused
Never commit .claude-plugin/types/ or the engine-written tsconfig.json	Engine files land in git
A broken module still exits claude -p with rc 0: grep stderr for hooks module did not load	Red gate read as green
Behavior that must survive Team/Enterprise orgs ships a bundled command hook	Module classic.* hooks are bypassed: silent no-op
Every interactive control shows its key sequence (label or dim row)	Undiscoverable control

▶ Reference pack and return contract

Five files under brewcode/skills/agents/references/, each stamped verified_on.

File	Read when
mods-lifecycle.md	Always before building: hard rules, scaffold, validate, test, ship
mods-api.md	Choosing events or $ nouns; holds the symbol index
mods-patterns.md	Building behavior: command hooks, state files, turn.step, band, slash commands
mods-testing.md	Tests: kit, stubs, ui.mount, CI, headless and tmux checks
mods-changes.md	New build or older mod: per-version changes

Return: verdict first, at most 30 lines. Per mod: path and role, Step 0 verdict plus DRIFT rows, gate exit codes (validate, tsc, test, live run), gaps. Logs go to a timestamped .claude/reports/ folder, path only.

Related

Update: /brewtools:plugin-update - FAQ