Agent setup compatibility
August 27, 2026 · View on GitHub
This matrix records what dsh-movein moves, what DSH already reads, and what remains manual. The original DSH source audit used 0.1.0-rc.6; package wiring and safe boot checks were rechecked on 0.1.1-rc.2. Hook enforcement limitations below track the still-open upstream reports rather than assuming configuration loading implies enforcement.
一份实测的 Claude Code 与 DeepSeek Harness 资产兼容性对照表，基于 DSH 0.1.0-rc.6 源码逐项验证。中文摘要在文末。
Claude Code to OpenCode
This route was loaded end to end with OpenCode 1.18.23 using debug config, debug skill, and debug agent.
| Claude Code asset | OpenCode result | What happens |
|---|---|---|
Global ~/.claude/CLAUDE.md | Linked instruction file | Links to ~/.config/opencode/AGENTS.md only when that target is free |
Project CLAUDE.md | Linked instruction file | Links to the project AGENTS.md only when that target is free |
Project auto memory MEMORY.md | Referenced from project config | Keeps the file in place, respects autoMemoryEnabled and autoMemoryDirectory, and sees later updates |
Unconditional .claude/rules/*.md | Referenced from config | Added to the matching OpenCode instructions array without copying the file |
Path-scoped .claude/rules/*.md | Manual | Reported without conversion because OpenCode has no equivalent conditional path scope |
| Skills | Native | Current OpenCode reads global and project .claude/skills directly, so no duplicate is created |
| Slash commands | Copied | Markdown and $ARGUMENTS stay unchanged in the matching OpenCode command directory |
| Subagents | Converted | Description and prompt body become an OpenCode subagent. Claude tool permissions remain manual |
| Local MCP | Mechanical conversion | Command and args become one command array. ${VAR} becomes {env:VAR} |
| Remote MCP | Mechanical conversion | URL and headers move into the target scope |
PreToolUse command hooks | Live plugin bridge | A generated global OpenCode plugin reads the original Claude settings at runtime. Matchers, exit code 2 blocking, structured deny results, and updatedInput are preserved |
PostToolUse command hooks | Live plugin bridge | The same plugin runs checks after a successful tool call and adds blocking stderr or structured feedback to the OpenCode tool result |
| Other hook events and types | Manual | Stop timing, prompt, agent, HTTP, async, and conditional if semantics are not guessed |
| Existing target | Skipped | No command, agent, instruction file, or MCP definition is overwritten |
| Plaintext secret | Skipped | A secret-looking MCP value is reported and not copied |
| JSONC | Preserved | Comments, trailing commas, and unrelated settings remain intact |
| Invalid target config | Apply blocked | A parse error blocks every write |
| Permissions | Manual | The semantics differ, so dsh-movein does not guess |
| Sessions | Out of scope | Session files are not read or written |
Origin overview
| Origin | Instructions | Skills and commands | MCP | Other behavior |
|---|---|---|---|---|
| Claude Code | Project native, global linked | Skills linked, commands and subagents converted | stdio and HTTP | Configures the mapped hook subset and deny or ask rules; hook enforcement still needs a canary |
| Codex | Global AGENTS.md linked | Prompts converted | stdio | Approval and sandbox policy remain with DSH |
| OpenCode | Project AGENTS.md native, one global file linked | Skills linked, commands and agents converted | local and remote | Permissions and plugins remain manual |
OpenCode compatibility
OpenCode paths and precedence follow the official V2 configuration documentation and V1 migration guide. JSONC parsing uses comments and trailing commas exactly as OpenCode permits.
| OpenCode asset | DSH compatibility | What happens |
|---|---|---|
| Global config | Read and merged | ~/.config/opencode/opencode.json and opencode.jsonc load first |
| Custom config | Read and merged | OPENCODE_CONFIG loads after global config |
| Project config | Read and merged | Direct configs load from the nearest Git root toward the current directory after custom config |
.opencode config | Read and merged | These configs load from the Git root toward the current directory after every direct project config |
| Custom directory | Read and merged | OPENCODE_CONFIG_DIR contributes config and file-based assets before project definitions |
Project AGENTS.md | Native, zero work | DSH already reads the same file |
| One global instruction file | One symlink | Linked to $DSH_HOME/AGENTS.md only when the destination is free |
| Multiple, globbed, or remote instructions | Manual | Reported without concatenation or network fetching |
| Skill directories | Format compatible | Both skill and skills aliases are found and linked into DSH roots |
| Agent files and inline agents | Converted | V1 prompt, V2 system, and the description become a DSH skill |
| Command files and inline commands | Converted | Template and description become a user-invocable DSH skill |
| Local MCP | Mechanical conversion | V1 direct maps and V2 mcp.servers maps become stdio command and args while string environment values remain intact |
| Remote MCP | Mechanical conversion | V1 direct maps and V2 mcp.servers maps become streamable HTTP rows |
| Disabled or malformed MCP | Skipped visibly | No row is written and the dry run names the skipped server |
{env:VAR} | Runtime reference | Converted to process.env.VAR without reading the current value |
{file:path} | Preserved for review | The placeholder remains visible and no file is read |
| Permissions and plugins | Manual | Reported as unsupported because DSH semantics differ |
| Sessions | Out of scope | No OpenCode session files are read or written |
| Invalid JSONC | Apply blocked | A parse error makes the complete apply operation write nothing |
Claude Code compatibility
| Claude Code asset | DSH compatibility | What actually happens |
|---|---|---|
Project CLAUDE.md | Native, zero work | instructionFileCandidates defaults to ['AGENTS.md', 'CLAUDE.md'], local variants too. DSH discovers it from project root down to cwd and renders it the same system-reminder way Claude Code does |
Global ~/.claude/CLAUDE.md | One symlink | The global slot is $DSH_HOME/AGENTS.md only, no CLAUDE.md fallback there. Link it and you are done |
Skills (SKILL.md) | Format compatible as is | Frontmatter parses as an open object, only name and description are required, unknown keys (allowed-tools, license, ...) are ignored. But .claude/skills is NOT one of the roots, so skills have to land in one (see the table below) |
| Slash-invoking skills | Same UX | Users type /name, the model loads via a skill tool, same shape both sides |
MCP servers (.mcp.json) | Lossless mechanical conversion | One dsh-mcp-client config row per server (stdio and streamable-http). Tool names are literally identical, mcp__server__tool on both sides, so nothing referencing them breaks |
Hooks (settings.json hooks) | First party bridge, partial and not enforcement-equivalent | @deepseek-ai/dsh-hooks-claude-code reads the configured file, substitutes ${CLAUDE_PROJECT_DIR}, and maps only 7 of 30 events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart, and SubagentStop. Other events are silently skipped during parsing; only command handlers run. Matchers test DSH's lowercase tool names, so a Claude matcher such as Bash can select nothing (#582). On Windows, PowerShell may not propagate a native interpreter's exit 2, making an intended deny fail open (#2485, #3714). On every platform, {"continue":false} is recorded but does not halt the run (#1514). Loading and composing this row therefore does not prove enforcement |
| Permission rules | Not native, bridgeable | DSH has three coarse presets and no per tool allowlist. deny/ask rules can be enforced at the tools/pre-execute gate (dsh-movein-permissions), allow rules have no equivalent, the DSH preset governs the default |
Subagents (.claude/agents/*.md) | No direct import | DSH agent presets are directories with agent.cordis.yml, not markdown. The practical path is converting agent definitions to skills (frontmatter is nearly identical). Fun fact, DSH ships a subagent-claude-code provider that literally spawns claude as a child agent |
Slash commands (.claude/commands/*.md) | No file equivalent | DSH commands are code-registered. User-invocable skills are the file-based substitute |
| Sessions | Hardest, avoid writing | ~/.dsh/sessions uses zstd-framed JSONL at SESSION_FORMAT_VERSION = 0 with an explicit no-compatibility promise and strict event invariants. Import history as plugin-sourced recall messages, never by writing session files. For conversation history use dsh-chat-import |
Memory / ~/.claude misc | Manual | No DSH counterpart, carry what matters into AGENTS.md or skills |
Verify hook enforcement after moving
dsh-movein doctor is intentionally non-invasive. It reads the three Claude settings layers, checks that every layer with supported command hooks has its own DSH bridge row and that the required packages exist, and reports definitely dead events, handler types, and matcher shapes. It does not execute a hook or mutate a settings file. doctor --live also keeps the migrated configuration boot-free: it composes that configuration, discards the bounded output, then boots only an official base/web snapshot. A green live doctor proves composition and host boot, not hook policy enforcement.
Before relying on a moved hook to block tools:
- Use a disposable project and a new DSH session. Add a temporary
PreToolUsecommand hook with a lowercase DSH tool matcher (bashon POSIX,pwshon Windows). - Make the hook exit 2 and ask the agent to run a harmless command such as printing a fixed word. Confirm the tool is denied, not merely that a hook result appears in a log.
- On Windows, test the same interpreter shape your real hook uses. For a native command, append
; exit $LASTEXITCODEwhere PowerShell syntax permits it, then repeat the canary. A directnode,py, or other native child without explicit propagation can be observed as a non-blocking exit instead. - Remove the temporary hook. Do not use
{"continue":false}as a stop control until upstream #1514 is fixed and a runtime canary passes on the DSH version you run.
The canary is manual because automatically invoking an existing hook could execute arbitrary user commands. Migration success, --dump-config, and a bridge package being resolvable are necessary wiring checks but are not substitutes for this denial test.
Where DSH actually looks for skills
.claude/skills is not scanned, but there are six roots, not two. Read in rank order from packages/skill/skill-filesystem/src/index.ts, the first match wins on a name collision.
| Rank | Source | Root |
|---|---|---|
| 100 | project-dsh | <projectRoot>/.dsh/skills |
| 200 | project-agents | <projectRoot>/.agents/skills |
| 300 | custom | whatever customSkillDirs lists |
| 400 | user-dsh | $DSH_HOME/skills, default ~/.dsh/skills |
| 500 | user-agents | $DSH_AGENTS_HOME/skills, default ~/.agents/skills |
| 600 | bundled | bundledSkillDir when a deployment configures one |
Three details that bite. The project root is the nearest ancestor containing .git, falling back to the cwd, so running from a subdirectory of a monorepo can silently pick a different root than you expect. The user DSH root skips its .system child. Nested discovery is not supported, a SKILL.md must sit one level under a root, not at **/SKILL.md.
dsh-movein writes into rank 100 and rank 400 (the .dsh pair) because those are DSH's own namespace, and doctor checks every root above for the silent-drop frontmatter shape, including the .agents ones you may have filled by hand.
Current verification note (2026-08-27). Migration regression coverage and the isolated live doctor target DSH
0.1.1-rc.2; the Claude-to-OpenCode path is checked against OpenCode1.18.23. These checks validate loading, conversion, composition, and safe boot. They do not claim that the DSH hook bridge has fixed the open enforcement gaps above.
Five traps measured the hard way
- A patch row whose package the profile cannot resolve makes
dsh webboot fatally (plugin tree failed to load), not a warning. Install first, write config rows only after the package resolves. - Satellite npm dist-tags lag the core. The hooks bridge's
latestwas0.0.1-rc.5while dsh itself was0.1.0-rc.6. Pin installs to the host dsh version. @deepseek-ai/dsh-hook-protocolis a peer the host install does not ship. Installing the hooks bridge alone still fails at boot, install the protocol package alongside.dsh plugin addnever installs a release younger than 24 hours. dsh forwards installs to pnpm, and pnpm 11 ships a default supply-chain cooldown (minimumReleaseAge= 1440 minutes). A freshdsh plugin add <pkg>silently picks the newest version older than a day and prints(x.y.z is available)for the one it skipped. Measured here: with 0.5.0 published 2h ago and 0.4.0 published 20h ago, a clean profile got 0.3.2 (30h old), reproduced independently on two machines.npx <pkg>goes through npm and getslatestimmediately. If you ship a plugin, publish at least a day before you announce.- A loaded hook bridge is not proof of enforcement. Unsupported events can be skipped, matchers can select no DSH tool, Windows can lose a native exit 2, and
{"continue":false}is not consumed. Run the disposable deny canary above on the exact host and DSH version that will enforce policy.
npx dsh-movein automates every row of this table that can be automated, with a dry run first and a migration diff report for the rules that cannot map.
中文摘要
- 项目 CLAUDE.md 原生兼容，DSH 默认就读，一行都不用动
- 全局 CLAUDE.md 链接为
~/.dsh/AGENTS.md即可 - SKILL.md 格式原样兼容，但
.claude/skills不是 DSH 的默认技能根，需要落到~/.dsh/skills .mcp.json可无损机械转换，工具名mcp__server__tool两边完全一致- hooks 有官方桥（30 个事件映射 7 个），但加载成功不等于强制成功：Windows 原生子进程 exit 2 可能丢失，
continue:false当前不会停止运行，必须用无害 canary 实测 - 子代理无法直接导入，转成技能最现实；会话文件格式 v0 无兼容承诺，绝对不要手写
- 五个坑还包括：解析不到的包会让 dsh 启动直接失败、周边包 npm 标签落后于核心、hook-protocol 是宿主不带的 peer 依赖、新版本有 24 小时安装冷却、hook 配置接好仍不能证明强制生效