{"id":49689731,"url":"https://github.com/esquetta/codexplugindoctor","last_synced_at":"2026-06-08T08:01:18.421Z","repository":{"id":354595531,"uuid":"1217828506","full_name":"Esquetta/CodexPluginDoctor","owner":"Esquetta","description":"Local CLI validator for Codex plugin packages, skills, and MCP server bundles.","archived":false,"fork":false,"pushed_at":"2026-05-31T08:30:30.000Z","size":1360,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T10:12:47.448Z","etag":null,"topics":["cli","codex","developer-tooling","mcp","mcp-server","openai","plugin","skills","typescript","validation"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Esquetta.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Esquetta"}},"created_at":"2026-04-22T09:00:08.000Z","updated_at":"2026-05-31T08:29:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Esquetta/CodexPluginDoctor","commit_stats":null,"previous_names":["esquetta/codexplugindoctor"],"tags_count":43,"template":false,"template_full_name":null,"purl":"pkg:github/Esquetta/CodexPluginDoctor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esquetta%2FCodexPluginDoctor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esquetta%2FCodexPluginDoctor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esquetta%2FCodexPluginDoctor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esquetta%2FCodexPluginDoctor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Esquetta","download_url":"https://codeload.github.com/Esquetta/CodexPluginDoctor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esquetta%2FCodexPluginDoctor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34053435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","codex","developer-tooling","mcp","mcp-server","openai","plugin","skills","typescript","validation"],"created_at":"2026-05-07T13:04:54.039Z","updated_at":"2026-06-08T08:01:18.396Z","avatar_url":"https://github.com/Esquetta.png","language":"TypeScript","funding_links":["https://github.com/sponsors/Esquetta"],"categories":[],"sub_categories":[],"readme":"# Codex Plugin Doctor\n\n[![CI](https://github.com/Esquetta/CodexPluginDoctor/actions/workflows/ci.yml/badge.svg)](https://github.com/Esquetta/CodexPluginDoctor/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/codex-plugin-doctor.svg)](https://www.npmjs.com/package/codex-plugin-doctor)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)\n[![GitHub release](https://img.shields.io/github/v/release/Esquetta/CodexPluginDoctor)](https://github.com/Esquetta/CodexPluginDoctor/releases)\n\nCodex Plugin Doctor is a local CLI validator for Codex plugin packages, skills, and MCP server bundles.\n\nIt catches packaging, metadata, security, and runtime protocol problems before a plugin reaches users, teammates, or release workflows.\n\n## Status\n\nCodex Plugin Doctor is a public stable CLI for local and CI validation.\n\n- Primary surface: GitHub repository and npm package\n- Distribution today: `npm install -g`, local source install, `npm link`, `npm pack`, GitHub Releases\n- Public npm package: `codex-plugin-doctor`\n- License: [MIT](./LICENSE)\n\n## 1.0 Stability\n\nThe 1.0 line is the stable compatibility baseline for plugin authors and CI consumers.\n\n- Public JSON schema surfaces and existing rule IDs/default severities are treated as stable through 1.0.\n- Runtime probing remains opt-in because it executes package-local MCP servers.\n- The project remains Codex-first; broader MCP Doctor positioning stays a post-1.0 expansion path.\n- Post-1.0 feature work should stay additive unless a documented major-version decision is made.\n\nSee [v1.0 Readiness Checklist](./docs/engineering/v1.0-readiness-checklist.md) for the stable release evidence and smoke plan.\n\n## Why This Exists\n\nCodex plugin packages can fail in several places:\n\n- the package manifest is missing or points outside the package root\n- skills exist but do not expose valid `SKILL.md` metadata\n- `.mcp.json` is malformed or references unsafe secrets\n- an MCP server starts but does not complete the protocol handshake\n- tools, resources, or prompts list successfully but fail deeper runtime checks\n- verbose metadata creates noisy matching and unnecessary context cost\n\nThis tool gives plugin authors a repeatable preflight check before distribution.\n\n## What It Checks\n\nStatic validation:\n\n- required `.codex-plugin/plugin.json`\n- manifest fields: `name`, `version`, `description`\n- skill directory wiring\n- `SKILL.md` presence and frontmatter fields\n- YAML single-line and block-scalar skill descriptions\n- `.mcp.json` structure\n- path traversal risks\n- hard-coded secret-like env values\n- description quality heuristics tuned against real plugin packages\n\nSecurity scorecard with `security`:\n\n- shell wrapper command warnings for MCP servers\n- encoded shell command failures\n- remote content piped into shell failures\n- MCP server `cwd` paths that escape the package root\n- plain HTTP remote transport warnings\n\nRuntime MCP validation with `--runtime`:\n\n- `initialize`\n- `notifications/initialized`\n- `tools/list`\n- `tools/call`\n- `resources/list`\n- `resources/read`\n- `resources/templates/list`\n- `prompts/list`\n- `prompts/get`\n- paginated list responses\n- runtime capability scorecard\n- redacted verbose transcript with `--verbose-runtime`\n- optional runtime approval gating with a precomputed `doctor runtime-plan` digest\n\nOutput formats:\n\n- human text output\n- JSON reports\n- Markdown reports\n- Shields-compatible badge JSON and static badge Markdown\n- validation history JSONL and trend summaries\n- deterministic local attestation artifacts\n- output contract and rule catalog freeze metadata\n- bundled validation corpus reports\n- `--output` file writing\n- CI summary and artifact generation\n\n## Quick Start\n\nGlobal install from npm:\n\n```bash\nnpm install -g codex-plugin-doctor\ncodex-plugin-doctor --version\ncodex-plugin-doctor self-test\ncodex-plugin-doctor check path/to/plugin-package\n```\n\nRun `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.\n\nIf you already have Codex installed locally and do not know plugin paths, discover the installed plugin cache:\n\n```bash\ncodex-plugin-doctor list --installed\ncodex-plugin-doctor check --installed\ncodex-plugin-doctor check --installed --all-summary\ncodex-plugin-doctor check --installed --compat --all-summary\ncodex-plugin-doctor audit --installed --security --compat\ncodex-plugin-doctor audit --installed --security --compat --policy security\ncodex-plugin-doctor mcp path/to/mcp-package\ncodex-plugin-doctor check --installed github\ncodex-plugin-doctor explain plugin.manifest.missing\n```\n\nRun from source:\n\n```bash\nnpm install\nnpm run build\nnode dist/cli.js check examples/codex-doctor-runtime --runtime\n```\n\nFor local global usage:\n\n```bash\nnpm link\ncodex-plugin-doctor check examples/codex-doctor-runtime --runtime\n```\n\nGenerate validation artifacts locally:\n\n```bash\nnpm run generate-validation-artifacts -- --target examples/codex-doctor-runtime --runtime-target examples/codex-doctor-runtime --out-dir validation-artifacts-local\n```\n\n## Example Output\n\nPassing runtime package:\n\n```text\nCodex Plugin Doctor\n===================\nStatus: PASS\nTarget: \u003crepo\u003e\\examples\\codex-doctor-runtime\nSummary: 0 fail, 0 warn, 0 total\n\nRuntime Scorecard\n----------------\ninitialize: pass\ntools/list: pass\ntools/call: pass\nresources/list: pass\nresources/read: pass\nresources/templates/list: pass\nprompts/list: pass\nprompts/get: pass\n\nNo findings.\n```\n\nRisky package:\n\n```text\nCodex Plugin Doctor\n===================\nStatus: FAIL\nTarget: \u003crepo\u003e\\examples\\codex-doctor-risky\nSummary: 1 fail, 0 warn, 1 total\n\nFailures\n--------\nx plugin.security.hard_coded_secret\n  Message: The MCP server `dangerServer` contains a hard-coded secret-like env value for `OPENAI_API_KEY`.\n  Impact: Hard-coded credentials inside plugin bundles increase leakage risk and make secure rotation difficult.\n  Suggested fix: Replace the literal value for `OPENAI_API_KEY` with an environment reference or injected secret outside the package.\n```\n\n## Useful Commands\n\nRun these from a Codex plugin package root:\n\n```bash\ncodex-plugin-doctor --version\ncodex-plugin-doctor self-test\ncodex-plugin-doctor doctor\ncodex-plugin-doctor doctor contract\ncodex-plugin-doctor doctor contract --json --output output-contract.json\ncodex-plugin-doctor doctor corpus\ncodex-plugin-doctor doctor corpus --json --output validation-corpus.json\ncodex-plugin-doctor doctor npm \u003cpublished-plugin-package\u003e\ncodex-plugin-doctor doctor npm \u003cpublished-plugin-package\u003e --json --output npm-preinstall.json\ncodex-plugin-doctor doctor attest .\ncodex-plugin-doctor doctor attest . --json --output attestation.json\ncodex-plugin-doctor doctor attest . --json --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY --output attestation.json\ncodex-plugin-doctor doctor attest verify attestation.json --target . --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY\ncodex-plugin-doctor doctor attest verify attestation.json --target . --json --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY\ncodex-plugin-doctor doctor inspector .\ncodex-plugin-doctor doctor inspector . --server context7 --json --output inspector-command.json\ncodex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin\ncodex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin --json --output risk-diff.json\ncodex-plugin-doctor doctor recommend .\ncodex-plugin-doctor doctor recommend . --json --output recommendations.json\ncodex-plugin-doctor doctor trust .\ncodex-plugin-doctor doctor trust . --json --output trust-score.json\ncodex-plugin-doctor doctor perf .\ncodex-plugin-doctor doctor perf . --json --output perf.json\ncodex-plugin-doctor doctor perf . --max-total-ms 2500 --max-stage-ms validation=500\ncodex-plugin-doctor doctor runtime-plan .\ncodex-plugin-doctor doctor runtime-plan . --json --output runtime-plan.json\ncodex-plugin-doctor doctor runtime-plan . --markdown --output runtime-plan.md\ncodex-plugin-doctor doctor runtime-policy .\ncodex-plugin-doctor doctor runtime-policy . --json --output runtime-policy.json\ncodex-plugin-doctor doctor review-bundle . --output review-bundle --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY\ncodex-plugin-doctor doctor review-bundle verify review-bundle --target . --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY\ncodex-plugin-doctor doctor review-bundle diff --before old-review-bundle --after review-bundle\ncodex-plugin-doctor doctor mcp .\ncodex-plugin-doctor doctor mcp . --json --output mcp-healthcheck.json\ncodex-plugin-doctor doctor export --bundle .\ncodex-plugin-doctor doctor export --bundle . --output doctor-bundle.json\ncodex-plugin-doctor doctor snapshot\ncodex-plugin-doctor doctor snapshot --json\ncodex-plugin-doctor doctor snapshot --output doctor-snapshot.json\ncodex-plugin-doctor doctor clients\ncodex-plugin-doctor doctor --update-check\ncodex-plugin-doctor audit --installed\ncodex-plugin-doctor audit --installed --security --compat\ncodex-plugin-doctor audit --installed --security --compat --json --output local-audit.json\ncodex-plugin-doctor audit --installed --security --compat --cache\ncodex-plugin-doctor audit --installed --changed --cache\ncodex-plugin-doctor mcp .\ncodex-plugin-doctor mcp . --json\ncodex-plugin-doctor mcp . --json --output mcp-doctor.json\ncodex-plugin-doctor init my-plugin\ncodex-plugin-doctor init my-mcp --template mcp-stdio\ncodex-plugin-doctor init remote-mcp --template mcp-http\ncodex-plugin-doctor init runtime-demo --template full-runtime\ncodex-plugin-doctor security .\ncodex-plugin-doctor security . --scorecard\ncodex-plugin-doctor security . --json\ncodex-plugin-doctor security . --policy security\ncodex-plugin-doctor compat .\ncodex-plugin-doctor compat . --all --scorecard\ncodex-plugin-doctor compat . --client codex\ncodex-plugin-doctor compat . --client generic-mcp\ncodex-plugin-doctor compat . --client claude-desktop\ncodex-plugin-doctor compat . --client claude-desktop --install-preview\ncodex-plugin-doctor compat . --client claude-desktop --apply --backup\ncodex-plugin-doctor compat . --client cursor\ncodex-plugin-doctor compat . --client cursor --install-preview\ncodex-plugin-doctor compat . --client cursor --apply --backup\ncodex-plugin-doctor compat . --client cline\ncodex-plugin-doctor compat . --client cline --install-preview\ncodex-plugin-doctor compat . --scorecard\ncodex-plugin-doctor compat . --json\ncodex-plugin-doctor compat . --json --output compatibility.json\ncodex-plugin-doctor check .\ncodex-plugin-doctor check . --profile ci\ncodex-plugin-doctor check . --profile strict\ncodex-plugin-doctor check . --profile publish\ncodex-plugin-doctor check . --policy codex-publish\ncodex-plugin-doctor check . --policy mcp-strict\ncodex-plugin-doctor check . --policy security\ncodex-plugin-doctor check . --json\ncodex-plugin-doctor check . --explain\ncodex-plugin-doctor check . --json --output report.json\ncodex-plugin-doctor check . --markdown --output report.md\ncodex-plugin-doctor check . --badge-json --output doctor-badge.json\ncodex-plugin-doctor check . --badge-markdown\ncodex-plugin-doctor check . --sarif --output results.sarif\ncodex-plugin-doctor check . --ascii\ncodex-plugin-doctor check . --no-animations\ncodex-plugin-doctor check . --runtime\ncodex-plugin-doctor check . --runtime --require-runtime-approval --runtime-approval-digest sha256:\u003capproved-plan-digest\u003e\ncodex-plugin-doctor check . --config .codex-doctor.json\ncodex-plugin-doctor check . --history validation-history.jsonl\ncodex-plugin-doctor history validation-history.jsonl\ncodex-plugin-doctor history validation-history.jsonl --json\ncodex-plugin-doctor history validation-history.jsonl --fail-on-regression\ncodex-plugin-doctor fix . --dry-run\ncodex-plugin-doctor fix . --interactive --backup\ncodex-plugin-doctor fix . --apply --backup\ncodex-plugin-doctor check . --json --runtime --verbose-runtime\n```\n\n`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`.\n\n`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 \u003cpackage\u003e` 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. 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 \u003cpath\u003e` 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 \u003cattestation.json\u003e --target \u003cpath\u003e --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 \u003cpath\u003e` 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 \u003cpath\u003e` evaluates the same runtime plan and security signals, then recommends `allow`, `review`, `sandbox_recommended`, or `deny` before local MCP execution starts. `doctor review-bundle \u003cpath\u003e --output \u003cdir\u003e --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 \u003cbundle-dir\u003e --target \u003cpath\u003e --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 \u003cdir\u003e --after \u003cdir\u003e` 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 \u003cdigest\u003e` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence \u003cpath\u003e --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 \u003cevidence.json\u003e --target \u003cpath\u003e --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 \u003cpath\u003e --tag \u003ctag\u003e --output \u003cevidence.json\u003e --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 \u003cpath\u003e` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server \u003cname\u003e` when the package contains multiple MCP server entries. `doctor diff --before \u003cpath\u003e --after \u003cpath\u003e` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend \u003cpath\u003e` 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 \u003cpath\u003e` 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 \u003cpath\u003e` 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 \u003cms\u003e` or repeatable `--max-stage-ms stage=ms` to fail CI when a budget is exceeded. `doctor mcp \u003cpath\u003e` exposes the generic MCP static health report under the doctor command family without starting local MCP servers. `doctor export --bundle \u003cpath\u003e` 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.\n\n`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.\n\n`--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.\n\n`mcp \u003cpath\u003e` 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.\n\n`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.\n\n`security \u003cpath\u003e` 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. Use `--json` for automation or `--scorecard` for a compact status view.\n\n`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.\n\n`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.\n\n`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`.\n\n`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`.\n\n`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.\n\n`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.\n\n`check --explain` adds inline rule catalog context to text reports, including why a finding matters, a more detailed fix path, and a compact example.\n\n`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`.\n\n`check --history \u003cpath\u003e` appends a compact JSONL validation snapshot after a single package check. `history \u003cpath\u003e` 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.\n\n`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.\n\nOptional local policy file:\n\n```json\n{\n  \"ignoreRules\": [\"plugin.heuristic.description.too_long\"],\n  \"failOnWarnings\": true\n}\n```\n\nRun these when you want Codex Plugin Doctor to find plugins from the local Codex installation:\n\n```bash\ncodex-plugin-doctor list --installed\ncodex-plugin-doctor check --installed\ncodex-plugin-doctor check --installed --all-summary\ncodex-plugin-doctor check --installed --compat --all-summary\ncodex-plugin-doctor check --installed github\ncodex-plugin-doctor check --installed github --runtime --no-animations\ncodex-plugin-doctor explain plugin.security.hard_coded_secret\n```\n\n## GitHub Action\n\n```yaml\nname: Validate Codex plugin\n\non:\n  pull_request:\n\njobs:\n  doctor:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v5\n      - uses: Esquetta/CodexPluginDoctor@v1.15.0\n        with:\n          version: \"1.15.0\"\n          path: .\n          runtime: \"true\"\n          policy: codex-publish\n          upload-artifact: \"true\"\n          artifact-name: codex-plugin-doctor-reports\n          review-bundle: \"true\"\n          review-bundle-verify: \"true\"\n```\n\nThe action writes `codex-plugin-doctor-summary.md`, `codex-plugin-doctor-report.json`, optional `codex-plugin-doctor.sarif`, 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. Review bundle generation requires a signing key environment variable such as `CODEX_PLUGIN_DOCTOR_SIGNING_KEY`. For runtime probing, SARIF output, review bundle artifacts, installed plugin cache checks, CI policy presets, and pinned release examples, see [GitHub Action Usage](./docs/engineering/github-action-usage.md).\n\nTo self-test this repository after cloning it:\n\n```bash\ncodex-plugin-doctor check examples/codex-doctor-runtime --runtime --no-animations\n```\n\n## Repository Layout\n\n```text\ndocs/                 Product, engineering, security, and release docs\nexamples/             Manual plugin packs for local CLI testing\nsrc/                  CLI, validation logic, runtime probing, reports\ntests/                Fixture-based regression tests\nvalidation-sessions/  Real-world validation waves and tuning notes\n```\n\n## Validation Evidence\n\nThe validator is tuned against local fixtures and real marketplace-style plugin packages. See:\n\n- [Real-World Validation Workflow](./docs/engineering/real-world-validation-workflow.md)\n- [Validation Sessions](./validation-sessions/README.md)\n- [Examples](./examples/README.md)\n- [Rule Catalog](./docs/rules/catalog.md)\n\nRecent validation waves covered:\n\n- curated Codex plugin cache packages\n- marketplace-style plugin snapshots\n- YAML block-scalar skill metadata\n- media and visual workflow metadata\n\n## Release Readiness\n\nRelease preparation is reproducible from the repository:\n\n```bash\nnpm run prepare-release\nnpm run release-check\n```\n\n`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, tests, build, and pack dry-run.\n\nRelated docs:\n\n- [Changelog](./CHANGELOG.md)\n- [Contributing](./CONTRIBUTING.md)\n- [Security Policy](./SECURITY.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [NPM Release Checklist](./docs/engineering/npm-release-checklist.md)\n- [Release Candidate Workflow](./docs/engineering/release-candidate-workflow.md)\n- [v1.0 Readiness Checklist](./docs/engineering/v1.0-readiness-checklist.md)\n\n## Contributing\n\nContributions are welcome once the repository is public. Start with:\n\n- [Contributing](./CONTRIBUTING.md)\n- [Security Policy](./SECURITY.md)\n- [Validation tuning issue template](./.github/ISSUE_TEMPLATE/validation_tuning.yml)\n\n## Support\n\nIf this tool saves you time, GitHub stars and sponsorship help signal that the project is worth continuing.\n\n- Star the repository on GitHub.\n- Use GitHub Sponsors through the repository funding link.\n- Open validation tuning issues for false positives or false negatives.\n\n## Product Direction\n\nCodex Plugin Doctor starts as a Codex-specific validator and can grow into a broader MCP Doctor over time.\n\nThe immediate goal is not a marketplace, dashboard, or hosted website. The immediate goal is a trustworthy local preflight check for Codex-compatible plugin bundles.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesquetta%2Fcodexplugindoctor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesquetta%2Fcodexplugindoctor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesquetta%2Fcodexplugindoctor/lists"}