codex-plugin-doctor

Codex Plugin Doctor

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

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 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
• optional Docker isolation for local Node.js stdio servers with --sandbox docker

MCP Protocol Discovery

Inspect an HTTP MCP endpoint's advertised protocol versions using a bounded MCP 2026-07-28 server/discover request:

codex-plugin-doctor doctor discover https://mcp.example.com/mcp --allow-network
codex-plugin-doctor doctor discover https://mcp.example.com/mcp --allow-network --json

This is an opt-in discovery-only check. A successful result validates the discovery response, not full protocol conformance, tool behavior, or compatibility with a particular client. Existing check --runtime remains on its 2025-11-25 baseline. See MCP Discovery for consent, scope, and exit codes.

Offline MCP Tool Definitions

Inspect a saved MCP 2026-07-28 tools/list response without contacting a server:

codex-plugin-doctor doctor tools-file ./tools-list.json --json

This checks the supplied tool definitions and root-schema shapes within fixed file, tool, and finding limits. It does not establish server inventory completeness or execute tools. See Offline MCP Tool Definitions for the accepted input format, coverage, and exit codes.

Offline MCP Tool Diff

Compare two saved tool-list responses before updating a server or client:

codex-plugin-doctor doctor tools-diff --before ./tools-old.json --after ./tools-new.json --json

This reports added, removed, and structurally changed definitions using numeric locations, and labels each change breaking, compatible, or unclassified with fixed reason codes. Add --fail-on breaking to fail CI only on breaking or unclassified changes, --markdown for pull request tables, and --show-names locally to see tool names and the JSON Pointer of each reason. Incomplete inputs, invalid definitions, or duplicate names prevent a comparison. Impact labels follow nested object properties, array items, and common length and range bounds, but remain heuristics, not proof of compatibility. See Offline MCP Tool Diff for matching rules, privacy, limits, and exit codes.

MCP Tool Catalog

Inspect a modern HTTP MCP server's tool definitions without invoking them:

codex-plugin-doctor doctor tools https://mcp.example.com/mcp --allow-network --json

This opt-in command performs discovery and bounded tools/list pagination. It reports tool-definition and root-schema shape findings, explicit completion state, and partial inspection limits. It does not claim full schema validation, tool execution, or client compatibility. Existing doctor discover behavior is unchanged. Add --save-response <path> to record a completely enumerated catalog as a tools/list response for tools-file and tools-diff; nothing is written when enumeration is incomplete. For protected servers, --bearer-token-env <NAME> sends a bearer token from an environment variable only over HTTPS or to an approved loopback endpoint; it is never printed or saved. The GitHub Action can compare saved responses with tools-diff-before, tools-diff-after, and tools-diff-fail-on, capture the live list with tools-capture-url (and tools-capture-token-env) or, for a local stdio server with runtime: "true", tools-capture-server, and skip the plugin package check with check: "false" in repositories that only ship an MCP server. With tools-diff-comment: "true" it also posts the comparison as one pull request comment that later runs update. tools-capture-sandbox: docker starts a stdio server in the Docker sandbox, and codex-plugin-doctor init-ci . --tools-diff-server <name> --sandbox docker writes a pull request workflow that captures in one job and compares and comments in another.

Local stdio servers from a package's MCP configuration can be cataloged too. --runtime is required because this starts package code; the server is stopped after its tool list is read:

codex-plugin-doctor doctor tools ./my-plugin --server my-server --runtime --save-response ./tools-current.json

Doctor tries server/discover (2026-07-28) first and falls back to the initialize handshake for older stdio servers, so the saved list works with tools-file and tools-diff either way. --sandbox docker and --require-runtime-approval work as they do for check --runtime; add --env <NAME> to pass a host variable such as an API key into the Docker container by name. See MCP Tool Catalog.

MCP Prompt Catalog and Diff

Record a server's prompt list and catch prompt changes that break clients:

codex-plugin-doctor doctor prompts https://mcp.example.com/mcp --allow-network --save-response ./mcp/prompts-baseline.json
codex-plugin-doctor doctor prompts-diff --before ./mcp/prompts-baseline.json --after ./prompts-current.json --fail-on breaking

