Claude2DSH
Move Claude Code conversations, skills, agents, commands, memory, and MCP servers into DeepSeek Harness as native, resumable sessions — and take DSH turns back to Claude Code JSONL when you need to.
简体中文
Abstract bridge carrying conversation nodes and software assets from an amber source environment into a cyan destination environment
Claude Code is the first source adapter in a multi-tool migration layer. Claude2DSH preserves the useful conversation structure, writes through DSH's native persistence APIs, and keeps the original Claude directory read-only by default.
[!IMPORTANT]
0.3.0 requires DSH >=0.1.5-rc.1 <0.2.0 and no longer starts on 0.1.0-rc.x. DSH 0.1.5 replaced the service-level session API with per-session handles and moved the Session log to format v3; 0.2.x releases predate that change. Upgrade the harness (npm install -g @deepseek-ai/dsh@latest) or stay on claude2dsh@0.2.0-rc.5.
Claude Code assets on the left mapping to DeepSeek Harness surfaces on the right, with the three import types added in 0.3.0 marked
Compatibility table showing DSH 0.1.5-rc.1 and 0.1.6-alpha.1 verified, the rest of 0.1.5 in range, and 0.1.0-rc.x unsupported
Why Claude2DSH
| Resume natively | Bring more than chat | Return without risking the source |
|---|
| Claude turns become DSH-native session events that DSH can inspect, replay, and resume. | Skills, user-global instructions, project memory, tool-output sidecars, subagent transcripts, and plugin assets have explicit migration paths. | Export and sync target a safe copy under $DSH_HOME by default. Concurrent edits pause instead of overwriting either side. |
The governing principle is zero-configuration by default: the default path produces a visible result without requiring users to understand profiles or bundles first, while dangerous write-back remains explicitly gated.
flowchart LR
A["Claude Code JSONL<br/>~/.claude/projects<br/>read-only"] --> B["Claude adapter<br/>discover · parse · normalize"]
B --> C["Normalized session IR<br/>turns · steps · tools · images"]
C --> D["DSH event synthesis<br/>native session events"]
D --> E[("DSH sessions<br/>$DSH_HOME/sessions")]
E --> F["Export / sync<br/>safe copy"]
F --> G["Claude Code JSONL<br/>resumable transcript"]
E --> H["Settings UI + tools<br/>import · export · sync · merge"]
Quickstart
Requirements: Node.js >=22.19.0, pnpm, and the dsh CLI.
# Install the published plugin into DSH's built-in headed profile
dsh plugin --profile web add @claude2dsh/plugin@0.3.0
# Start the browser UI; the terminal prints the local URL
dsh web
Then:
- Open the URL printed by
dsh web.
- On a fresh DSH installation, choose Configure later if the model API-key prompt appears; migration itself does not call a model.
- Open Settings → Claude2DSH.
- Choose a language, confirm the Claude sessions directory, and optionally include subagent/workflow transcripts.
- Click Preview import, inspect the counts and item report, then click Run import.
flowchart LR
S1["Install plugin<br/>dsh plugin --profile web add ..."] --> S2["Start UI<br/>dsh web"]
S2 --> S3["Open Settings → Claude2DSH"]
S3 --> S4["Preview import"]
S4 --> S5["Run import"]
S5 --> R["Native DSH sessions<br/>listed in Session sources"]
The first section of Settings → Claude2DSH is the migration guide; Chinese is the default UI language and English is selectable. If port 3080 is already in use, run dsh web --port 0 and open the URL printed by DSH.
Real Claude2DSH first-run migration guide in English, showing language, source directory, subagent option, Preview import, Run import, and Auto mirror defaults
Preview is read-only and returns an itemized plan before any DSH write.
Real Claude2DSH Preview import report in the default Chinese UI, showing one privacy-safe synthetic session ready to import
This is what a successful run looks like. The screenshot comes from a real Claude2DSH UI using a synthetic, privacy-safe Claude transcript.
Real Claude2DSH import result in the default Chinese UI, showing one newly imported synthetic session and zero failures
Repository helper
If you cloned this repository, the helper performs the same install into the main web profile and starts the UI on DSH's default local port (3080):
bash scripts/install-claude2dsh.sh
Set CLAUDE2DSH_PROFILE only when you intentionally want a custom profile. Headless profiles expose the same tools but do not include the browser UI.
Capabilities: when and how to use them
| Capability | Use it when | Entry and visible result |
|---|
| Session import | First migration, or after the Claude transcript gains turns | Settings → Claude2DSH → First-run migration, or claude2dsh_import; reports previewed/imported/already/appended/skipped/failed |
| Skill import | Claude skills should become DSH-native discoverable assets | claude2dsh_import_skills; copied skills appear under $DSH_HOME/skills and in DSH skill discovery |
| Global context | Move user-global ~/.claude/CLAUDE.md into DSH global instructions | claude2dsh_import_context; previews first and never overwrites a different $DSH_HOME/AGENTS.md |
| Project memory | Make one project's MEMORY.md and memory/*.md discoverable in DSH | claude2dsh_import_memory; creates one DSH skill bundle per project |
| Export to Claude | Continue a DSH session in Claude Code | claude2dsh_export; writes a validated JSONL copy under $DSH_HOME/claude2dsh/exports |
| Sync back | Append new DSH turns to an existing exported Claude copy | claude2dsh_sync; reports appended turns, events, and JSONL records |
| Auto mirror | Keep watching for new Claude turns and mirror DSH turns to the safe copy | Settings → Auto mirror; claude2dsh_autosync shows status and resumes a paused queue |
| Conflict merge | Both sides grew after the watermark and neither version may be lost | claude2dsh_merge; computes or creates a new merged copy rather than changing either original |
| Tool-output sidecars | A transcript references large persisted tool results | claude2dsh_sidecars; lists or resolves copied files and records missing/oversize items |
| Session sources | Distinguish Claude main, subagent, and merged sessions | Settings → Session sources, or claude2dsh_session_sources; shows source kind and path |
| Agent import | Claude subagent definitions should keep their instructions in DSH | claude2dsh_import_agents; each becomes the skill with its origin, model, and tool list in frontmatter metadata |
A translation is not an equivalence, and the report says so: a Claude subagent becomes a DSH skill rather than a preset, and a Claude slash command becomes a user-invocable skill. The original frontmatter values are preserved in skill metadata so the difference is inspectable.
Session import is idempotent: running it again reports an existing session instead of duplicating it. The default search is recursive and respects CLAUDE_CONFIG_DIR (falling back to ~/.claude/projects), and the first-run guide displays the discovered source root and result counts. Project-level CLAUDE.md is not copied because DSH already reads it natively; only user-global context needs conversion.
Settings tour
The Claude2DSH settings page keeps the first migration and safety-critical defaults in one place:
- First-run migration — language, source directory, optional subagents, preview, run, and itemized result.
- Auto mirror — opt-in watcher, debounce, and DSH-to-safe-copy direction.
- Import defaults — image mode/provider/model, subagent default, and sidecar size cap.
- Export / write-back — safe-copy target by default; original
~/.claude write-back is a separate dangerous switch.
- Claude hook bridge — startup-only paths and activation guidance.
- Session sources — imported session ID, source kind, and source path.
The following real screenshots use the default Chinese UI and synthetic data; labels switch with the language selector.
Claude2DSH Settings sections for Auto mirror, Import defaults, and Export or write-back, with safe defaults visible
Claude2DSH Settings sections for the startup hook bridge and session sources, showing one privacy-safe synthetic Claude main session
Safety model
- Import treats the Claude source as read-only. Preview performs no DSH write.
- DSH writes go through host persistence and the DSH-native roots under
$DSH_HOME/sessions, $DSH_HOME/skills, and $DSH_HOME/claude2dsh.
- Export and sync default to
$DSH_HOME/claude2dsh/exports; they do not write the original ~/.claude.
- Writing the original Claude directory requires explicit
allowOriginalClaudeDir: true authorization and remains refused by default.
- Plugin inventory reads assets without executing plugin code.
- Auto mirror pauses on concurrent growth. The explicit merge tool creates a new safe copy instead of guessing which side wins.
Current limitations
- Harness range:
0.3.0 supports DSH >=0.1.5-rc.1 <0.2.0 and refuses to load outside it. Interfaces and on-disk formats are still not presented as a stable compatibility promise; a future Session format change will need a matching plugin release.
- Hook bridge: the upstream bridge supports 7 of Claude Code's 30 hook events, only
type: "command" handlers, and partial semantics per supported event. Full hook compatibility is a roadmap goal, not a current claim.
- Vision acceptance: the native image path is implemented, but it has not been accepted against a real vision-capable DSH model route. The shipped DeepSeek adapter declares text-only input.
- Auto mirror: it is opt-in and off by default. It writes DSH turns only to the safe Claude export copy; when both sides grow, it pauses and reports a conflict. Automatic merge is not implied.
- Plugin compatibility: inventory and selected assets can migrate, but arbitrary Claude plugin runtime behavior is not automatically portable to DSH.
- Source adapters: Claude Code is currently the only adapter. Codex and other tools remain roadmap work.
- Session-list decoration: DSH has no per-session sidebar-row extension point, so source identity is shown in Settings and through
claude2dsh_session_sources instead.
FAQ
I installed the plugin but cannot see a UI.
You probably used a headless profile. Install into the built-in web profile and start dsh web; the page is under Settings → Claude2DSH.
Will it write my real ~/.claude?
Not during migration. Export and sync also target a safe copy under $DSH_HOME by default. Original-directory write-back requires a separate explicit authorization.
Why are Auto mirror and the hook bridge off by default?
Both can execute work after the first import. They stay opt-in so the user sees and accepts their scope first; the hook bridge is also limited to the documented 7/30 command-only subset.
Sibling project
Claude2DSH is part of a small family of DSH plugins by the same author for people who work across several agent tools:
- CiteCiter — citation and evidence management for DSH sessions. Where Claude2DSH moves a whole conversation between harnesses, CiteCiter keeps the sources behind an answer traceable and quotable. Both plugins follow the same rules: public DSH extension points only, nothing written into a foreign tool's directory without explicit authorization, and a real-profile acceptance run before every release.
If you migrated a Claude Code corpus into DSH, CiteCiter is the natural next install for the sessions that end up citing documents.
License and acknowledgements
MIT. The project was designed independently and benefited from the published work of dsh-chat-import (MIT) and dsh-claude-move (Apache-2.0); thanks to both projects for useful reference points. Hook compatibility delegates to the official DeepSeek Harness Claude Code hook bridge package.
