dsh-emacs — an Emacs client for DeepSeek Harness
Use DeepSeek Harness (dsh)
from Emacs: streaming replies, tool calls, workspace sessions, subagent chats,
file attachments, and model selection. Requires Emacs 28.1+, with no
mandatory third-party Emacs packages.
https://github.com/user-attachments/assets/9ee9fc66-1997-49b7-a921-5753690edafa
The development version (0.9.0 - Unreleased) targets dsh 0.2.2-rc.1. The protocol reference records the 2026-11-05 source audit and adaptations for batched projection updates, explicit session activation and image-reference reads. Browser-cookie authentication is retained. The last live E2E validation used dsh 0.2.1-rc.2 with dsh-emacs 0.8.0; it does not validate this new baseline.
Quick start
Clone the repository:
git clone https://github.com/vritser/dsh-emacs.git ~/dsh-emacsAdd this to your Emacs configuration and evaluate it, or restart Emacs:
(add-to-list 'load-path (expand-file-name "~/dsh-emacs")) (require 'dsh-emacs)Run
M-x dsh-emacs. It opens the session list and starts a local server if needed, offering to install the dsh CLI when it is missing.Configure a provider with
M-x dsh-emacs-add-provider, or useM-x dsh-emacs-open-webfor account sign-in and other provider families. Credentials and model settings stay on the dsh server.Press
cto create a session, useC-c C-mto choose a model, then type after❯and pressC-c C-cto send.
For an existing server, configure its address and authentication
before connecting. A use-package example is in
Customization.
For multiple project services, use the development version’s
connection lifecycle and optional profile switcher.
After disconnecting, run M-x dsh-emacs to reconnect to the configured service.
Using it
M-x dsh-emacs opens the session list with Recents first: the 15 most
recently updated visible sessions with workspace labels, followed by their
usual workspace groups.
Set dsh-emacs-session-recents-limit to change the count (zero hides Recents).
Set dsh-emacs-session-recents-show-workspace to nil to hide workspace labels.
Press RET to open a session, c to create one, and TAB to fold a group
or expand available subagents.
From a local project, the command locates its existing workspace; from a chat,
it locates that session. New sessions open an editable draft while connecting.
Opening an existing session in a fresh chat buffer completes only the latest
human round (a turn with a user-authored message), fetching extra pages for a
long round without moving your draft cursor. C-c C-o cancels an in-progress
history load; once finished, it loads 3 earlier user+assistant rounds by
default (dsh-emacs-history-rounds). Switching back to a live chat
preserves it.
The PTC mode preset ID is now ptc. If your configuration sets
dsh-emacs-default-preset to "code", change it to "ptc".
Idle session dots, the New Session placeholder and muted text (timestamps,
reply footers, deliverable descriptions, subagent error notices) use the
theme's shadow face (grey by default); running session dots are orange.
Essential keys
| Key | Action in a chat buffer |
|---|---|
C-c C-c |
Send; while busy, queue input or interrupt if input and attachments are empty |
C-u C-c C-c |
Steer the running turn (default configuration) |
C-c C-b |
Interrupt the running turn |
C-c C-q / C-c C-j |
Manage pending messages / background jobs |
C-c C-m / C-c C-e |
Select a model / change reasoning effort |
C-c C-a |
Stage a file; repeat to add more |
C-c C-v / C-c C-d |
Paste a clipboard image / discard staged attachments |
C-c C-o |
Load 3 earlier user+assistant rounds; prefix chooses the count; press again to cancel |
C-c > |
Return to the draft and follow new output |
C-c C-w / C-c C-y |
Copy content / fork through the assistant reply at point |
C-c C-l |
Locate this session in the list (jump preference) |
C-c C-s / C-c M-s |
Switch sessions in this workspace / across all workspaces |
C-c C-r |
Refresh the chat |
M-p / M-n |
Recall previous / next input |
TAB |
Complete commands, skills, references, local paths, or words |
User messages stay left aligned with a teal left rail and light inner
spacing, with one blank line before and after each question. Answers
remain frameless; completion summaries leave a small gap above the answer without changing its font.
Ordinary Emacs undo applies only to the input, leaving the transcript intact.
Copying a user-message line yields its authored text; pasting does not carry
the conversation rail or spacing into the destination.
M-x imenu navigates the conversation's questions. Click a folded tool or
thinking header, or press RET on it, to expand it. Once a turn ends,
continuous thinking and tool cards between replies fold into activity summaries
such as Read files and ran commands. Replies stay outside these groups.
Successful turns without mid-turn input additionally fold their whole process
under Completed…, leaving any final answer visible. Failed and Stopped
are non-foldable status rows, as are completion rows for turns with mid-turn input;
their internal activities still fold independently. Running turns stay open.
Earlier history extends disclosures without resetting manual expansion.
Set dsh-emacs-fold-work-details to nil and reopen the chat for a flat transcript.
See Web folding rules and remaining differences.
Visible chat windows follow new output independently while their cursors and
views stay near the draft, preserving each editing position. Windows reading
older messages stay put; C-c > returns that window to the draft and following.
Typing from the read-only transcript jumps to the composer; extend
dsh-emacs-composer-typing-commands for a mode-specific editing command
(see Customization).
The 0.7.0 release removes dsh-emacs-group-consecutive-tools and
dsh-emacs-assistant-divider; both are deleted, so remove any remaining
entries from personal configuration. Tool cards still fold independently and
assistant message spacing is unchanged. See
Customization.
The unused Lisp helpers dsh-emacs-modeline-set-cwd,
dsh-emacs-modeline-set-branch, dsh-emacs-modeline-teardown and
dsh-emacs-usage-p are also removed in 0.7.0 without aliases. Remove calls
from personal Lisp code; cwd and branch follow the chat's default-directory
and cached Git detection. See Mode-line.
References, commands, and attachments
@references select server-side files, directories, or sessions. Discovery runs in the background; Corfu refreshes as results arrive, while other frontends may need anotherTAB. See @ references./commands and skills complete withTAB, including after a space inside a message. Use/planfor plan mode and/plan offto leave it. Submitted plans open in a review buffer. See Slash commands and Skills.- Attachments are staged with
C-c C-a, clipboard paste, or drag-and-drop.C-c C-csends them with your input; a blank input uses their file names. See Attachment staging. !git statusruns locally in the session's workspace. Its output is neither sent to the model nor saved in server history. Plain path completion also uses the machine running Emacs; use@for remote server files. See Shell commands.
Unfinished output stays in a compact transcript card, explicitly labelled Retry (scheduled or started), Failed reply, Cancelled reply, or Retry cancelled using the server's follow-up events. Recovery without an explicit retry event shows Retried once another response arrives in the same turn and step. Partial output remains expandable; hover the title for failure details. The mode line keeps running activity and elapsed time without a separate retry label. If outcome events are unavailable, the card says Incomplete reply. Retry, cancellation, model errors and compaction failures share a status-dot icon: orange for retry, red for failure, grey for cancelled/unknown. Model error reasons remain visible below the title.
Goals, subagents, and questions
The composer shows the next pending message, then the active goal. C-c C-g
opens goal actions; C-c C-q manages the
queue.
The default busy-send behavior is configurable with
dsh-emacs-busy-enter-behavior.
M-, returns to the originating position after opening files, sessions,
plans, images or job output. M-x dsh-emacs-list-subagents opens child
conversations. Continuable children accept follow-up input, while
one-shot children are read-only. See Subagents.
Agent questions use your normal minibuffer completion. Pick an option or type
an answer; multiple-choice answers accept comma-separated options such as
2,3. Empty input skips a question. C-c C-p answers an expired timed question.
See Question prompts.
Appearance
The mode line shows model, usage, and activity. Install
Motion Line separately for an animated
whale and elapsed clock; without it, activity captions remain static.
Native mode lines always keep the plain DSH major-mode label; the separate
whale-tail animation, caption and clock appear only during activity.
Doom keeps its static whale logo and existing layout.
Completed replies show Copy, Fork and tokens together on the left, in order.
Elapsed time appears in the compact Completed disclosure above the answer; add duration to
dsh-emacs-reply-footer-items to also show it in the footer.
Transcript event rows follow dsh-emacs-render-style: full (the
default) draws dsh-web's SVG icons where Emacs can, while simple leads every
event row with one compact dot (state-colored where the row carries state) and
mutes the rest of the row.
See Mode line, Reply footer, and UI styling for configuration.
Server setup
By default, dsh-emacs manages a local server. For a server you run yourself:
(setq dsh-emacs-base-url "http://127.0.0.1:3080"
dsh-emacs-server-auto-start nil)
Remote addresses, including HTTPS, never trigger a local server start.
Authentication is automatic for servers started by dsh-emacs. For an external
server, paste its printed launch URL (http://host:port/?token=…) into
dsh-emacs-base-url, set dsh-emacs-server-auth-token, or supply the token when
prompted. Successful prompted tokens are saved; a server restart may require
a new one. Reverse-proxy Basic auth is separate from the dsh launch token.
See Server options for configuration and managed-process ownership, Adding providers for model setup, and Editing dsh configuration for local or TRAMP configuration files.
Documentation
- Customization — options, history, workspaces, approvals
- @ references · Slash commands · Skills
- Shell commands · Model picker · Subagents
- Mode line · UI styling
- Changelog — release notes and breaking changes
- Architecture · RPC protocol
Contributing
Follow AGENTS.md, keep changes focused, and run
scripts/verify.sh before pushing. It checks syntax, byte compilation, unit
tests, clean loading, and repository hygiene. CI runs the same gate on Emacs
28.1 and a current stable release. Optional
GUI tests and
real-server tests cover display
and transport behavior.
After editing source and finishing pending uploads/submissions,
M-x dsh-emacs-reload reloads it while preserving chats and drafts.
Upgrading live 0.8.0 connections requires disconnecting and reconnecting;
removed definitions and changed struct layouts require a restart.
See Source reload.
Acknowledgments
The UI mirrors dsh web. Markdown rendering and folding build on agent-shell; mode-line stats and compact token formatting follow pi-mono.
License
GPL-3.0-or-later — GNU General Public License v3 or later.
No comments yet. Be the first to write one.