doctor prompts reads prompts/list from an HTTP server, or from a local stdio server with --server <name> --runtime, without retrieving any prompt. doctor prompts-file inspects a saved list offline, and doctor prompts-diff labels a removed prompt, a removed argument, or a newly required argument as breaking. Like the tool diff, reports omit names unless --show-names is given. The GitHub Action runs the same capture and comparison through prompts-* inputs and comments on pull requests, and init-ci --tools-diff-server <name> --prompts-baseline <path> writes that workflow. See MCP Prompt Catalog and Diff.

MCP Resource Template Catalog and Diff

codex-plugin-doctor doctor resource-templates https://mcp.example.com/mcp --allow-network --save-response ./mcp/resource-templates-baseline.json
codex-plugin-doctor doctor resource-templates-diff --before ./mcp/resource-templates-baseline.json --after ./resource-templates-current.json --fail-on breaking

doctor resource-templates reads resources/templates/list the same way, without reading any resource; resource-templates-file inspects a saved list, and resource-templates-diff labels a removed template, a changed URI template, or an added or removed template variable as breaking. Reports never include URI templates, and names appear only with --show-names. The GitHub Action and init-ci --tools-diff-server <name> --resource-templates-baseline <path> run the same comparison on pull requests. See MCP Resource Template Catalog and Diff.

Remote MCP Readiness

Remote MCP runtime probing is disabled until you explicitly pass --runtime --allow-network. Loopback endpoints also require --allow-local-network:

codex-plugin-doctor check ./remote-mcp --runtime --allow-network
codex-plugin-doctor check ./remote-mcp --runtime --allow-network --allow-local-network

The probe makes only bounded protocol and OAuth metadata-discovery requests, redacts report output, and applies SSRF controls. It does not authenticate or follow redirects.

Remote transport reliability adds one bounded SSE GET after initialization. HTTP 200 must be text/event-stream; HTTP 405 is compliant when the endpoint does not offer server-to-client SSE. At most one SSE resume and one session restart are attempted, and no remote response content is retained. This is a bounded readiness check, not a live interoperability, delivery-guarantee, or load-test claim.

--allow-session-lifecycle is disabled by default and is state-changing: only after a valid MCP-Session-Id it permits one bounded session DELETE. --require-remote-reliability is a strict result gate: it fails unless every attempted remote reliability scorecard passes. Local-only runs are unaffected. It grants no network consent, so --runtime --allow-network (and loopback consent when applicable) remain required. See Remote MCP Readiness and Remote MCP Transport Reliability.

MCP Registry Readiness

Validate official MCP Registry publication metadata without publishing or installing anything:

codex-plugin-doctor registry check path/to/server.json
codex-plugin-doctor registry check path/to/server.json --json --require-registry-readiness
codex-plugin-doctor registry inspect io.github.example/weather --allow-network

Local checks validate metadata, ownership consistency, package integrity, transports, and Codex installability. Exact Registry lookup is read-only, requires explicit network consent, and contacts only the fixed official Registry endpoint. It never follows advertised package, icon, repository, or remote MCP URLs. See MCP Registry Readiness.

MCP Registry Publication Preflight

Check a publication candidate locally without making a network request:

codex-plugin-doctor registry preflight path/to/server.json --json

Opt in to bounded public npm and MCP Registry metadata checks:

codex-plugin-doctor registry preflight path/to/server.json --allow-network --json

Require a publish-ready result in CI:

codex-plugin-doctor registry preflight path/to/server.json --allow-network --require-publish-ready --json

Preflight checks the exact npm package version, then the exact Registry version and latest Registry record on fixed public hosts. An existing exact Registry version is an immutable collision and must be replaced by a version bump. The command is advisory: it never authenticates, publishes, or changes npm or Registry records. See MCP Registry Publication Preflight.

Public Directory Submission Preflight

Check a plugin package for deterministic public-directory submission issues without contacting a portal:

codex-plugin-doctor doctor submission <path>
codex-plugin-doctor doctor submission <path> --json
codex-plugin-doctor doctor submission <path> --markdown
codex-plugin-doctor doctor submission <path> --require-ready
codex-plugin-doctor doctor submission archive <zip>
codex-plugin-doctor doctor submission archive <zip> --json --output submission-archive.json
codex-plugin-doctor doctor submission archive <zip> --markdown --output submission-archive.md
codex-plugin-doctor doctor submission archive <zip> --require-ready

