dsh-better-sidebar
ctx.betterSidebar service open to every plugin
✨ Features
| 🗂️ File Management Lazy-loading tree, git status colors, live directory watch, global search, drag-and-drop upload, multi-select batch actions, dual-source "Open with" menu.   | 🌿 Git Source Control (Merge / Staged / Changes groups, message box with Generate, branch + sync footer) plus a this-session AI-changes lens, with a read-only commit graph (lanes, branch and tag badges, branch filter, commit details) in one tab.  |
| 📝 Editable Editor & Previews An editable CodeMirror (the stock preview is read-only), Markdown + Mermaid + floating outline, sandboxed HTML preview, .jsonl record cards, paged preview for huge files, streaming transfers with no size caps. | 🧩 Tasks Live subagent topology (workflow graph / tree modes) + background task list: exit codes, live output, force-kill. |
| 💬 Side Chat (beta) Codex-style side threads: inherit the full parent context and run independently, realtime push, visible & revocable queue, per-thread model selection, one-click promotion to a top-level session. | 🖥️ Bottom Workbench A self-drawn bottom panel that coexists with the native right sidebar: drag-to-split panes, multiple terminal tabs, per-session persisted layout. |
Also: 📂 the sidebar_open tool lets the model open the sidebar itself · ⚡ ~325KB core at startup, heavy chunks load on demand · 🌏 i18n follows DSH · 📱 narrow screens switch to a full-width drawer
🌿 Git Graph (read-only commit graph)
Switch to Git Graph at the top of the Git panel for commit nodes, forks and merge edges across local branches, remote-tracking branches and HEAD. The branch selector only filters history — it never checks out or fetches; each commit is one line (lane edges + ref pills + subject), hover shows the author and short hash, and selecting one opens its full message and diff in the bottom pane. History loads in pages; reference changes during pagination prompt a refresh; reads are bounded (200 commits per page, offset 10,000, 1,000 branches) and report an explicit error past a limit. Lightweight and annotated tags appear on commits in the graph, rows and details use neutral tag pills, and tag changes invalidate pagination. Tag decorations keep the first 5,000 tags by ref name, further bounded by an 8 MiB complete-line output prefix; excess tags are omitted without failing the graph.
🧭 dsh-context diagnostics (optional)
With the dsh-context plugin installed, three places offer a one-click jump into that conversation's Context view: an agent node's detail card on the Tasks page, a background job's output window (the job's real owner session — never merely the session its row was watched under), and the session header. The entries appear only while dsh-context's Context page is actually registered: a deployment without it (or with that page hidden) shows no control at all, and while one jump is in flight every entry point is disabled. A failed jump is reported once, in a dismissible alert at the frame's bottom edge; nothing is polled while idle.
🚀 Installation
dsh plugin --profile web add dsh-better-sidebar@latestThen hard-refresh the browser (Cmd/Ctrl+Shift+R). Requires DSH 0.2.2-rc.1+.
Compatibility warning — match the plugin to the host line. As of 2026-11-04, DSH's npm
latestis 0.2.1-rc.5 andnextis 0.2.2-rc.1. v0.30.0 requires DSH 0.2.2-rc.1+; hosts on the 0.2.1 line (0.2.1-rc.1 ~ rc.5, i.e. today'slatest) must pindsh-better-sidebar@0.28.2— v0.29.0 was never published to npm. DSH 0.2.1-alpha.5 users must pindsh-better-sidebar@0.28.0-alpha.0, and hosts still on 0.2.0-rc.2 must pindsh-better-sidebar@0.26.1. A 0.x caret never spans a minor version, so one plugin build cannot serve two host lines. The marketplace installer picks the plugin'slatestregardless of host version, so an old host gets a version-rejection error — upgrade the host or pin the version explicitly. The two packages'latesttags are independent.
Pick the plugin version for your DSH version
| Your DSH version | Install command |
|---|---|
| 0.2.2-rc.1+ | dsh plugin --profile web add dsh-better-sidebar@0.30.1 |
| 0.2.1-rc.1 ~ 0.2.1-rc.5 | dsh plugin --profile web add dsh-better-sidebar@0.28.2 |
| 0.2.1-alpha.5 | dsh plugin --profile web add dsh-better-sidebar@0.28.0-alpha.0 |
| 0.2.0-rc.2 | dsh plugin --profile web add dsh-better-sidebar@0.26.1 |
| 0.2.0-rc.1 | dsh plugin --profile web add dsh-better-sidebar@0.24.1 |
| 0.1.7-rc.1 ~ 0.1.7 stable | dsh plugin --profile web add dsh-better-sidebar@0.22.1 |
| 0.1.7-alpha.x | No compatible release — upgrade DSH to rc.1 first |
| 0.1.6 and earlier (incl. the 0.1.5 line) | dsh plugin --profile web add dsh-better-sidebar@0.19.1 |
Always pin exact versions for older releases (latest moves forward with each new stable). Replace web with your own profile name.
Other ways to install
Let DSH install it for you — paste this prompt into any DSH session:
Install the dsh-better-sidebar plugin (a sidebar workbench for DSH):
1. Confirm DSH is 0.2.2-rc.1 or newer, then run dsh plugin --profile web add dsh-better-sidebar@0.30.1
2. Remind me to hard-refresh the browser (Cmd/Ctrl+Shift+R) afterwards
If something fails, check the FAQ table in https://github.com/omdsh-dev/DSH-better-sidebar README first.One-line script — clone this repo and run bash scripts/install.sh 0.30.1 (macOS / Linux / Windows Git Bash; ./scripts/install.ps1 -Version 0.30.1 for native Windows). It handles installation + bundle registration.
Updating: just re-run the install command, then hard-refresh the browser.
FAQ
| Symptom | Cause & fix |
|---|---|
Ignored build scripts error | pnpm 11 blocked a transitive dependency's build script. Run pnpm approve-builds in the profile directory (~/.dsh/profiles/web) — this plugin itself has no build-script dependencies. |
minimum release age / version younger than 24h | The release is less than 24 hours old. Wait 24h or re-run (pnpm auto-adds minimumReleaseAgeExclude). |
| "Profile directory not found" | Run dsh web once to initialize ~/.dsh/profiles/web. |
Host dies on start: DesktopHostFatalError: … required plugins did not activate / better-sidebar | The profile carries its own @deepseek-ai/dsh-* copies (left by an older DSH, or listed in the profile's package.json / overrides) and they resolve ahead of the installation, so the dsh-subagent this plugin imports statically binds to a mixed set; when an export is missing the host only reports this fatal and never names the package. Confirm with the check shipped in the current plugin: node ~/.dsh/profiles/web/node_modules/dsh-better-sidebar/scripts/check-profile-host-tree.mjs ~/.dsh/profiles/web. Fix: remove @deepseek-ai/dsh-* from the profile's package.json / overrides and pnpm install there (the installation then supplies them), or align both copies to one version; then restart. The install scripts run this check for you. |
| Two sidebars on the page | Double mounting. Remove the legacy manual mount line (- insert: ... better-sidebar ...) from ~/.dsh/profiles/web/cordis.patch.yml; aggregate packages mounting this package under a different id are auto-yielded, no action needed. |
| Settings values gone after upgrade | Since DSH 0.1.7, preferences live on this plugin's mount row in the profile (default entry id better-sidebar). The plugin migrates your old settings.yaml values once on first start and never overwrites newer values. |
| Terminal unavailable | Terminals are provided by DSH itself (this plugin ships no PTY) — see DSH docs; "host provides no terminal capability" in the bottom terminal means this deployment has no terminal controller mounted. |
dsh: command not found | Install DSH first; or use npx -y --package @deepseek-ai/dsh@0.2.2-rc.1 dsh plugin --profile web add dsh-better-sidebar@0.30.1. |
🆕 Recent Updates
v0.30.1 — settings nav icon fix
- The "Side card" row in Settings no longer shows two icons. The plugin used to paint its own glyph over the shell's fallback gear with a CSS mask; the shell now wraps the nav icon in a container and exposes a per-section icon slot. The row contributes its icon through that slot, and the stale marker + CSS apparatus is gone — along with a document-wide DOM observer.
v0.30.0 — DSH 0.2.2 support, side-chat images, clickable quote chips
- DSH 0.2.2-rc.1 is the new baseline (all 14 peer floors move to
^0.2.2-rc.1). The host replaced the installable model-selection ref with an agent-ownedAgentModel, so a side-chat thread's model switch now goes throughagent.model.select()— recorded once in the log and applied to the next step. A 0.x caret never spans a minor: DSH 0.2.1 hosts (today's npmlatest) keep pinning plugin v0.28.2. - Side Chat takes images: paste a screenshot or pick PNG / JPEG / WebP / GIF, preview or remove before sending, or send images alone; the preview survives a reload and a cold restore.
- Quote chips are clickable: a passage selected with "Add to conversation" lands as a chip that jumps back to the source file and flashes the quoted lines, with a nonce so a second click jumps again; if the reference record cannot be persisted the plugin falls back to the previous built-in chip instead of landing a dead one.
- Drafts survive the host-owned close paths: closing a native sidebar tab or quitting the desktop app keeps the unsaved draft and offers it back when the same file is reopened — the host exposes no cancellable close hook, so this is backup-and-restore rather than a prompt.
- Reliability: a side-chat seed built from a compacted parent no longer persists an unreadable session log; page CSS zoom is no longer misread as a page transform; the bottom workbench terminal no longer paints black; container workspaces show every child repository in the Git panel; the installers refuse a profile whose
@deepseek-ai/dsh-*copies are a mixed version pair and print the repair command.
v0.29.0 — GenUI in side chats
- Adds the opt-in
registerSidechatSurfaceAdapterservice for GenUI 0.15.0. Settled assistant replies can render interactive components, with actions and state kept in the owning child thread. - Uninstalled consumers, streaming replies and unsupported fences retain the existing Markdown view. The 0.28.2 cold-session read fix remains included.
- Provider contribution: @sunxiuguo, #1033.
🔌 Plugin Ecosystem
ctx.betterSidebar offers two extension points to every plugin — registerTab / registerFileViewer; the built-in 6 tabs + 4 viewers use the very same API. The GitHub topic dsh-better-sidebar already lists 30+ ecosystem plugins; the full integration guide is at docs/external-plugin-guide.md.
import type {} from 'dsh-better-sidebar' // triggers the ctx.betterSidebar type merge
export const inject = ['betterSidebar']
export function apply(ctx: Context) {
ctx.effect(() => ctx.betterSidebar.registerTab({
id: 'my-plugin:db', title: 'Database', component: ({ scope }) => <DbView sessionId={scope.sessionId} />,
}))
}Ecosystem catalog (28 tab plugins · 4 viewer plugins · 4 enhancements)
📑 Tab plugins (sidebar pages)
| Plugin | ⭐ | Description |
|---|---|---|
| ChenRuoT/dsh-sidebar-qa |  | Select-to-ask side page: Codex-style side questions / Claude Code /btw |
| fuhefei/dsh-sentinel |  | Condition-driven wake-up system: file / command / HTTP / process / webhook watchers that wake an agent; dock + sidebar branch + global dashboard |
| Fisfzy/ego-browser |  | Agent browser: i18n-aware local browser tab (auto-registers a sidebar page when better-sidebar is present, falls back to a floating observer) |
| jiuge2467/dsh-studio |  | Full-stack workbench: multi-source MCP visual debugging hub, visual thinking engine |
| Iwctwbh/dsh-flowglass |  | Flowglass: realtime session flow visualization (messages / tool groups / subagent branches) |
| FeatherHunter/dsh-mattpocock-skills-deck |  | Gamified mattpocock/skills task system: fog-of-war map, task bar progression |
| GULI-lab/DSH-element-source |  | Click any UI element to jump to its Vue / React / Svelte / Angular source and feed it into the session |
| Lzh3070/dsh-file-review-tab |  | File review page: line-level red/green diff + undo + deep links into chat lines |
| yq04/dsh-git-remotes |  | Git remotes page: branches / upstreams / ahead-behind, fetch with prune, ff-only pull, confirmed push |
| ztyhehe/dsh-better-sidebar-svn |  | SVN source-control page: status / diff / log / commit / update / revert / conflict resolution, symmetric to the built-in Git panel |
| Melody-max114/dsh-excel-panel |  | Excel editing page: xlsx preview / edit, live formula evaluation, merged cells, save back to the original file |
| v587d/dsh-anysearch-refs |  | AnySearch result reference cards: query, source digest, keyword highlights |
| Lukeknow0/dsh-markdown-link-preview |  | Markdown artifact link preview: click same-origin .md outputs in chat to read them in the sidebar |
| mlosun/dsh-docs-panel |  | Global docs panel: portable Markdown notes readable from any workspace |
| tylina/dsh-tylina |  | Typst document tool: WYSIWYG typesetting for papers, reports, exams, resumes, charts, posters, sheet music, and PPTX-exported slides |
| lnyuqian/dsh-skill-sidebar |  | Skills panel: scans local skill directories, short action phrases + one-click copy + pinning |
| g-yixuan/dsh-sidenote |  | Codex-style side chat + selection-anchored annotations (lightweight consumer plugin) |
| OMSociety/dsh-ssh-tunnel |  | Multi-host SSH tunnels + SSH manager page |
| OMSociety/dsh-git-forge |  | GitHub / Gitea accounts, project authorization and push policies |
| YesSanSan/dsh-conversation-outline |  | Conversation outline page: turn-structured view, one-click jump, LLM one-line titles |
| Wulabalabo/dsh-sidebar-Explorer-Plus |  | File manager page: upload / move / delete / rename / new folder (write operations) |
| yq04/dsh-turn-review |  | Turn review: review agent changes turn by turn |
| Ghz114514/dsh-refpics |  | Pinterest-style reference-image search: masonry flow, sidebar board, download & Eagle favorites |
| yzlin499/dsh-yzlin499-easy-plugins |  | Handy utility bundle (friendly to bare-bones DSH) |
| dong-victor/dsh-better-sidebar-starter |  | Run-configuration page: IDEA-style Run/Debug configs — one-click start, history, WebSocket live logs, parallel instances |
| baosfeng/my-dsh-plugins |  | Personal plugin collection (dsh-file-activity): sidebar file-activity page — read / create / modify history and stats |
| Hoemr/dsh-better-overleaf |  | Overleaf tab: CDP browser login, project switching, local git mirror with two-way sync |
| Andor-Z/dsh-turn-outline |  | Turn-trace page: folds the session by user turns, click any step to jump back to its chat position; zero LLM, read-only |
🖼️ Viewer plugins (file viewers)
| Plugin | ⭐ | Description |
|---|---|---|
| HuanLinOTO/dsh-plugin-better-sidebar-plugin-office |  | Office trio preview (.docx / .xlsx / .pptx), shipped as a separate slim bundle |
| HuanLinOTO/dsh-plugin-better-sidebar-plugin-audio |  | Audio preview: zoomable waveform player + realtime spectrum, HTTP Range streaming route, scrubbable at any size |
| zemul/dsh-video-preview |  | Inline video preview: .mp4 / .webm / .mov / .mkv / .avi with HTTP Range seeking |
| dong-victor/dsh-better-sidebar-jupyter |  | Runnable .ipynb notebook view: lazy Python kernel, streaming output, save-back |
🧰 Enhancements & tools
| Plugin | ⭐ | Description |
|---|---|---|
| eg-bole/dsh-better-sidebar-icons |  | VSCode-style file / folder icon theme (vscode-icons port, pure DOM overlay, zero intrusion) |
| dong-victor/dsh-better-sidebar-terminal-plus |  | Terminal enhancements: bundled Nerd Font icons, fixed xterm icon rendering, stable terminal cwd |
| Max-Null/dsh-sidebar-preview-select |  | Preview selection boost: select text in the sidebar preview → floating "send to session" |
| Hoemr/dsh-quicklook |  | QuickLook-style Space preview: press Space on the active file tab for full-size image / PDF / text |
📣 List your plugin: tag your repo with the
dsh-better-sidebartopic to appear on the topic page; then PR aPluginEntryintosrc/client/plugins-tabs.ts/plugins-viewers.tsto join the in-app recommended catalog.
⌨️ Keyboard Shortcuts
| Action | Keys |
|---|---|
| Save editor | Ctrl/Cmd + S |
| Find / replace in file | Ctrl/Cmd + F |
| Find next / previous | Ctrl/Cmd + G / Shift + Ctrl/Cmd + G |
| Select next occurrence | Ctrl/Cmd + D |
| Git commit | Ctrl + Enter |
| Close tab | Middle-click |
| Split / merge panes | Drag a tab to a pane edge / center |
| Reference a file in the input box | Hover a row → @file button |
🔐 Security & ⚠️ Known Limitations
- Routes sit behind a Host-header trust fence (same as
/api);fs.writeis atomic; git is only invoked via CLI and never sets identity - ⚠️ Since v0.23.0 the fs routes do no workspace-containment check: they can read/write any path the host user can reach (OS permissions only) — callers must not treat these routes as fenced
- HTML previews render in an opaque-origin sandboxed iframe and serve relative CSS, JavaScript, JSON, fonts and WebAssembly with their content types; the sandbox can be disabled per feature in settings (off by default, with warnings)
- No git push/pull/fetch; the file tree only watches expanded directories; Markdown preview renders the saved file
- Read-only formats (spreadsheets / PDF / images / Office) are rendered by DSH's own document preview and follow the host version; the browser view only exists in the desktop profile
- Unsaved drafts are confirmed before closing a tab / deleting a file / refreshing; saving after external modification is rejected, never silently overwritten
- On mobile (<768px) there is no bottom panel — its tabs merge into the right sidebar's full-width drawer
🛠️ Development & Build
pnpm install # @deepseek-ai/* devDependencies are published, resolves directly
pnpm typecheck && pnpm lint && pnpm build && pnpm test
make check # aggregate gate (matches CI)
make mount # real-mount smoke: build + pack → pnpm test:mountArchitecture: a single npm package with host/client halves — host (src/index.ts): /sidebar/api/* JSON API, media / HTML preview / upload routes and two WebSockets; client (src/client/index.tsx): native right-sidebar tabs + bottom workbench; state persisted per session in localStorage. Repository rules: AGENTS.md.
Windows / Linux / macOS supported (macOS verified daily, the rest covered by unit tests and Windows CI); no native dependencies — building needs only Node ≥ 20 + pnpm ≥ 10.
💬 Community
QQ group: 577011007
🤝 Contributing
- Code changes go through PRs: develop on a
feat/*/fix/*branch →gh pr create; runpnpm typecheck && pnpm build && pnpm test(ormake check) before submitting - List an ecosystem plugin: tag your repo with
dsh-better-sidebar+ PR an entry intosrc/client/plugins-tabs.ts/plugins-viewers.ts - Repository rules:
AGENTS.md
👥 Contributors
🔗 Friends
- dsh-tianshu-tui: interactive terminal UI plugin for DeepSeek Harness with TDD and evidence-gate workflows
- dsh-TUI: Claude Code-style fullscreen terminal plugin — pixel-whale header, streaming thoughts, context progress bar + TPS gauge
- dshfind plugin store: third-party plugin market — public repos under the
dsh-plugintopic, synced daily - DeepSeek Harness Desktop Tauri: Tauri desktop build — 5MB installer, zero setup, plugins preinstalled
- DeepSeek Harness Desktop: a modern desktop app — start and manage local Harness services without configuring Node.js; website