Widen the repo to monitors

[jackyraimond]

Adds monitors as a second component type alongside hooks.

What a monitor is

A shell command that runs in the background for the whole session. Every line it prints to stdout reaches Claude as a notification.

It is the mirror image of a hook. A hook reacts to something Claude does — it fires on a lifecycle event and can block, format or record. A monitor reacts to something the world does, and tells Claude about it without anyone asking it to look:

[
  { "name": "shopware-log", "command": "tail -F var/log/dev.log",
    "description": "Shopware runtime errors" }
]

You edit a plugin, an exception lands in the log, and Claude knows — instead of you noticing later and pasting it in. Same for a failing Vite build, a container that died, or a deploy that finished.

Why here and not a new repo

Because they share this repository's trust model, which is what CONTRIBUTING is actually written around. Both run unsandboxed, automatically, with your credentials. A monitor arguably deserves more scrutiny than a hook, not less: it runs for the entire session and feeds its output straight into Claude's context.

Grouping by trust rather than by taxonomy also settles where the other components go. Skills and agents only influence what Claude says, with no automatic execution, so they belong in AiOpsCommunity/skills. MCP and LSP are a different thing again — mostly wrapping third-party servers — and are deliberately not addressed here.

Layout

Exactly parallel to hooks, because monitors/monitors.json is a default location Claude Code discovers on its own, just like hooks/hooks.json:

monitors/
├── _template/
└── <monitor-name>/
    ├── .claude-plugin/plugin.json
    ├── monitors/monitors.json     # array of monitor entries
    ├── scripts/<script>
    └── README.md

Tooling

• validate.sh loops over both kinds, sharing the manifest and README checks. Monitor-specific: array shape, required fields, duplicate names, valid when values, ${user_config.*} in a command (which Claude Code rejects for shell commands), personal paths, path escapes, and bundled script permissions. A monitor with no bundled script — a bare tail -F — is valid and reported as such.
• pr-policy.sh now enforces one hook or one monitor per PR, and blocks a PR that touches both.
• review-flags.sh scans monitor scripts too.
• CI validates monitor manifests with claude plugin validate --strict.

The rule the template leads with

Print only what deserves to interrupt. Every line costs context and pulls Claude's attention. A monitor that forwards a whole log turns a session into noise, and noise is how a useful monitor gets uninstalled. The template script filters in the script, before printing, and the README says to ask of every line: would I tap someone on the shoulder for this?

Constraints, stated up front

Documented in the template README rather than left to be discovered:

• Monitors run only in interactive CLI sessions.
• They run unsandboxed, at hook trust level.
• ${user_config.*} is not substituted into a monitor command, and monitor processes do not receive CLAUDE_PLUGIN_OPTION_<KEY>. A monitor needing configuration reads a file its script owns.
• Disabling a plugin mid-session does not stop a running monitor.
• Monitors are an experimental component; the schema may change between releases.

Testing

./scripts/validate.sh, ./scripts/pr-policy.sh and claude plugin validate --strict all pass.

18 validator scenarios, each mutating a real monitor plugin and asserting the build fails with the right message: missing description, missing command, duplicate names, an invalid when, a valid on-skill-invoke: when, ${user_config.*} in a command, a personal path, a path escaping the plugin, a non-executable script, monitors.json that is not an array, an empty array, a missing README, a missing marketplace entry, a mismatched plugin.json name, and a deleted template. Plus two positives: a monitor with no bundled script passes, and hooks still validate.

9 pr-policy scenarios: one hook passes, one monitor passes, a hook and a monitor together fails, two monitors fails, two hooks still fails, an unregistered monitor fails, a monitor with no README row fails, a monitor plus a template change fails, and an infrastructure-only change passes.

Suggested next step

Land this, then a first real monitor as a separate PR to set the example. A log tail for Shopware or Symfony is the obvious candidate, since it demonstrates the filtering discipline better than anything abstract.

🤖 Generated with Claude Code