DSH-Code

English | 中文

---

1. Project overview

DSH-Code is a terminal coding interface for DeepSeek Harness (dsh). It is composed as an out-of-tree bundle on top of the official @deepseek-ai/dsh-base and uses the same Agent, Session, tool, command, skill, permission, sandbox, context-compaction, and plugin services as the Harness Web UI.

DeepSeek Harness registers models, tools, storage, policies, and interfaces as plugins through Cordis. Durable session events record the information required to restore conversations and runtime state. DSH-Code preserves that architecture while adding a terminal workflow suited to coding tasks. The interface follows terminal conventions familiar to developers, while runtime behavior remains governed by DSH services and configuration.

2. Quick start

Requires Node ^22.19 || >=24 and the preview dsh CLI (current release line: @deepseek-ai/dsh@0.1.1-rc.2). You can still enter the TUI, browse sessions, and use non-model features without configuring a model; press a in /model to manage API keys, OAuth, and device-code sign-in.

1. Install and update

Use the same commands for the initial installation and subsequent updates:

npm install -g @deepseek-ai/dsh@0.1.1-rc.2 dsh-code@1.0.1
npm install -g pnpm
dsh plugin --profile cli add dsh-code@1.0.1

> Note: pnpm ignores packages published less than 24 hours ago, so use the exact version dsh-code@1.0.1 on release day; the version may be omitted after 24 hours. npm installation is not affected. > > Version alignment: dsh-code 1.0.1 targets dsh 0.1.1-rc.2, with every Harness dependency pinned exactly to 0.1.1-rc.2. Keep the global dsh CLI and dsh-code aligned instead of mixing release candidates. rc.2 removes the old DeepSeek setting maxRequestImageBytes.

2. Launch commands

Available launch commands:

dsh --profile cli
deepseek
dsh-code

dsh --profile cli, deepseek, and dsh-code are equivalent launch commands. deepseek and dsh-code are global aliases for dsh --profile cli, and all additional arguments are forwarded unchanged, for example deepseek --resume abc123.

> DeepSeek Harness is still a developer preview and may introduce compatibility-breaking changes. DSH-Code will continue to track the evolution of its plugin interfaces.

For installation, native-module, and plugin-loading issues, see [Troubleshooting](docs/problems.md).

3. Core features and usage

DSH-Code brings DSH Agents, models, tools, and durable sessions directly into the terminal, covering the complete workflow from writing code to reviewing changes.

1. Session management

Create sessions with /new, or restore existing sessions with /resume and --continue
Create a new work branch from a historical point with /fork while preserving the original session
Search history by current directory, update time, and session scope
Recall input history with Up/Down, or search previous prompts with /history
Use persistent titles, Markdown export, context occupancy, token, cache, TTFT, and elapsed-time metrics
Restore the session's Agent Preset and model selection when resuming it

2. Agents, models, and extensions

Select an independent Agent Preset for each session to compose tools, prompt sections, skills, context compaction, plan mode, and subagent capabilities
Use /mode to select standard, code, minimal, cordis, or a user-defined Preset
Use /model to switch models and manage providers, API keys, OAuth/device-code sign-in, endpoints, available models, and context windows
In the /model provider list, Enter manages a manual API key, l starts sign-in, and o logs out after confirmation
Automatically load commands and skills available in DSH; use /help to find them and /plugin to inspect extension status
Use plans, goals, todos, permissions, sandboxes, subagents, and additional instructions while a task is running

3. Model-switch animations

The composer plays Wave, Aurora, or Pulse when the model or reasoning effort changes under the following conditions:

Scenario	Trigger	Animation text	Effect tier
Official DeepSeek model	Switch to the model, or change its reasoning effort	`deepseek`	Flash uses the single-band tier; other DeepSeek models use the multi-band tier
Other models	After changing the model or reasoning effort, the effective effort is strictly above `high`	`Into the Unknown`	Uses the same multi-band tier as non-Flash DeepSeek models

