Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[DOCS] Mods: document that each event allows only one matcher-less on() registration per plugin

Open Beginner friendly
  • Is something wrong?
#101,450 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
documentation

Research direction

Read the plugin-authoring skill in SKILL.md and reference.md, then inspect the On and Register doc comments in .claude-plugin/types/claude-code/index.d.ts. Document that each event can have only one matcher-less registration per plugin and explain the matcher workaround; done when all three locations clearly state the rule.

Written by the indexing model from the issue text.

Description

area:plugins documentation enhancement
Documentation Type

Missing documentation (feature not documented)

Documentation Location

The plugin-authoring skill (SKILL.md, reference.md) and the On / Register doc comments in the mods type declarations (.claude-plugin/types/claude-code/index.d.ts).

Section/Topic

Registering hooks with on(event, matcher?, hook): how many registrations an event may have

Current Documentation

The docs describe on(event, matcher?, hook) and matchers, but do not say that an event may be registered without a matcher only once per plugin.

What's Wrong or Missing?

claude plugin validate (and the loader) refuses a hooks module that registers the same event twice without a matcher — for any event, not just session.start:

export const register: Register = on => {
  on('turn.complete', ($, e, next) => next(e))
  on('turn.complete', ($, e, next) => next(e))
}

✘ modules../register.ts: on("turn.complete") is registered twice without a matcher; the first is at ...register.ts:2; ...

Registrations with a matcher may repeat, even with an identical matcher:

on('turn.complete', { reason: 'answer' }, ($, e, next) => next(e))
on('turn.complete', { reason: 'answer' }, ($, e, next) => next(e)) // accepted

Because hooks.json takes a single modules path, a plugin made of several features wires them from one hooks module, and several features naturally observe the same lifecycle events (session.start, turn.complete, prompt.submit). Discovering this rule late forces a redesign: an event-ownership table and artificial matchers such as { isInteractive: true }, { reason: 'answer' }, { origin: { kind: 'composer' } }. Events whose input has no literal discriminant (e.g. session.measure) cannot be shared at all.

Suggested Improvement
  1. State the rule in reference.md / the skill's "A mod in one paragraph" and in the On doc comment, with the matcher workaround.
  2. Consider allowing repeated matcher-less registrations (chained in registration order, as matcher registrations already are), or provide a way to share an event that has no discriminant.
Impact

Medium - Makes feature difficult to understand

Additional Context
  • Claude Code 2.1.296 (type declarations written by 2.1.295), Windows 11.
  • Related: #100984 (another rule claude plugin validate enforces or misses without documentation).
Dominant language
TypeScript
Stars
153k
Forks
26.7k
Avg merge
22h 23m
Merged PRs (30d)
15

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

  • No Dockerfile or Docker Compose file
  • No pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from anthropics/claude-code

All issues in anthropics/claude-code

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.