The preflight is offline and non-executing: it does not submit a package, make network requests, start MCP servers, verify domains, or handle OAuth credentials. Its automatic status is pass or fail; a passing automatic result remains manual_review_required until portal-only review is complete. It never claims directory acceptance. See Public Directory Submission Preflight.

The archive variant accepts an existing skills-only ZIP and does not extract archive entries to disk, execute package code, or repair the archive. It reports malformed ZIP structures and deterministic package blockers; unsupported portal rules remain manual or coverage: unavailable rather than an automatic pass.

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: <repo>\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: <repo>\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 corpus --manifest ../private-corpus/corpus.json --json
codex-plugin-doctor doctor corpus metrics --manifest ../private-corpus/metrics.json --markdown
codex-plugin-doctor doctor corpus metrics --manifest ../private-corpus/metrics.json --json --min-precision 0.90 --min-recall 0.85 --max-false-positive-rate 0.10
codex-plugin-doctor doctor npm <published-plugin-package>
codex-plugin-doctor doctor npm <published-plugin-package> --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-plan . --sandbox docker --json
codex-plugin-doctor doctor runtime-policy .
codex-plugin-doctor doctor runtime-policy . --json --output runtime-policy.json
codex-plugin-doctor doctor runtime-policy . --sandbox docker --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:<approved-plan-digest>
codex-plugin-doctor check . --runtime --sandbox docker
codex-plugin-doctor check . --runtime --sandbox docker --require-runtime-approval --runtime-approval-digest sha256:<approved-docker-plan-digest>
codex-plugin-doctor release check .
codex-plugin-doctor release check . --json
codex-plugin-doctor release check . --runtime
codex-plugin-doctor release check . --runtime --require-runtime-approval --runtime-approval-digest sha256:<approved-plan-digest>
codex-plugin-doctor release check . --runtime --sandbox docker --require-runtime-approval --runtime-approval-digest sha256:<approved-docker-plan-digest>
codex-plugin-doctor check . --config .codex-doctor.json
codex-plugin-doctor baseline create . --output .codex-doctor-baseline.json
codex-plugin-doctor check . --baseline .codex-doctor-baseline.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

Docker runtime mode supports local Node.js stdio MCP servers. It uses a digest-pinned image, no network, read-only container and package filesystems, an unprivileged user, dropped capabilities, bounded resources, and a limited writable /tmp. It fails closed without native fallback and rejects package roots containing commas. The Docker daemon, base image, and host kernel remain trusted boundaries. Generate approval digests with the same --sandbox docker backend used for execution. See Runtime Approval And Sandboxing.

External corpus evaluation is static and offline. doctor corpus --manifest <corpus.json> validates anonymized local snapshots using stable content digests and exact finding fingerprints without downloading dependencies or starting target servers. Reports omit manifest and package paths and fail on digest drift, missing expected findings, present disputed findings, or unreviewed findings. See Real-World Validation.

doctor corpus metrics --manifest <corpus.json> measures reviewed true positives, false positives, and false negatives as precision, recall, and emitted-finding false-positive share. Optional thresholds make the measurement release-gating; incomplete reviews and digest drift return exit 2 instead of producing a favorable score. The dedicated metrics manifest stays offline, requires contained snapshot paths, and may record immutable HTTPS Git provenance without fetching it.

