dsh-advanced-sidebar

@achasoft/dsh-advanced-sidebar

A session menu and a resizable side dock for the DeepSeek Harness (dsh) Web Client. The ⋯ menu in the session header opens these panels in a column to the right of the conversation:

• Changes: git status, diffs, staging, commit, a model-written commit message, and push;
• Terminal: your own shells, in tabs;
• Files: a file browser with text preview;
• Preview: dev servers, workspace files, URLs, or a scratchpad;
• Background tasks: the session's jobs.

The same menu has Open in, Download session log, Archive, and Delete. Work the browser cannot do itself (running git, opening a pseudo-terminal, launching an editor) runs on the host through this plugin's own RPC namespace. One optional model tool, ui_preview, lets the agent inspect and drive the Preview panel.

Features

Session menu

A ⋯ button in the open session's header. It acts on that session, using the session's own working directory, or its workspace path when the session has none.

When the host cannot serve an entry (git not installed, an editor command not found, no subprocess capability), the entry stays in the menu, disabled, with the reason next to it. An entry switched off in settings is not shown at all. The menu asks the host again each time it opens, so installing git or an editor shows up without a restart.

Download session log. The harness package @deepseek-ai/dsh-session-log-export adds its own ⋯ button, with that single entry, to the same header row. This plugin hides that button: it registers an entry with the same id (session-log-download) at priority -1, and moves the entry into its own menu. Exporting still uses the harness's controller and dialog, so /export keeps working. If the harness package is absent or its controller has a different shape, nothing is hidden and the menu has no Download entry.

The dock

Panels open in a column on the right of the app frame. The conversation narrows to make room, so the dock does not cover it.

• Resizing. Drag the left edge, use Left and Right on the focused handle, or double-click the handle to return to the configured width.
• Width limits. The width is kept between 280 px and 960 px, and never leaves the conversation less than 400 px.
• Narrow windows. When even the minimum width would squeeze the conversation below 400 px, the dock floats over the conversation instead.

Changes

• Status. The working directory's status, grouped as Staged, Not staged, Untracked, and Conflicted, with branch, ahead, and behind counts. Click a file to see its patch, with Copy patch.
• Staging. Stage / Unstage a file, or a whole group with Stage all / Unstage all.
• Commit. Commit records what is staged, with an optional Amend the previous commit. The author git would record (git var GIT_AUTHOR_IDENT) is shown under the message box, so a missing user.email is visible before you commit.
• Generate. Writes a commit message with the model the composer is currently set to. The model sees only the staged patch, up to commitMessageMaxBytes. The message goes into the box for you to edit, and nothing is committed automatically.
• Push. Pushes the current branch to its upstream (git push with no arguments). A branch with no upstream shows Publish instead, which pushes to origin, or to the first remote if there is no origin, and sets the upstream. Force push, a remote picker, and custom refspecs are not offered.
• No discard. There is no way to discard changes from this panel. Use the Terminal panel.

Terminal

• Your own shells. Interactive shells in the session's working directory, in tabs, up to maxTerminals. They are separate from the model's terminals.
• Controls. Interrupt and Ctrl+C send SIGINT to the foreground process group. Clear clears the screen, and Restart starts a new shell.
• Shells keep running. Closing the dock or switching panels leaves them running. Reopening a tab replays the output the host kept (terminalScrollback). Closing a tab ends its shell, and so does archiving or deleting the session.
• Emulator. The screen is @xterm/xterm, so colors, line editing, and full-screen programs work.

Files

• Browsing. The working directory, one level at a time. Hidden entries are excluded unless filesShowHidden is on.
• Preview. A text preview up to filesMaxPreviewBytes. Binary files show their size.
• Actions. Open with the default application and Show in file manager.

Preview

Four modes, with a viewport picker (Desktop, Tablet, Mobile, Custom) in every mode.

For a launch configuration, readiness means the configured port accepts a TCP connection, checked until previewReadyTimeoutMs. The child process gets PORT, NO_COLOR=1, and FORCE_COLOR=0. Stopping sends SIGTERM to the process tree, then SIGKILL after previewGraceMs.

.claude/launch.json example:

{
  "version": "0.0.1",
  "configurations": [
    { "name": "web", "runtimeExecutable": "npm", "runtimeArgs": ["run", "dev"], "port": 3000 }
  ]
}

Background tasks

• List. The session's background jobs, filtered by text, status, and start date, with duration and status.
• Stop. Requires allowTaskKill. Stopping a task also suppresses the completion notice the model would otherwise receive.
• Output. Requires showTaskOutput, and appears only after the task has finished and its completion has been reported. Reading output earlier would consume the output the model reads.

Settings card

Settings → Plugins → Advanced sidebar edits most settings and shows, for each Open in target and preview configuration, whether it is available on this host. See Configuration.

Requirements

• DeepSeek Harness 0.1.5-rc.2 with the web profile. This is the version the plugin is tested against. Node ^22.19 || >=24.
• pnpm on PATH, because dsh plugin runs pnpm.
• git 2.23 or newer on the host PATH for Changes, because unstaging uses git restore --staged.
• Harness capabilities, each optional. A missing one disables only the entries that need it, with the reason shown:

• OS: developed and tested on macOS. The code has Windows and Linux branches (shell fallback, file-manager command) that are not verified.

Install

dsh plugin --profile web add @achasoft/dsh-advanced-sidebar
dsh web

