dsh-compat

Inspect Claude Code and Codex plugins, explain compatibility component by component, and generate auditable DeepSeek Harness bundles.

中文文档 · Real-plugin reports

Developer preview. dsh-compat is intentionally conservative: it reports unsupported behavior instead of pretending that host-specific hooks, agents, or permissions are portable.

What it does

• detects .claude-plugin/plugin.json and .codex-plugin/plugin.json;
• inventories Skills, Commands, Agents, Hooks, MCP, LSP, Settings, and Resources;
• assigns every component one state: DIRECT, ADAPTED, UNSUPPORTED, or BLOCKED;
• rejects source-root escapes, unsafe symlinks, inline credentials, and lifecycle-script declarations;
• converts supported static content into a deterministic DSH bundle;
• emits a compatibility report, source map, ownership lock, and SHA-256 digests;
• never executes source plugin code during inspection or conversion.

Current support

Component	Inspect	Convert	Current behavior
Agent Skills	Yes	Yes	Registered through ctx.skills; static SKILL.md retained for audit
Markdown Commands	Yes	Adapted	Converted into user-invocable DSH skills
MCP stdio	Yes	Adapted	Emits @deepseek-ai/dsh-mcp-client row; env values are omitted
MCP HTTP	Yes	Adapted	Normalized to streamable-http; headers are omitted
Resources	Yes	Yes	Copied as inert, auditable bundle resources
Hooks	Yes	No	Reported unsupported until event and blocking semantics are verified
Agents/Subagents	Yes	No	Reported unsupported until model/tool/permission behavior is verified
LSP	Yes	No	Inventory only
Settings/Permissions	Yes	No	Fail closed; never widens permissions

The static target adapter is pinned to DSH 0.1.0-rc.6. DSH remains a developer preview, so every compatibility claim must be revalidated against a fixed package version or commit.

Install from source

Requirements: Node.js 22+ and pnpm 11+.

git clone https://github.com/Simidas/dsh-compat.git
cd dsh-compat
pnpm install
pnpm build
node dist/cli.js help

The repository is not published to npm yet.

30-second demo

The demo shows the intended flow: inspect an untrusted plugin, review the component-level decisions, and build a DSH bundle only after the report is understood.

Real-plugin evidence

The first five reports use a fixed public commit from Anthropic's official Claude plugin repository. They preserve source provenance and digests without vendoring upstream code. The intentionally conservative results include both successful command/skill adaptations and unsupported hook/agent semantics.

See reports/real/README.md for the reproducible matrix and individual reports.

Usage

Inspect a local plugin without executing it:

node dist/cli.js inspect ./path/to/plugin
node dist/cli.js inspect ./path/to/plugin --format json
node dist/cli.js inspect ./path/to/plugin --strict

Generate a DSH bundle:

node dist/cli.js convert ./path/to/plugin --out ./generated-plugin
node dist/cli.js test ./generated-plugin

test currently performs deterministic static validation. It does not start source MCP/LSP servers or run source hooks.

Review the generated files before installing:

generated-plugin/
├── package.json
├── cordis.patch.yml
├── index.js
├── skills/
├── resources/
├── dsh-compat.env.example.json
├── dsh-compat.report.json
├── dsh-compat.report.md
├── dsh-compat.source-map.json
└── dsh-compat.lock.json

Then, at your discretion:

dsh plugin --profile <profile> add -w ./generated-plugin
dsh --profile <profile> --dump-config

MCP environment variables and HTTP headers are never copied with their values. Bind the names listed in dsh-compat.env.example.json through your reviewed DSH profile or generated patch before starting the MCP server.

Exit codes

Code	Meaning
0	Command completed under the selected policy
1	Usage or internal error
2	Compatibility/static policy failure
3	Security blocker
4	Reserved for unresolved source/target revisions

Security model

Source plugins are untrusted input. dsh-compat does not run package-manager lifecycle scripts, hooks, binaries, MCP servers, or LSP servers. Unknown executable behavior and permission widening fail closed. See SECURITY.md.

Generated bundles contain code and configuration and must be reviewed before installation. dsh-compat does not attest that an upstream plugin or MCP server is safe to run.

Development

pnpm test:all

Compatibility contributions require a stable rule ID, fixture, security test where applicable, and official DSH documentation/source or a behavior trace. See CONTRIBUTING.md.

The implementation contracts and roadmap are in docs/. project-control.md is the project status source of truth.

License

Apache-2.0. Third-party source plugins and generated artifacts remain subject to their applicable licenses; see NOTICE.