Skip to main content
All posts
Guide

Migrating from Claude Code to DeepSeek Harness: A Guide

Considering DeepSeek Harness as an open-source Claude Code alternative? See how CLAUDE.md, hooks.json, MCP servers, Skills, and subagents map over directly.

If you're moving a project from Claude Code to DeepSeek Harness (dsh), most of your setup carries over more directly than you'd expect: your CLAUDE.md loads as-is, your hooks.json can run through an official bridge plugin, and dsh can even delegate tasks straight back to Claude Code as a subagent. The pieces that don't map cleanly are Skills and the underlying extension model — dsh treats everything as one kind of plugin instead of separate skill/command/hook/MCP systems.

This is a fact-based mapping, not a tutorial for either tool in general — it assumes you already know Claude Code's public concepts (CLAUDE.md, hooks.json, MCP servers, Skills, slash commands, subagents) and just want to know what the dsh equivalent is. It's written for readers specifically weighing dsh as an open-source Claude Code alternative, not a general introduction to either tool.

Quick mapping table

Claude Code conceptdsh equivalentHow close is the fit
CLAUDE.md project instructionsNative AGENTS.md/CLAUDE.md loading, workspace rootDirect — dsh reads it automatically
hooks.json shell hooksdsh-hooks-claude-code bridge pluginDirect — official bridge translates events
MCP servers@deepseek-ai/dsh-mcp-client plugin instance per serverMostly direct — same tool naming, narrower scope
Skills (SKILL.md)dsh's own ctx.skills provider registryNot compatible out of the box
Slash commandsdsh "human commands" via ctx.commandsSame concept, different registration mechanism
Subagentsdsh subagent provider registry, including a Claude Code providerDirect — can literally call Claude Code
Approval / permission settingsdsh sandbox modes + permission presetsDifferent vocabulary, comparable structure

Your project instructions don't need to change

dsh loads project instructions the same way Claude Code does: it reads whichever of AGENTS.md or CLAUDE.md is present at the workspace root and renders it into context automatically, for every run mode (Web UI, headless, SDK). There's a fixed render budget of 65,536 bytes — if your instructions file is close to that size already, it'll behave the same way it would if you hit a comparable limit in Claude Code: content past the budget doesn't make it into context. If your CLAUDE.md is already reasonably scoped, you can point dsh at the same workspace and it'll pick it up without any conversion step.

Hooks: reuse hooks.json through an official bridge

dsh ships an official bridge package, dsh-hooks-claude-code, that translates an existing Claude Code hooks.json file into dsh's own extension-point listeners — things like agent/session-start and tools/pre-execute. If your team has already invested in hook scripts for pre-commit checks, notification triggers, or logging, you don't have to rewrite them from scratch to try dsh; you install the bridge plugin into your profile and point it at your existing hooks file. A parallel dsh-hooks-codex bridge exists if you're coming from Codex CLI instead or in addition.

dsh plugin --profile web add dsh-hooks-claude-code

We haven't independently tested every Claude Code hook event against the bridge, so treat this as "reuse your logic, then verify the specific hooks you rely on" rather than a guaranteed drop-in. See Hooks and slash commands in DeepSeek Harness for how individual events map.

MCP servers: same tool naming, narrower scope

If you've configured MCP servers for Claude Code, the mental model transfers almost directly. dsh names bridged MCP tools mcp__<serverName>__<rawName> — the same server-qualified shape Claude Code uses — so a server you're already comfortable configuring elsewhere won't surprise you here. Where it differs is configuration format and scope:

- id: mcp-github
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: github
    transport: stdio
    command: npx
    args: ['-y', '@modelcontextprotocol/server-github']
    env:
      GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN

Each MCP server becomes one plugin instance in your profile's Cordis config rather than an entry in a dedicated MCP config file. The bigger gap to know about before migrating: dsh's MCP client explicitly bridges only MCP Tools — Resources and Prompts are documented as deferred, with no consumer wired up yet. If an MCP server you rely on in Claude Code leans on Resources (surfaced as @-mentions) or Prompts (surfaced as slash commands) rather than Tools, that functionality won't carry over. Check each server's capability list before assuming a 1:1 migration. Full configuration details, including streamable-http transport and reconnection behavior, are in our MCP setup guide.

Skills: expect to redo this one

This is the piece most likely to trip people up. dsh has its own Skill system — a provider registry (ctx.skills) that merges skills from the local filesystem and built-in sources, consumed through a skill tool that injects content into context when called. It is architecturally its own thing, not the same format as Claude Code's SKILL.md directory convention. A community Discussion on the dsh repo (#88, "这个是不是还不能使用传统Skill?") asked directly whether existing Skills could be reused, and as of this writing, dsh's own documentation doesn't state direct compatibility either way — the honest answer is "unconfirmed," not "yes" or "no."