doctor corpus metrics diff --before <metrics.json> --after <metrics.json> compares two complete metrics reports from the same corpus identity. Add --fail-on-regression to fail CI when precision or recall decreases, or when the reviewed emitted-finding false-positive share increases. Reports with different corpusDigest values are rejected as non-comparable, and diff output never includes the input report paths.

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 <package> 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 <path> 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 <attestation.json> --target <path> --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 <path> 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 <path> evaluates the same runtime plan and security signals, then recommends allow, review, sandbox_recommended, or deny before local MCP execution starts. doctor review-bundle <path> --output <dir> --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 <bundle-dir> --target <path> --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 <dir> --after <dir> 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 <digest> refuses to run runtime probes unless the current plan digest matches the approved digest. doctor release-evidence <path> --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-evidence verify <evidence.json> --target <path> --sign-key-env NAME verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME writes a signed release evidence file and prints the gh release upload command; add --upload to run the upload through GitHub CLI with --clobber. doctor inspector <path> builds a safe MCP Inspector launch command from a packaged .mcp.json file without starting the Inspector proxy automatically. Use --server <name> when the package contains multiple MCP server entries. doctor diff --before <path> --after <path> compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. doctor recommend <path> turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add --json for automation or --output recommendations.json to write the report to disk. doctor trust <path> creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. doctor perf <path> profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. Add --max-total-ms <ms> or repeatable --max-stage-ms stage=ms to fail CI when a budget is exceeded. doctor mcp <path> exposes the generic MCP static health report under the doctor command family without starting local MCP servers. doctor export --bundle <path> creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. doctor snapshot creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add --json for machine-readable output or --output doctor-snapshot.json to write the bundle to disk. doctor clients reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. doctor --update-check compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.

audit --installed runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add --security to include security scorecards, --compat to include the all-client compatibility matrix, and --json --output local-audit.json when you want a shareable machine-readable report. Add --cache to reuse unchanged plugin results between runs; add --changed to only report plugins whose fingerprint changed since the last cached audit. Use --cache-file path/to/audit-cache.json when CI or scripted runs need an explicit cache location.

audit deps <path> runs npm audit --json for the target package and normalizes dependency vulnerability results into a stable schemaVersion: "1.0.0" report. Use --json --output dependency-audit.json when CI needs machine-readable status, vulnerability counts, and the raw npm audit payload. Add --recommend to include prioritized remediation actions for direct upgrades, direct no-fix packages, transitive parent updates, and manual transitive review.

watch <path> continuously validates a plugin package after file changes. Use --debounce-ms <ms> to tune noisy repositories, --runtime when runtime probes are required, and --json --output watch-latest.json when another process should consume the latest validation snapshot.

init-git-hooks [path] installs generated pre-commit and pre-push hooks that run Codex Plugin Doctor validation before local commits and pushes. Add --force to overwrite existing hooks and --json when setup automation needs the written hook paths.

--policy codex-publish|mcp-strict|security applies opinionated gates without requiring a local .codex-doctor.json. codex-publish fails warnings and enables runtime probes for release checks, mcp-strict does the same for MCP-heavy packages, and security fails warning-level security findings so advisory risks can block a local audit or CI gate.

mcp <path> diagnoses generic MCP packages that may not have a Codex plugin manifest. It looks for .mcp.json or a manifest mcpServers reference, validates the top-level mcpServers object and server transports, adds MCP command-surface security findings, and includes the all-client compatibility matrix in the same report.

init [path] --template ... creates targeted starter packages. skill-only is the default minimal skill package, mcp-stdio adds a local stdio MCP config and mock server, mcp-http scaffolds a streamable HTTP MCP config, and full-runtime generates a stdio sample that passes the runtime protocol probes.

security <path> renders a focused package security scorecard. It reuses the existing package security findings, then adds deeper MCP command-surface checks for shell wrappers, encoded shell payloads, remote pipe-to-shell startup patterns, cwd values outside the plugin root, and plain HTTP URLs. Findings include structured, instance-specific evidence such as manifest fields, skill paths, server names, protocol methods, dependency sections, env keys, and bounded payload lengths. Deterministic SHA-256 fingerprints derive from the rule ID and canonical evidence, with package paths normalized for cross-machine stability. Secrets, prompt bodies, resource contents, tool payloads, stderr, and encoded commands are not copied into evidence. Use --json for automation or --scorecard for a compact status view.

compat --client claude-desktop checks whether the MCP package can be added to the local Claude Desktop setup. On Windows it looks for %APPDATA%\Claude\claude_desktop_config.json; on macOS it looks for ~/Library/Application Support/Claude/claude_desktop_config.json. A valid existing config returns PASS, a missing Claude Desktop install returns WARN, and a malformed local config returns FAIL so you do not add new servers into a broken config file. If the package server name already exists in Claude Desktop, the command returns WARN with the duplicate server name. Add --install-preview to print the JSON snippet that should be merged into claude_desktop_config.json; it does not modify files. Use --apply --backup only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.

