How do I run `claude plugin validate --strict` on a plugin?

To make claude plugin validate --strict fail when a plugin's TypeScript hooks have type problems, update to Claude Code 2.1.323, released on November 12, 2026, and run it on your plugin folder. The type check arrived in that version. Each finding is a warning, and --strict turns every warning into exit code 1.

This site is independent and not affiliated with Anthropic. We read the changelog and Anthropic's plugin documentation on 2026-11-13. We did not run the command, so nothing below is a hands-on result, and we show no sample output.

What the command checks

Anthropic's plugin commands reference describes claude plugin validate in one sentence: "Validate a plugin manifest, a marketplace manifest, or the skills, agents, and commands in a directory, and exit with a code a CI job can act on."

Given a folder, it picks what to check by what it finds there:

• .claude-plugin/marketplace.json, when it exists
• otherwise .claude-plugin/plugin.json
• otherwise the skills, agents and commands files, chosen by the folder's name

So you can point it at a finished plugin or at a plain .claude folder of skills. If you are still writing your first skill, our guide to creating a Claude Code skill comes first.

What 2.1.323 changed

Anthropic's changelog has two lines for 2.1.323 that touch this command. The first is the one most plugin authors will feel:

Added type checking of a plugin's TypeScript hooks module to claude plugin validate; each finding is a warning, and --strict fails on it

The second only matters if you write mods:

Changed claude plugin validate to fail a mod whose engine.create hook isn't written in the one accepted form; installed mods keep loading

Our reading of the first line: from 2.1.323, a type mistake in a hooks module shows up as a warning, and --strict makes it block. The changelog does not say what the command did before. The second line says "fail", not "warn", and it adds that installed mods keep loading.

The Claude moves worth stealing, by email

Workflows tested on real jobs, sent only when they are worth it. Free.

Subscribe

Run it before you commit

The flag's job, in Anthropic's words, is to "Treat warnings as errors, so unrecognized fields and missing metadata that the runtime tolerates fail the run". That is the gap between a plugin that loads and a plugin that is clean.

The command from the reference looks like this:

claude plugin validate ./my-plugin --strict

You can also stay inside a session. The same page lists /plugin validate <path> and says it "Prints the same report as claude plugin validate, inline".

Reading the verdict

The reference gives three exit codes. Anthropic's table pairs each with a verdict line:

Exit code	Verdict line	Meaning, per the reference
0	Validation passed or Validation passed with warnings	"The manifest loads. With --strict, no warnings either"
1	Validation failed or Validation failed (--strict treats warnings as errors)	An error, or a warning under --strict
2	Unexpected error during validation: <reason>	"The validator itself failed, such as on an unreadable path"

Without the flag, a run that prints Validation passed with warnings still exits 0. That is why a CI job that only checks the exit code lets warnings through. Add --strict and the same run exits 1.

One output block never changes the result. The reference says an Advice block "doesn't change the verdict line or the exit code, with or without --strict". It appears when a plugin's README has no install line.

Put it in a CI job

The reference says the command was built so "a CI job can act on" its exit code. Its flag table also lists --json, which outputs "the validation report as one JSON object with the same exit codes" and "Requires Claude Code v2.1.259 or later".

A simple setup is the --strict command from above as a required check on every pull request. Add --json when you want a script to read the report. We have not run either form in a pipeline.

Plugin authors who want a score on top of a pass can read our guide to claude plugin eval, which covers a different command. Mod authors will find the context in our Claude Code mods guide.

Where this does not help

• We did not run it. We have no output to show and cannot confirm what a TypeScript finding looks like.
• The documentation does not describe the type check. In the pages we read, the changelog line is the only source for it. We cannot say which compiler options it uses or which files it reads.
• A pass is not a safety review. Validation checks structure and types. It does not tell you whether a hook does something you would not want, so read third-party code yourself.
• Older versions behave differently. On versions before 2.1.281, Anthropic's manifest reference says a --strict run fails on Unknown field warnings for directory listing fields such as icon.
• Warnings can be noise. A plugin with a missing description fails --strict, though it loads fine.

If you see a message you do not understand, Anthropic keeps a troubleshooting page that pairs each validation message with its fix.

Does --strict fail on warnings in Claude Code 2.1.323?

Yes. Anthropic's reference says --strict treats warnings as errors, so a run that would print Validation passed with warnings exits 1 instead of 0. The 2.1.323 changelog adds that each TypeScript hooks finding is a warning, so --strict fails on it.

What does exit code 2 mean in claude plugin validate?

Exit code 2 means the validator itself failed, not your plugin. Anthropic's reference gives an unreadable path as an example. The reference says the message goes to stderr and the command writes nothing to stdout.

Can I validate a plugin from inside a Claude Code session?

Yes. Type /plugin validate <path> in a session. Anthropic's reference says it prints the same report as claude plugin validate, inline. For a script or a CI job, run claude plugin validate from your shell instead, because you need the exit code.

Sources (checked 2026-11-13)

• Claude Code changelog: the 2.1.323 entry (November 12, 2026).
• Plugin commands reference: the plugin validate section, flags and exit codes.
• Plugin manifest reference: warnings, --strict and the validate section.
• Troubleshoot plugins: each validation message with its fix.

We will mention it in the newsletter if Anthropic documents the TypeScript check.