In practice, this means: don't assume your SKILL.md library ports over untouched. One community-built option worth knowing about is dsh-skillport, which discovers existing SKILL.md libraries across several agent tools' paths (including Claude Code) and loads them into dsh with a progressive-disclosure index — but that's a third-party plugin filling a gap, not an official compatibility guarantee. Browse the Skills category for the current state of skill-related plugins.

Subagents: you can keep using Claude Code itself

This is the most surprising fact for anyone treating this as a one-way migration: dsh's subagent system has an official Claude Code provider, dsh-subagent-claude-code, which drives Claude Code through its own Agent SDK. In other words, you don't have to fully leave Claude Code behind — dsh can call it as one of several possible execution backends, alongside a Codex provider, an Agent Client Protocol provider, and in-process providers.

One-shot subagent delegation supports four optional capabilities that a provider must explicitly declare support for: outputSchema (structured output), depthLimit (delegation depth cap), toolFilter, and persona. Unsupported requests fail loudly rather than silently degrading. If your team already has working multi-agent workflows built around Claude Code, migrating means reframing that workflow as a dsh orchestration layer that happens to call Claude Code, rather than throwing the workflow away. See DeepSeek Harness subagents for the full provider table, and the workflow-automation category for orchestration plugins like dsh-agent-teams.

Permissions: mapping the mental model

dsh's permission system is structured differently from Claude Code's approval settings, but the underlying goal — control how much an agent can touch without asking — is the same. dsh has three sandbox modes: read-only, workspace-write (the default for new sessions — writes are confined to the workspace root and platform temp directories), and danger-full-access (no isolation). These get bundled with an approval policy into a "permission preset" — the default table ships two presets, workspace-write (paired with an ask approval policy) and danger-full-access (paired with never, meaning nothing is asked). You can define custom presets in configuration if the defaults don't fit your team's workflow. See Permissions and sandboxing in DeepSeek Harness for the full backend details (Linux bwrap/Landlock, macOS Seatbelt, Windows ACL, and E2B cloud sandboxing).

Habits worth adjusting

A few differences aren't about specific config files, but about how the two tools are organized:

  • One extension mechanism, not four. Claude Code separates skills, commands, hooks, and MCP into distinct systems with their own file formats. In dsh, all of that — plus tools and model adapters — is the same underlying thing: a plugin registered against a Cordis Context. Once you're used to dsh, "how do I add X" usually has one answer (write or install a plugin) instead of four different answers depending on what X is.
  • Plugins are installed per-profile, not globally. dsh organizes configuration into named profiles (web, headless, or custom names), each with its own installed plugin set. Decide early whether you want one profile per project or one shared profile, the same way you'd think about per-project vs. global tool configuration elsewhere.
  • Session history doesn't have to start from zero. If you want to bring existing Claude Code conversation history along rather than starting fresh, the community plugin dsh-chat-import imports chat histories from several coding agents, including Claude Code, as resumable dsh sessions — and can export back to Claude Code format too. That's a third-party tool, not an official migration path, so verify the import on a low-stakes session first.

FAQ

Do I need to rewrite my CLAUDE.md file to use dsh?

No. dsh reads AGENTS.md or CLAUDE.md directly from the workspace root and renders it into context automatically, subject to a 65,536-byte render budget.

Will my Claude Code hooks just work in dsh?

Install the official dsh-hooks-claude-code bridge plugin and point it at your existing hooks.json — it translates the events into dsh's extension points. We haven't verified every hook type works identically, so test your specific hooks after migrating rather than assuming a perfect match.

Can I keep using Claude Code after switching to dsh?

Yes — dsh's dsh-subagent-claude-code provider lets it delegate tasks to Claude Code through Claude Code's own Agent SDK. You can use dsh as an orchestration layer that calls Claude Code for some tasks rather than replacing it outright.

Do my Claude Code Skills work in dsh without changes?

Not confirmed either way in dsh's own documentation — treat this as unresolved rather than assuming compatibility. The community plugin dsh-skillport is one option for bridging existing SKILL.md libraries, but it's a third-party workaround, not an official guarantee.

Are my MCP servers compatible with dsh?

If the server exposes Tools, yes — the naming convention (mcp__<serverName>__<rawName>) matches what Claude Code uses. If it relies on MCP Resources or Prompts, those aren't bridged in dsh yet, so check your server's feature list before migrating.

Next steps