compat --client cursor checks whether the MCP package can be added to Cursor. It prefers a project-level .cursor/mcp.json when one already exists in the target package, then falls back to the global ~/.cursor/mcp.json path. A valid existing config returns PASS, a missing Cursor config returns WARN, malformed JSON returns FAIL, and duplicate MCP server names return WARN. Add --install-preview to print the JSON snippet that should be merged into Cursor's mcp.json; it does not modify files. Use --apply --backup only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.

compat --client cline checks whether the MCP package can be added to Cline. It uses CLINE_DIR/data/settings/cline_mcp_settings.json when CLINE_DIR is set, otherwise ~/.cline/data/settings/cline_mcp_settings.json. Add --install-preview to print the JSON snippet that should be merged into cline_mcp_settings.json.

compat --all makes the all-client matrix explicit when you want Codex, Generic MCP, Claude Desktop, Cursor, Cline, and Windsurf in one run. compat --scorecard turns the compatibility matrix into a compact score summary. PASS maps to 100, WARN maps to 70, and FAIL or SKIPPED maps to 0.

check --installed --compat --all-summary validates every discovered Codex plugin from the local plugin cache and appends a compact compatibility summary for Codex, Generic MCP, Claude Desktop, Cursor, Cline, and Windsurf. This is the fastest repo-free audit when a user does not know individual plugin paths.

check --profile ci|strict|publish applies named validation policies. ci keeps default behavior, strict fails on warnings, and publish fails on warnings while enabling runtime probing by default.

check --explain adds a deduplicated Next Actions summary plus inline rule catalog context to text reports, including the problem summary, rule category, why a finding matters, a more detailed fix path, a compact example, and the matching codex-plugin-doctor explain <finding-id> follow-up command.

check --badge-json emits Shields endpoint-compatible JSON such as {"schemaVersion":1,"label":"doctor","message":"PASS","color":"brightgreen"}. check --badge-markdown emits a static shields.io Markdown badge for README or release notes. Badge output is intentionally limited to single package checks, not check --installed.

check --history <path> appends a compact JSONL validation snapshot after a single package check. history <path> reads the JSONL file and compares the latest run to the previous run, including status, finding-count deltas, and whether the latest run regressed. Add history --json for automation output or history --fail-on-regression when CI should fail after a worse latest run.

baseline create <path> --output <path> records the current fingerprinted findings for gradual CI adoption. A later check <path> --baseline <path> keeps matched findings visible in baseline metadata but gates only new active findings; reports summarize new, matched, and resolved counts. Commit the baseline for review and regenerate it deliberately after accepted findings change.

fix --dry-run renders safe automatic fix plans without changing files. fix --interactive --backup shows the same numbered plan, then applies everything after yes or only selected action numbers such as 1,3. fix --apply --backup applies supported safe fixes, such as manifest defaults and missing skills directories, after creating backups.

Optional local policy file:

{
  "ignoreRules": ["plugin.heuristic.description.too_long"],
  "suppressions": [
    {
      "fingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "reason": "Accepted until the upstream package layout is corrected.",
      "expiresAt": "2026-07-31"
    }
  ],
  "failOnWarnings": true
}

ignoreRules disables every finding with a matching rule ID. Prefer suppressions when accepting one specific finding instance: each record requires the exact 64-character lowercase SHA-256 fingerprint shown in Doctor reports, a non-empty review reason, and a real YYYY-MM-DD expiration date.

Active suppressions remove only the matching finding from the active result and preserve it under suppressedFindings for audit output. Expired or invalid records do not suppress findings; Doctor emits suppression.expired or suppression.invalid warnings instead. Duplicate active records use the first valid match.

Manage suppressions

codex-plugin-doctor suppress add .
codex-plugin-doctor suppress list .
codex-plugin-doctor suppress remove .

Interactive add selects one active fingerprinted finding and defaults to an expiration 30 local calendar days from today. The stored YYYY-MM-DD record remains active through that UTC calendar date and expires at 00:00 UTC on the following day. Suppressions match only the exact finding fingerprint; invalid or expired records never hide findings.

