dsh-vim

Vim-style modal keyboard navigation for the DeepSeek Harness Web GUI.

A short recording of modal navigation and the keybindings settings page in the DeepSeek Harness Web GUI.

• Core (src/core): framework-agnostic vim keyboard engine — keymap, router, modal state, cursor/scroll/composer actions.
• Adapter (src/adapter-deepseek-harness): thin DeepSeek Harness plugin shell that wires the core into Cordis services and the shell.overlay slot.

Status

Extracted from packages/client/ui-vim in the DeepSeek Harness repository (commit 528d5204, package @deepseek-ai/dsh-client-ui-vim).

Compatibility

Targets DeepSeek Harness 0.1.0-rc.7 (@deepseek-ai/* pinned to rc.7 in peerDependencies). The vim engine reads the rendered web shell through stable data-* attributes ([data-chat-flow], [data-shell-overlay], …); these are not a public API — pin the plugin to your harness version and verify after upgrading (see docs/adapter.md).

Default keymap

Sequence	Action
j / k	Move cursor down / up
g g / G	First / last row
h / l	Fold / unfold tool row
Ctrl+d / Ctrl+u	Half-page down / up
z z / z t / z b	Scroll cursor center / top / bottom
y y	Copy current row
Ctrl+1 / Ctrl+2	Toggle sidebar / details
g s / g d / g c	Toggle sidebar / details / goto conversation
Ctrl+h / Ctrl+l	Focus panel left / right (sessions · conversation · details; stops at edges). On the session list j/k pick a session, Enter opens it
:	Enter command mode
Esc	Back to normal mode (only Esc; Ctrl+[ is intentionally unbound)
g ?	Open the keybindings settings page (list + customize every binding)

Command mode (:):

Command	Effect
side	Toggle sidebar
details	Toggle details
theme <name>	Apply theme
vim on / vim off	Enable / disable vim keys
help / h	Show key help

Keybindings settings page

Press g ? (normal mode) to open the settings panel on the Vim keybindings page (also reachable via the sidebar gear → settings nav): it lists every binding of the current mode with its action, lets you rebind an action by pressing the new key sequence (multi-key combos like g g work; commit happens after a short pause), remove a binding, or restore the built-in keymap in one click. All changes persist to the durable ui-vim.keymap settings section, so they survive reloads and can be edited by hand in settings.yaml (see docs/adapter.md). While the page is on screen only g ? and Esc act; Esc also cancels a rebind capture.

Install / usage

This package publishes a framework-agnostic core as dsh-vim. The DeepSeek Harness adapter is shipped as source under src/adapter-deepseek-harness; see docs/adapter.md for how to load it in a DeepSeek Harness installation.

Installing into DeepSeek Harness

To enable vim-style keyboard navigation in your DeepSeek Harness Web GUI:

1. Install the bundle into your profile:

   dsh plugin --profile web add dsh-vim
   

   This adds dsh-vim as a dependency to your profile and registers it as a bundle layer. The cordis.patch.yml in the package inserts the host-side settings registration, the browser-side engine, and the invariant companion.

2. Verify the layer is active:

   dsh --profile web --dump-config | grep -A 5 ui-vim
   

3. Boot the Web GUI:

   dsh --profile web
   

   Press g ? in normal mode to open the keybindings settings page and customize bindings. Vim mode is enabled by default; toggle it with :vim off or :vim on in command mode.

Configuration

Vim settings are stored in the ui-vim section of your settings.yaml:

ui-vim:
  enabled: true
  indicator: true
  keymap:
    normal:
      x: copy-row
      j: ''  # removes the built-in j binding

See docs/adapter.md for the full settings schema.

From a local checkout

If you have a local clone of this repository:

dsh plugin --profile web add ./path/to/dsh-vim

This uses a pnpm link: dependency, so changes to the source are reflected after rebuilding (pnpm build).

From GitHub

dsh plugin --profile web add github:Loyage/dsh-vim

Note: git installs fetch sources, not built artifacts. The package includes a prepare script that builds automatically after installation.

FAQ

Symptom	Cause & fix
Ignored build scripts warning	pnpm 10+ blocks dependency build scripts by default. In the profile directory (~/.dsh/profiles/web) run pnpm approve-builds --all.
minimum release age / version younger than 24h	Freshly published versions are subject to pnpm's 24h minimum release age. Wait 24h, or re-run the command (pnpm fills minimumReleaseAgeExclude automatically).
“profile directory not found”	Run dsh web once to initialize ~/.dsh/profiles/web before installing plugins.
Keys unchanged after updating	Hard-refresh the browser (Cmd/Ctrl+Shift+R). Client changes hot-reload without a DSH restart; only host-half changes (src/adapter-deepseek-harness/index.ts, schema.ts, invariant.ts) need a restart.
Two mode indicators / keys respond twice	Double mount. Remove any leftover manual - insert line for dsh-vim in ~/.dsh/profiles/web/cordis.patch.yml; when an aggregate bundle (e.g. @linxin666/dsh-web-ui-all) mounts this package under its own entry id, the bundle patch backs off automatically — make sure only one channel is active.
Keys don't respond in an input field	In insert mode the vim keys intentionally don't hijack typing. Press Esc to return to normal mode.
Bindings break after a DSH upgrade	The engine relies on stable data-* hooks, which are not a public API. Pin dsh-vim to your harness version and re-verify after upgrading (see docs/adapter.md).

Known limitations

• Ctrl+[ is intentionally not bound as an alternative to Esc (see Default keymap).
• The data-* hooks the engine reads are not a public API — pin the harness version and re-verify after upgrading (docs/adapter.md lists the full selector set).
• Panel focus navigation stops at the edges (sessions · conversation · details) and does not wrap; on the session list j/k pick a session, Enter opens it.
• Multi-key sequences resolve within SEQUENCE_TIMEOUT_MS (900 ms); two presses slower than that are treated as independent actions.
• The g ? navigation to the settings page walks the shell's a11y hooks and is best-effort; the page can also be opened from the settings panel navigation.

Platform support

• Host: DeepSeek Harness 0.1.0-rc.7 web profile (--profile web), Node.js ≥ 20.
• Browser: any modern evergreen browser (Chrome / Edge / Firefox / Safari) — the client runs inside the shell, no browser-specific code.
• OS: no native dependencies, no node-pty-style compiled artifacts; consistent across Windows / Linux / macOS.
• Other clients: Web GUI only; the terminal client is out of scope.

Development

pnpm install
pnpm test
pnpm build

License

MIT. Contains code derived from the DeepSeek Harness project (packages/client/ui-vim, MIT, Copyright (c) 2026 DeepSeek).

Repository: https://github.com/Loyage/dsh-vim