CodexPluginDoctor

Codex Plugin Doctor

[](https://github.com/Esquetta/CodexPluginDoctor/actions/workflows/ci.yml) [](https://www.npmjs.com/package/codex-plugin-doctor) [](./LICENSE) [](https://github.com/Esquetta/CodexPluginDoctor/releases)

Codex Plugin Doctor is a local CLI validator for Codex plugin packages, skills, and MCP server bundles.

It catches packaging, metadata, security, and runtime protocol problems before a plugin reaches users, teammates, or release workflows.

Status

Codex Plugin Doctor is a public stable CLI for local and CI validation.

• Primary surface: GitHub repository and npm package
• Distribution today: npm install -g, local source install, npm link, npm pack, GitHub Releases
• Public npm package: codex-plugin-doctor
• License: [MIT](./LICENSE)

1.0 Stability

The 1.0 line is the stable compatibility baseline for plugin authors and CI consumers.

• Public JSON schema surfaces and existing rule IDs/default severities are treated as stable through 1.0.
• Runtime probing remains opt-in because it executes package-local MCP servers.
• The project remains Codex-first; broader MCP Doctor positioning stays a post-1.0 expansion path.
• Post-1.0 feature work should stay additive unless a documented major-version decision is made.

See the [documentation index](./docs/README.md) for architecture, usage, security, and contributor guides.

Why This Exists

Codex plugin packages can fail in several places:

• the package manifest is missing or points outside the package root
• skills exist but do not expose valid SKILL.md metadata
• .mcp.json is malformed or references unsafe secrets
• an MCP server starts but does not complete the protocol handshake
• tools, resources, or prompts list successfully but fail deeper runtime checks
• verbose metadata creates noisy matching and unnecessary context cost

This tool gives plugin authors a repeatable preflight check before distribution.

What It Checks

Static validation:

• required .codex-plugin/plugin.json
• manifest fields: name, version, description
• skill directory wiring
• SKILL.md presence and frontmatter fields
• YAML single-line and block-scalar skill descriptions
• .mcp.json structure
• path traversal risks
• hard-coded secret-like env values
• description quality heuristics tuned against real plugin packages

Security scorecard with security:

• shell wrapper command warnings for MCP servers
• encoded shell command failures
• remote content piped into shell failures
• MCP server cwd paths that escape the package root
• plain HTTP remote transport warnings

Runtime MCP validation with --runtime:

• initialize
• notifications/initialized
• tools/list
• tools/call
• resources/list
• resources/read
• resources/templates/list
• prompts/list
• prompts/get
• paginated list responses
• runtime capability scorecard
• redacted verbose transcript with --verbose-runtime
• optional runtime approval gating with a precomputed doctor runtime-plan digest

Output formats:

• human text output
• JSON reports
• Markdown reports
• Shields-compatible badge JSON and static badge Markdown
• validation history JSONL and trend summaries
• deterministic local attestation artifacts
• output contract and rule catalog freeze metadata
• bundled validation corpus reports
• --output file writing
• CI summary and artifact generation

Quick Start

Global install from npm:

npm install -g codex-plugin-doctor
codex-plugin-doctor --version
codex-plugin-doctor self-test
codex-plugin-doctor check path/to/plugin-package

Run codex-plugin-doctor check . from the root of a Codex plugin package that contains .codex-plugin/plugin.json. The Codex Plugin Doctor source repository is not itself a plugin package.

If you already have Codex installed locally and do not know plugin paths, discover the installed plugin cache:

codex-plugin-doctor list --installed
codex-plugin-doctor check --installed
codex-plugin-doctor check --installed --all-summary
codex-plugin-doctor check --installed --compat --all-summary
codex-plugin-doctor audit --installed --security --compat
codex-plugin-doctor audit --installed --security --compat --policy security
codex-plugin-doctor mcp path/to/mcp-package
codex-plugin-doctor check --installed github
codex-plugin-doctor explain plugin.manifest.missing

Run from source:

npm install
npm run build
node dist/cli.js check examples/codex-doctor-runtime --runtime

For local global usage:

npm link
codex-plugin-doctor check examples/codex-doctor-runtime --runtime

Generate validation artifacts locally:

npm run generate-validation-artifacts -- --target examples/codex-doctor-runtime --runtime-target examples/codex-doctor-runtime --out-dir validation-artifacts-local

Example Output

Passing runtime package:

Codex Plugin Doctor
===================
Status: PASS
Target: \examples\codex-doctor-runtime
Summary: 0 fail, 0 warn, 0 total

Runtime Scorecard
----------------
initialize: pass
tools/list: pass
tools/call: pass
resources/list: pass
resources/read: pass
resources/templates/list: pass
prompts/list: pass
prompts/get: pass

No findings.

Risky package:

Codex Plugin Doctor
===================
Status: FAIL
Target: \examples\codex-doctor-risky
Summary: 1 fail, 0 warn, 1 total

Failures
--------
x plugin.security.hard_coded_secret
  Message: The MCP server `dangerServer` contains a hard-coded secret-like env value for `OPENAI_API_KEY`.
  Impact: Hard-coded credentials inside plugin bundles increase leakage risk and make secure rotation difficult.
  Suggested fix: Replace the literal value for `OPENAI_API_KEY` with an environment reference or injected secret outside the package.

Useful Commands

Run these from a Codex plugin package root:

codex-plugin-doctor --version
codex-plugin-doctor self-test
codex-plugin-doctor doctor
codex-plugin-doctor doctor contract
codex-plugin-doctor doctor contract --json --output output-contract.json
codex-plugin-doctor doctor corpus
codex-plugin-doctor doctor corpus --json --output validation-corpus.json
codex-plugin-doctor doctor npm 
codex-plugin-doctor doctor npm  --json --output npm-preinstall.json
codex-plugin-doctor doctor attest .
codex-plugin-doctor doctor attest . --json --output attestation.json
codex-plugin-doctor doctor attest . --json --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY --output attestation.json
codex-plugin-doctor doctor attest verify attestation.json --target . --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
codex-plugin-doctor doctor attest verify attestation.json --target . --json --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
codex-plugin-doctor doctor inspector .
codex-plugin-doctor doctor inspector . --server context7 --json --output inspector-command.json
codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin
codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin --json --output risk-diff.json
codex-plugin-doctor doctor recommend .
codex-plugin-doctor doctor recommend . --json --output recommendations.json
codex-plugin-doctor doctor trust .
codex-plugin-doctor doctor trust . --json --output trust-score.json
codex-plugin-doctor doctor perf .
codex-plugin-doctor doctor perf . --json --output perf.json
codex-plugin-doctor doctor perf . --max-total-ms 2500 --max-stage-ms validation=500
codex-plugin-doctor doctor runtime-plan .
codex-plugin-doctor doctor runtime-plan . --json --output runtime-plan.json
codex-plugin-doctor doctor runtime-plan . --markdown --output runtime-plan.md
codex-plugin-doctor doctor runtime-policy .
codex-plugin-doctor doctor runtime-policy . --json --output runtime-policy.json
codex-plugin-doctor doctor review-bundle . --output review-bundle --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
codex-plugin-doctor doctor review-bundle verify review-bundle --target . --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
codex-plugin-doctor doctor review-bundle diff --before old-review-bundle --after review-bundle
codex-plugin-doctor doctor mcp .
codex-plugin-doctor doctor mcp . --json --output mcp-healthcheck.json
codex-plugin-doctor doctor export --bundle .
codex-plugin-doctor doctor export --bundle . --output doctor-bundle.json
codex-plugin-doctor doctor snapshot
codex-plugin-doctor doctor snapshot --json
codex-plugin-doctor doctor snapshot --output doctor-snapshot.json
codex-plugin-doctor doctor clients
codex-plugin-doctor doctor --update-check
codex-plugin-doctor audit --installed
codex-plugin-doctor audit --installed --security --compat
codex-plugin-doctor audit --installed --security --compat --json --output local-audit.json
codex-plugin-doctor audit --installed --security --compat --cache
codex-plugin-doctor audit --installed --changed --cache
codex-plugin-doctor audit deps .
codex-plugin-doctor audit deps . --json --output dependency-audit.json
codex-plugin-doctor audit deps . --recommend
codex-plugin-doctor audit deps . --recommend --json --output dependency-remediation.json
codex-plugin-doctor watch .
codex-plugin-doctor watch . --json --output watch-latest.json --debounce-ms 500
codex-plugin-doctor init-git-hooks .
codex-plugin-doctor init-git-hooks . --json
codex-plugin-doctor mcp .
codex-plugin-doctor mcp . --json
codex-plugin-doctor mcp . --json --output mcp-doctor.json
codex-plugin-doctor init my-plugin
codex-plugin-doctor init my-mcp --template mcp-stdio
codex-plugin-doctor init remote-mcp --template mcp-http
codex-plugin-doctor init runtime-demo --template full-runtime
codex-plugin-doctor security .
codex-plugin-doctor security . --scorecard
codex-plugin-doctor security . --json
codex-plugin-doctor security . --policy security
codex-plugin-doctor compat .
codex-plugin-doctor compat . --all --scorecard
codex-plugin-doctor compat . --client codex
codex-plugin-doctor compat . --client generic-mcp
codex-plugin-doctor compat . --client claude-desktop
codex-plugin-doctor compat . --client claude-desktop --install-preview
codex-plugin-doctor compat . --client claude-desktop --apply --backup
codex-plugin-doctor compat . --client cursor
codex-plugin-doctor compat . --client cursor --install-preview
codex-plugin-doctor compat . --client cursor --apply --backup
codex-plugin-doctor compat . --client cline
codex-plugin-doctor compat . --client cline --install-preview
codex-plugin-doctor compat . --scorecard
codex-plugin-doctor compat . --json
codex-plugin-doctor compat . --json --output compatibility.json
codex-plugin-doctor check .
codex-plugin-doctor check . --profile ci
codex-plugin-doctor check . --profile strict
codex-plugin-doctor check . --profile publish
codex-plugin-doctor check . --policy codex-publish
codex-plugin-doctor check . --policy mcp-strict
codex-plugin-doctor check . --policy security
codex-plugin-doctor check . --json
codex-plugin-doctor check . --explain
codex-plugin-doctor check . --json --output report.json
codex-plugin-doctor check . --markdown --output report.md
codex-plugin-doctor check . --badge-json --output doctor-badge.json
codex-plugin-doctor check . --badge-markdown
codex-plugin-doctor check . --sarif --output results.sarif
codex-plugin-doctor check . --ascii
codex-plugin-doctor check . --no-animations
codex-plugin-doctor check . --runtime
codex-plugin-doctor check . --runtime --require-runtime-approval --runtime-approval-digest sha256:
codex-plugin-doctor check . --config .codex-doctor.json
codex-plugin-doctor check . --history validation-history.jsonl
codex-plugin-doctor history validation-history.jsonl
codex-plugin-doctor history validation-history.jsonl --json
codex-plugin-doctor history validation-history.jsonl --fail-on-regression
codex-plugin-doctor fix . --dry-run
codex-plugin-doctor fix . --interactive --backup
codex-plugin-doctor fix . --apply --backup
codex-plugin-doctor check . --json --runtime --verbose-runtime

self-test runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after npm install -g codex-plugin-doctor.

doctor checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. doctor contract publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add --json for automation or --output output-contract.json to write the contract to disk. doctor corpus runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add --json for automation or --output validation-corpus.json to write the corpus report to disk. doctor npm runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. The JSON report includes tarball metadata such as filename, path, integrity, shasum, sizes, file count, and extracted package root so automation can prove which archive was scanned. Use a published Codex plugin package as the target; scanning codex-plugin-doctor itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add --json for automation or --output npm-preinstall.json to write the report to disk. doctor attest creates a local attestation with stable package/report digests, validation/security/compatibility/trust summary, and verification metadata. Add --sign-key-env NAME to attach a local HMAC-SHA256 signature without printing the secret, or --json --output attestation.json to write the artifact to disk. doctor attest verify --target --sign-key-env NAME recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats generatedAt, targetPath, verification, and signature.keyHint as unsigned display metadata. doctor runtime-plan creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. Add --markdown --output runtime-plan.md to preserve a review-ready approval artifact with the execution boundary, checklist, servers, probes, and risk reasons. doctor runtime-policy evaluates the same runtime plan and security signals, then recommends allow, review, sandbox_recommended, or deny before local MCP execution starts. doctor review-bundle --output --sign-key-env NAME writes a signed review directory with runtime plan, runtime policy, attestation, release evidence, manifest, Markdown summary files, and SHA-256 file integrity digests. doctor review-bundle verify --target --sign-key-env NAME verifies the bundle manifest, expected files, manifest integrity digests, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. doctor review-bundle diff --before --after compares two review bundles and flags risk-increasing changes in status, runtime policy, release readiness, signatures, release evidence, and runtime plan digest. check --runtime --require-runtime-approval --runtime-approval-digest refuses to run runtime probes unless the current plan digest matches the approved digest. doctor release-evidence --sign-key-env NAME creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use --allow-dirty or --allow-untagged only for local rehearsal. `doctor release

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Esquetta
• Source: Esquetta/CodexPluginDoctor
• License: MIT

Install and usage instructions live in the source repository linked above.