For automation, supply all add fields or one remove selector and add --json when machine-readable output is required:

codex-plugin-doctor suppress add . --fingerprint <sha256> --reason "Accepted temporarily." --expires-at 2026-07-31 --json
codex-plugin-doctor suppress list . --json
codex-plugin-doctor suppress remove . --index 0 --json
codex-plugin-doctor suppress remove . --fingerprint <sha256> --json

Run these when you want Codex Plugin Doctor to find plugins from the local Codex installation:

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 check --installed github
codex-plugin-doctor check --installed github --runtime --no-animations
codex-plugin-doctor explain plugin.security.hard_coded_secret

GitHub Action

name: Validate Codex plugin

on:
  pull_request:

jobs:
  doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: Esquetta/CodexPluginDoctor@v1.80.0
        with:
          version: "1.80.0"
          path: .
          runtime: "true"
          policy: codex-publish
          corpus: "true"
          contract: "true"
          upload-artifact: "true"
          artifact-name: codex-plugin-doctor-reports
          review-bundle: "true"
          review-bundle-verify: "true"

The action writes codex-plugin-doctor-summary.md, codex-plugin-doctor-report.json, codex-plugin-doctor-action-manifest.json, optional codex-plugin-doctor.sarif, optional validation corpus and quality metrics reports, optional output-contract.json, and optional signed review-bundle/ files to codex-plugin-doctor-reports, appends the Markdown report to the GitHub Actions step summary, uploads the report directory as an artifact, and then returns the real validation exit code. Set submission: "true" to add offline submission preflight reports; set require-submission-ready: "true" only with that opt-in to make automatic blockers fail the job. Review bundle generation requires a signing key environment variable such as CODEX_PLUGIN_DOCTOR_SIGNING_KEY. For runtime probing, SARIF output, corpus quality regression gates, corpus and contract artifacts, review bundle artifacts, installed plugin cache checks, CI policy presets, and pinned release examples, see GitHub Action Usage.

To self-test this repository after cloning it:

codex-plugin-doctor check examples/codex-doctor-runtime --runtime --no-animations

Repository Layout

docs/                 Public architecture, guides, rules, security, and contributor docs
examples/             Manual plugin packs for local CLI testing
src/                  CLI, validation logic, runtime probing, reports
tests/                Fixture-based regression tests

Validation Evidence

The validator is tuned against local fixtures and real marketplace-style plugin packages. See:

• Real-World Validation Workflow
• Examples
• Rule Catalog
• Official Plugin Components

Recent validation waves covered:

• curated Codex plugin cache packages
• marketplace-style plugin snapshots
• YAML block-scalar skill metadata
• media and visual workflow metadata

Release Readiness

Release preparation is reproducible from the repository:

npm run prepare-release
npm run release-check

prepare-release runs tests, builds the TypeScript output, and performs npm pack --dry-run. release-check adds release preflight checks for a clean git tree, existing npm versions, existing version tags, package/lockfile/changelog version consistency, tests, build, pack dry-run, fresh temp install audit, and publish dry-run.

For plugin packages, codex-plugin-doctor release check . performs static readiness checks by default. Runtime probing executes package-local MCP servers and therefore requires an explicit --runtime; protected workflows can also require the approved runtime-plan digest.

Related docs:

• Changelog
• Contributing
• Security Policy
• Code of Conduct
• NPM Release Checklist
• Release Candidate Workflow
• Versioning and Releases

Contributing

Contributions are welcome once the repository is public. Start with:

• Contributing
• Security Policy
• Validation tuning issue template

Support

If this tool saves you time, GitHub stars and sponsorship help signal that the project is worth continuing.

• Star the repository on GitHub.
• Use GitHub Sponsors through the repository funding link.
• Open validation tuning issues for false positives or false negatives.

Product Direction

Codex Plugin Doctor starts as a Codex-specific validator and can grow into a broader MCP Doctor over time.

The immediate goal is not a marketplace, dashboard, or hosted website. The immediate goal is a trustworthy local preflight check for Codex-compatible plugin bundles.