dsh plugin --profile <name> … runs pnpm with the remaining arguments in $DSH_HOME/profiles/<name> (default ~/.dsh/profiles/web). Afterwards, dsh adds every dependency whose package.json declares dsh.bundle to dsh.profile.bundles. This package declares "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }, so it is enabled with no manual edit. Restart dsh web after installing.

To uninstall, remove the package. dsh also drops it from dsh.profile.bundles:

dsh plugin --profile web remove @achasoft/dsh-advanced-sidebar

How cordis.patch.yml is applied

At boot, dsh builds the configuration from patch layers, in this order:

1. Each bundle's cordis.patch.yml, in dsh.profile.bundles order.
2. $DSH_HOME/profiles/<name>/cordis.patch.yml.
3. $DSH_HOME/cordis.patch.yml.
4. Any --patch <file> overlays.

Later layers override earlier ones by row id. This package inserts three rows:

To keep the sidebar but not give the model a tool, disable the third row in your profile's cordis.patch.yml:

- id: advanced-sidebar-ui-preview
  disabled: true

To see the composed result:

dsh --profile web --dump-config

Configuration

All keys below are in the config of the advanced-sidebar row. A patch replaces a row's whole config, so an override must restate every key. Copy the row from this package's cordis.patch.yml and edit it.

The host schema declares no defaults, and every key except commitMessagePrompt and terminalShell is required. The defaults listed are the values cordis.patch.yml ships. Changes saved from the settings card are stored as a user layer over the patch value. Card marks keys the card can edit. On a Web Client that is not on loopback the harness settings scope is unavailable, so the card and menu show the host's values read-only.

Menu and behavior

git (Changes panel)

Terminal and Files

Preview

Open in

The host refuses a configuration at load when:

• an editor id is invalid or duplicated, or an editor command is empty;
• a preview name is empty or duplicated;
• a preview row has no command, no URL, and no port;
• deleteMode is purge while confirmDelete is false.

The advanced-sidebar-ui-preview row has one key, commandTimeoutMs (default 15000, range 1000–600000). It is the default wait for ui_preview open when the call passes no waitMs.

Model tool and RPC

ui_preview

Registered only when the advanced-sidebar-ui-preview row is composed. It works only while the Preview panel is open in the same session. Otherwise it returns immediately with a message telling the model to open the panel.

dom, eval, click, and type refuse a cross-origin frame by name instead of returning nothing.

RPC namespace advancedSidebar

The browser half calls these endpoints over the harness's client connection:

• describe
• gitStatus, gitDiff, gitStage, gitUnstage, gitCommit, gitPush, gitCommitMessage
• terminalOpen, terminalRead, terminalWrite, terminalSignal, terminalClose
• listEntries, readFile
• previewList, previewStart, previewStop, previewLogs, previewFileInfo, previewPoll, previewResult, previewRelease
• openIn
• taskKill, taskOutput
• deleteSession

Every endpoint returns a result value with a failure code instead of throwing. The root export re-exports the types.

Security notes

• git does not run programs the repository configures.
  • Every git command passes -c core.fsmonitor=false.
  • Every git diff passes --no-ext-diff --no-textconv.
  • Read-only commands (status, diff, log, identity, remote list) switch off filter.<driver>.clean/process from the repository's local and per-worktree config. Global and system filters, such as git-lfs, still run. A driver name that cannot be disabled this way, because it contains =, makes the reading fail instead.
  • Stage, commit, and push are explicit user actions and keep git's normal behavior, including hooks and filters.
• No option injection.
  • Paths are checked to be inside the repository and passed after --.
  • The commit message is a single -m argument.
  • Publish checks the branch with git check-ref-format --branch, checks the remote as refs/remotes/<remote>/HEAD, and pushes -- <remote> refs/heads/<b>:refs/heads/<b>.
  • Credential prompts are disabled (GIT_TERMINAL_PROMPT=0), so a push that needs credentials fails instead of hanging.
• Host-enforced switches. allowGitStaging, allowGitCommit, allowGitPush, allowCommitMessageDraft, allowTaskKill, showTaskOutput, and showDelete are checked by the host, not only hidden in the UI.
• Paths stay inside the workspace. Files, Preview File mode, and ui_preview file arguments are resolved through the harness filesystem's containment check, so symlinks cannot escape.
• Panel terminals are separate from the model's terminals. They are allocated with ctx.subprocess.spawnTerminal, not the agent's terminal registry, so your keystrokes never reach a terminal the model controls.
• Preview routes are gated. The routes /advanced-sidebar/preview-file, /advanced-sidebar/preview-proxy (plus its websocket upgrade), and /advanced-sidebar/preview-scratchpad each call the harness connection's requestRejection first. That is the same host/origin check and signed dsh-auth-* cookie check that guards /api, and it answers 401/403 otherwise. If the connection has no such gate, the routes are not registered at all.
  • Loopback only. The proxy forwards only to literal loopback hosts (localhost, 127.0.0.0/8, [::1]). A hostname that merely resolves to loopback is refused.
  • No credential forwarding. The harness's dsh-auth-* cookie is stripped from forwarded requests and from upstream Set-Cookie headers.
  • Registered workspaces only. The file route serves only files inside a workspace in workspaceRegistry.
  • Scratchpad size. Scratchpad documents are limited to 1 MiB.
  • No caching. Responses are sent with no-store.
• A proxied page runs as the Web Client's origin. Its scripts can call the harness API with your session. Only preview dev servers you trust as much as a browser tab signed in to the harness.
• ui_preview open accepts any http(s) URL, like the address bar. Only loopback URLs become same-origin and inspectable.

Known limitations