dsh-emacs-bridge

dsh-emacs-bridge

This is a two-way bridge between GNU Emacs and the (DSH). It lets you control DSH from Emacs, including submitting prompts, reading replies, and controlling sessions. The Emacs-side user interface is designed to closely follow Emacs conventions.

Installation

The bridge consists of two components: a DeepSeek Harness plugin (dsh-emacs-bridge), and an Emacs package to interact with the harness. The package ships the baseline library dsh-bridge.el plus an optional companion, dsh-bridge-extras.el; the baseline never loads the companion on its own.

Requirements

• dsh, the DeepSeek Harness.
• pnpm installed on the executable path (DSH uses it to install plugins).
• GNU Emacs, version 29 or later, installed on the executable path.
• (Recommended) The Markdown mode Emacs package. From Emacs, install it via M-x package-install RET markdown-mode RET.

Installing via the DSH Plugin Manager

1. From the DSH web interface, click Plugins in the left panel,

then Add Plugin at the upper right. Enter dsh-emacs-bridge into the box, and click Install. When it finishes, click Enable Now.

Or, from the command line,

dsh plugin --profile web add dsh-emacs-bridge

1. If you are replacing a previous version of the plugin, restart DSH.

(This is not needed for a first-time install.)

1. You should now see a dsh-emacs-bridge entry in DSH's Plugins

page. Click on it to open the configuration card, then click on the Install Emacs package button. This installs the multi-file dsh-bridge package (the baseline library plus the optional dsh-bridge-extras companion) via the Emacs package manager.

1. After a first installation, restart Emacs or do `M-x

package-initialize in a running session. After upgrading a package whose libraries are already loaded, restart Emacs so the new code replaces the old; package-initialize` alone does not reload features. The DSH Bridge commands will then be available in Emacs.

You can also install these same files manually: go to the GitHub release list, look for the file dsh-emacs-bridge-.tgz, and get its URL. Use this URL in the Add Plugin box, or in the command dsh plugin --profile web add . Then download the accompanying Emacs package dsh-bridge-.tar, and install it with M-x package-install-file.

Manual installation from sources

You can also directly build and install the DSH plugin and Emacs library from this repository. First, go to this repository's root directory and run the following to build the plugin:

make build

Next, install the plugin. If you have dsh installed on the executable path, run this:

# from this repo root:
dsh plugin --profile web add link:./dsh-plugin
dsh web

If instead you run DSH from a source checkout (pnpm dsh web), run the following from the deepseek-harness directory, replacing the link: path with the appropriate path into this repo:

# from deepseek-harness root:
pnpm dsh plugin --profile web add link:/absolute/path/to/dsh-emacs-bridge/dsh-plugin

Finally, install the Emacs library by putting this in your Emacs init file, replacing the path with the actual path to this repository's emacs/ directory:

(add-to-list 'load-path "/path/to/dsh-emacs-bridge/emacs")
(require 'dsh-bridge)
;; Optional: the detail inspector.  The baseline never loads it.
;; (require 'dsh-bridge-extras)

make package also builds a multi-file dsh-bridge-.tar that M-x package-install-file can install directly.

Usage

From Emacs, the main entry-points are these two commands:

• M-x dsh-bridge — open a transient menu for DSH commands.
• M-x dsh-bridge-list-sessions — show a list of DSH sessions.

Consider giving either or both a global keybinding, e.g.,

(keymap-global-set "C-c d" #'dsh-bridge)

Transient menu

The M-x dsh-bridge command opens a transient menu that prompts for the next command. The menu's top line shows the session to be acted on (chosen based on your recent activity); you can cycle through available sessions with M-p/M-n.

Type RET to perform the default interaction on the session. For example, if the session is running, this command opens a view buffer to show the replies; if the session is idle, it opens a prompt buffer as well as a view buffer (if there are replies).

Here is a full list of commands are available from the transient menu:

• q — exit the transient menu.
• M-p/M-n — cycle through other sessions, ordered by age.
• RET — visit the session (e.g., open a prompt buffer and/or view

buffer for it).

• r — open a buffer to type in a prompt.
• f — fetch and display the latest set of replies.
• D — describe the session.
• I — inspect the session's newest turn in the optional detail

inspector (loads dsh-bridge-extras on first use).

• t — pin the current session as the target.
• u — unpin the currently-pinned session.
• k — stop the running session.
• o — compact the session's context history.
• l — open the DSH-Sessions buffer.
• + — create a new session and pin it.
• p — toggle plan mode.
• G — set or edit the goal objective (with C-u, also the round cap).
• A — pause an armed goal, or resume and rearm a stopped one.
• X — clear the current goal.

DSH-Sessions buffer

The M-x dsh-bridge-list-sessions command opens a list of DSH sessions. The pinned target session (if any) is marked by a * in the leftmost column, and the S (state) column shows each session's live status. The following commands are available from here:

• q — quit the window and bury the buffer.
• RET — visit the session at point (similar to RET in the

transient menu).

• r — open a buffer to type a prompt for the session at point.
• f — fetch and display the output from the session at point.
• a — answer a pending user query for the session at point.
• k — stop the session at point if it is running.
• o — compact the context history of the session at point.
• t — pin the session at point as the target. A cold session binds

without being resumed; the host resumes it when a later request acts on it.

• u — unpin.
• v — toggle whether archived sessions are shown (hidden by default).
• R — rename the session at point.
• d — archive the session at point.
• U — unarchive the session at point.
• + — create a new session, in an existing or new workspace.
• W — rename the workspace of the session at point.
• D — describe the session at point.
• I — inspect the session's newest visible turn in the optional

detail inspector.

• g — refresh the DSH-Sessions buffer.

For a full list, see the menu bar. Other tabulated-list-mode keys are also available.

DSH-View buffer

This read-only buffer contains the model output for a DSH session. Each buffer holds one agent turn (i.e., all replies from a user prompt to an idle). It is fetched by f from the transient menu or the DSH-Sessions buffer, C-c C-f from the prompt buffer, or pushed from the web UI's "Send to Emacs" button (see below).

The following commands are available in a DSH-View buffer:

• g — re-fetch the current session's newest turn.
• r — open a DSH-Prompt buffer for the current session.
• B — branch the shown turn into a new session.
• k — stop the shown session's running turn.
• o — compact the shown session's context history.
• i — receive the latest "Send to Emacs" turn (see below).
• v — show or hide the turn's tool calls and thinking summaries.
• D — describe the current session.
• I — inspect the shown turn in the optional detail inspector,

starting at the activity entry or changed file at point.

• M-p/M-n — cycle the current session's turns.
• l — open the DSH-Sessions buffer.
• q — quit the window and bury the buffer.

When created, a DSH-View buffer usually follows the latest turn, automatically updated as more replies arrive. Walking back through older turns with M-p suspends following; cycling back to the newest turn with M-n resumes it automatically. To customize this behavior, change dsh-bridge-view-follow-at-newest.

If Markdown mode is installed, and dsh-bridge-view-gfm is non-nil, the replies are font-locked as GitHub-Flavored Markdown.

By default, a DSH-View buffer shows only the assistant's replies. Type v (dsh-bridge-view-toggle-activity) to toggle viewing other activity reports in the buffer, including tool calls and reasoning block summaries.

Agent queries and approval requests

If the model requests additional user input via the ask_user_question tool, the query is surfaced in the DSH-View buffer. Type a here (or in the DSH-Sessions buffer with point on the session) to open a buffer for handling the query. In the resulting buffer, navigate to each question block and mark your desired option with RET (or choose it with a number key), or type c to enter a custom answer. To submit the answers, type C-c C-c. Alternatively, type C-c C-k to decline the query.

Special approval requests from the model (e.g., for sandbox escalation) are also surfaced in the DSH-View buffer. Upon receiving such a request, type a to see the details in a help window; then you can type y to accept the request once, n to reject it, or c to cancel it. Quitting (C-g) leaves the approval pending; type a again to restart it.

If the web UI is open, the query or approval is shown there too. Whichever answers first, Emacs or web UI, settles the request and dismisses the other presentation. To change this (e.g., letting the web UI handle all requests), customize dsh-bridge-approval-answer.

Turn detail inspector (optional)

The optional dsh-bridge-extras library adds a read-only inspector for the complete committed detail of one turn: full reasoning text, exact tool arguments, tool result content, and the durable per-call file diffs recorded by write and edit. Open it with M-x dsh-bridge-extras-inspect-turn, with I from the transient menu or a DSH-View buffer, or with I in the DSH-Sessions buffer. From DSH-View it inspects the shown turn and selects the activity entry or changed file at point; elsewhere it inspects the newest visible turn without resuming a cold session. The inspector is fetched lazily over the bridge's read-only /details/* routes; nothing is inserted into the DSH-View body.

• TAB/RET — disclose or hide the entry at point (the first

disclosure fetches its detail).

• n/p — move between entries.
• g — refresh the turn index, keeping disclosure state.
• e — visit the file named on the current changed-file line.
• L — fetch the next page of a large entry.
• q — quit the window.

Limits are deliberate. Only entries still visible on the current session surface are shown, so a compaction-shadowed block stays hidden. Per-call diffs cover write and edit results that recorded durable hunks; a str_replace_editor result has no such record and shows none (its arguments remain available from the tool-call entry), and creates or identical writes have no diff text. The displayed diff is an applied per-call fragment for reading, not an appliable patch, so line navigation and patch application are not offered. At most 2000 index entries are listed per turn; larger text is served in 64 KiB pages, and diff input/output are bounded (256 KiB per side, 128 KiB of display). Cold and archived sessions are read without being resumed; archived sessions remain readable until unarchived.

If Markdown mode is installed, reasoning text is fontified with its presentation faces transferred onto a copy; the inspector's own major mode is unchanged. Above a size bound the text is shown verbatim rather than truncated.

DSH-Prompt buffer

The DSH-Prompt buffer is used to compose a prompt, or reply. It is opened by r from the transient menu, DSH-View buffer, or the DSH-Sessions buffer. You can also open it with RET from the DSH-Sessions, if the session is waiting for a prompt.

The target session is determined by how the buffer was invoked; for instance, r from a DSH-View buffer opens a prompt for the same session.

The following commands are available from the DSH-Prompt buffer:

• C-c C-c — send the prompt, and pop to a DSH-View buffer to see the reply.
• C-c C-a — attach a file to the prompt (see below).
• C-c C-m — set the model and reasoning effort.
• C-c C-s — rebind the buffer to another session.
• C-c C-k — stop the session if it is running, or erase the prompt otherwise.
• C-c C-o — compact the session's context history.
• C-c C-f — open the DSH-View buffer for this session.
• C-c C-l — open the DSH-Sessions buffer.
• M-p/M-n — walk the session's prompt history.

When Markdown mode is installed, this buffer derives from it, so most markdown editing commands are also available.

If the session is running when you invoke C-c C-c, the command asks how exactly to send the prompt; you queue it to run after the current turn, steer the running turn, or cancel. Customize dsh-bridge-send-while-running to change this behavior. To unconditionally steer, type C-u C-c C-c.

While walking the prompt history with M-p/M-n, you may edit earlier prompts. This blocks further history navigation; to resume, you must send the prompt first, or revert with M-x revert-buffer.