Levels above high include xhigh, x-high, very-high, max, maximum, and ultra. For non-DeepSeek models, high, medium, low, and off do not trigger an animation.

Style	Flash	Other DeepSeek / `Into the Unknown`
Wave	One blue crest sweeps from left to right, about 1.2 seconds	Two offset blue crests sweep across in sequence with trailing `· ✦ ✧` sparkles, about 1.5 seconds
Aurora	Two blue light bands drift across one another, about 1.5 seconds	Three differently hued light bands drift across one another, about 1.8 seconds
Pulse	One ring expands outward from the center of the composer, about 1.1 seconds	Two rings expand outward in sequence, about 1.45 seconds

4. Coding workflow

Use @ to reference workspace files or existing sessions; selecting PNG, JPEG, WebP, or GIF files attaches the real image automatically
Attach images through the initial prompt, repeated --image arguments, or by dragging one or more images into the terminal
Inspect changes by file with /diff, and start a read-only code review with /review
Copy the latest complete response with /copy, and inspect full history and tool details with Ctrl+O
Handle tool approvals, structured questions, plan reviews, multiple selections, and custom answers
Control what the Agent may do with permission Presets and sandboxes; add instructions or interrupt while a task is running

5. Commands and key bindings

Start the TUI:

dsh --profile cli                    # create a standard session
dsh --profile cli --mode code        # start with the specified Agent Preset
dsh --profile cli --continue         # resume the latest session for the current directory
dsh --profile cli --resume abc123    # resume by id or unique prefix
dsh --profile cli --session my-id    # create a session with an explicit id

The following built-in commands are available inside the TUI. Additional Harness commands and user skills depend on the active profile and installed packages; use /help for the complete current list.

#### Sessions and history

| Command | Purpose | | --- | --- | | /new [preset] | Create a session, optionally selecting an Agent Preset | | /resume [id\|prefix] | Search for or restore an existing session | | /resume cancel | Cancel a pending session switch | | /fork [event-seq] | Create a session branch from the latest completed turn or a specified event position | | /delete [id\|prefix] | Delete a session and its subagent sessions | | /title <text> | Change the current session title | | /export [path] | Export the current session as Markdown | | /history | Search and reuse previously submitted prompts | | /clear | Clear the current terminal display without deleting the durable session |

#### Agents, models, and permissions

Command	Purpose
`/mode [preset]`	Inspect or select the current session's Agent Preset
`/model`	Switch models and manage providers, API keys, browser sign-in, endpoints, and available models
`/effort`	Adjust the current model's reasoning effort
`/permission [preset]`	Inspect or switch the permission Preset
`/subagent`	Select the model used when a subagent performs a task

#### Coding, tasks, and background work

| Command | Purpose | | --- | --- | | /diff [--staged\|ref] | Inspect the working-tree, staged, or specified-ref Git diff by file | | /review [--staged\|ref] | Review Git changes with read-only permissions | | /todos | View the complete todo list for the current session | | /agents | View subagent sessions created by the current session | | /jobs | View background jobs and their runtime status | | /copy | Copy the latest complete assistant response |

#### Extensions, display, and exit

Command	Purpose
`/plugin [query]`	Inspect loaded extensions and their status
`/statusline`	Select the items displayed in the status bar
`/theme`	Switch the terminal color theme
`/help`	View key bindings, built-in commands, Harness commands, and user skills
`/quit`	Exit DSH-Code

#### Input and key bindings

Action	Purpose
`Enter`	Submit the current input
`Up` / `Down`	Recall the previous or next input-history entry
`Tab`	Complete commands, skills, or `@` references
`@`	Reference workspace files or existing sessions; image files are sent as attachments
`Ctrl+O`	Inspect full history and tool details
`Ctrl+R`	Fold or expand model reasoning
`Shift+Tab`	Cycle through permission Presets
`Delete`	Cancel the newest queued message when the composer is empty
`Ctrl+K`	Delete from the cursor to the end of the line
`Ctrl+U`	Clear the current input line
`Ctrl+A` / `Ctrl+E`	Move to the beginning or end of the current line
`Esc`	Close the current menu or interrupt the running turn
`Ctrl+C`	Cancel a task, clear the input, or exit, depending on the current state
`Ctrl+D`	Exit DSH-Code

4. How DSH-Code integrates with DSH

1. Runtime composition

DSH-Code reads the live Harness registries instead of maintaining a separate local copy. Model adapters, tool providers, skill sources, commands, permission policies, persistence backends, sandboxes, and subagent providers can all be added or replaced through DSH composition.

/plugin provides a read-only view of the current Cordis loader state.

2. Session-scoped Agent Presets

The Host owns the shared infrastructure—registries, persistence, session queries, permissions, and sandbox policies—while each session receives an isolated Agent scope composed by an Agent Preset:

standard — a full-featured general-purpose coding Agent
code — multi-operation workflows designed for Code Mode / PTC
minimal — only a persistent shell and str_replace_editor
cordis — the full Agent plus runtime inspection and Preset-authoring guidance
user Presets — custom tools, prompt sections, skills, context compaction, plan mode, and subagent behavior

Use /mode before the first turn, or start directly with --mode <preset>. The selected Preset is written to the session and restored when the session resumes.

3. Session history and recovery

Prompts, streaming chunks, tool calls and results, model selections, plan state, permissions, titles, and Preset selections are all projected from durable Session events. Session recovery, export, history inspection, context metrics, and terminal replay use the same record.

React state stores only temporary interface details such as the input draft, cursor, active panel, selection, and scroll position.

dsh profile
└─ Host plane: registries · persistence · queries · permissions · sandbox
   ├─ Agent session A + preset code
   ├─ Agent session B + preset minimal
   └─ DSH-Code TUI
      durable events → pure projection → append-only transcript
                                  └→ bounded panels → composer → status bar

5. Development

pnpm install
pnpm test
pnpm typecheck
pnpm build
pnpm run gen:whale   # regenerate src/whale-glyph.ts from the vendored logo path

The whale glyph is generated from the DeepSeek FishLogo geometry vendored in scripts/fish-logo.ts (source: DeepSeek Harness, MIT).

1. Source development installation

For a local checkout:

dsh plugin --profile cli add file:C:/path/to/dsh-code

GitHub installation is available for source development:

dsh plugin --profile cli add github:unlinearity/dsh-code

The Git package builds during installation. If pnpm asks for an allowBuilds entry, copy the complete entry it prints into ~/.dsh/profiles/cli/pnpm-workspace.yaml, then run the command again. The key contains the Git URL and commit, so it cannot be replaced with only dsh-code.

2. Uninstall

dsh plugin --profile cli remove dsh-code   # unmount the plugin from the cli profile
npm uninstall -g dsh-code                  # remove the global package and the deepseek / dsh-code commands

Both commands are required for a complete uninstall. The first only removes the profile mount, so the deepseek command still exists and reports "the cli profile does not mount dsh-code yet". The second removes the global npm package and its launch aliases. Uninstalling does not affect @deepseek-ai/dsh itself or any persisted session data.

3. References

Runtime services, events, plugin scopes, and the persistence model follow DeepSeek Harness.
Session navigation, overlay sizing, scrollback, bottom layout, and resize handling refer to Codex CLI.
Slash-command discovery, turn steering, reasoning folds, approvals, and question flows refer to Claude Code.

DSH-Code is an independent MIT-licensed community project and is not affiliated with OpenAI or Anthropic.

Communities:

Linux DO: Learn AI at L Station!
DeepSeek Harness: the official DSH website

License

[MIT](LICENSE). The vendored FishLogo geometry comes from DeepSeek Harness (MIT).

Source facts

Install

Check the source files