dsh-better-sidebar: a service-based sidebar for DSH

What dsh-better-sidebar adds to a DSH session

DSH is the host; this plugin fills its right column. According to the README, the right column is DSH's own native sidebar API as of v0.19.0, and the plugin registers each tab type and tab body through ctx.sidebarRightTabs and ctx.sidebarRight. Files opened from chat go through ctx.sidebarRight.openResource('dsh-resource://file/…'). The plugin no longer draws the right panel itself, and the README states the older floating-window capability was removed at the same time. What the plugin keeps is its own bottom workbench, plus the ctx.betterSidebar service that other plugins call.

The audience is two groups. The first is DSH users who want a workbench next to the conversation: explorer, CodeMirror editor, xterm.js terminal backed by node-pty, a Git view, a sub-agent and background-task page, and a side conversation thread the README labels beta. The second group is DSH plugin authors. The README says the built-in 8 tabs and 6 viewers register through the same ctx.betterSidebar API as third-party plugins, with registerTab and registerFileViewer as the entry points, so a third-party tab is not a second-class citizen. That design choice is the interesting part of the project, and it is also what makes its release cadence a commitment.

How the sidebar is wired: native tabs, a bottom workbench, and a plugin service

The architecture has three layers. At the top, DSH owns the right column and its tab containers; the plugin supplies tab types and tab bodies through ctx.sidebarRightTabs and ctx.sidebarRight, and opens resources with dsh-resource://file/ URLs. In the middle sits the plugin's own bottom workbench, which the README describes as split panes, a terminal and per-session persistence, with the toggle button mounted to the right of the session header. Below both sits ctx.betterSidebar, the service other plugins consume to register tabs, file viewers and, per the feature list, custom file and directory icons through registerFileIcon.

Persistence is per session: layout, tabs and panels are stored per conversation, and the README says stale state is cleaned up automatically. Loading is split. The README states startup pulls roughly 325KB of core and that heavy dependencies such as the terminal, editor and Mermaid renderer are fetched on demand, pointing to a design document at docs/plans/2026-08-12-lazy-chunks-design.md. Two optional tools extend the model's reach: the terminal page can inject terminal_* tools, and a global setting injects a sidebar_open tool so the model can open a file, a folder (the tree re-roots to that directory) or an HTTP(S) page in the sidebar. Both are opt-in, which is the right default for anything that lets a model drive the UI.

Installing dsh-better-sidebar and opening your first file

The README lists the prerequisites as a working DSH (dsh web runs), Node.js 20 or later, and pnpm 10 or later. Installation is a plugin profile add. The first attempt is expected to fail: pnpm 11 blocks the node-pty build script, so the dependency lands but the build does not run. Approving builds in the profile directory re-runs the install, and the second add succeeds.

dsh plugin --profile web add dsh-better-sidebar@latest   # 首次会因 pnpm 11 拦截 node-pty 构建脚本而失败（依赖已写入）
cd ~/.dsh/profiles/web && pnpm approve-builds --all      # 放行构建脚本（自动重跑安装）
dsh plugin --profile web add dsh-better-sidebar@latest   # 重跑即成功

After that, hard-refresh the browser (Cmd/Ctrl+Shift+R). The README notes DSH hot-reloads client changes, so no restart is needed unless the host half changed. You should then see the sidebar and the toggle button to the right of the session header.

The README also documents a second route: hand the install to a DSH session itself. The prompt it gives starts with the same dsh plugin --profile web add command and then runs pnpm approve-builds under ~/.dsh/profiles/web. That is convenient, but it is the same two steps, so the failure on the first attempt is not something the prompt avoids.

For the first real use, open a file from the conversation. Per the README, chat file opening now goes through ctx.sidebarRight.openResource('dsh-resource://file/…'), which lands in the native right column. From there the explorer tree, the editor, the terminal and the Git diff view are tabs in that column, while the bottom workbench holds the split panes. The terminal tab can be pinned: right-click it and choose pin to workspace or pin to global, after which it survives session switches and appears inline in the TabBar.

Version coupling is the real constraint

The README is unusually explicit about version support, and that is the main thing to weigh. Release v0.19.0 targets DSH 0.1.5-rc.1 and later; v0.19.1 was verified on 0.1.5-rc.2 while keeping the peer floor at ^0.1.5-rc.1. Users still on DSH 0.1.5-alpha.2 are told to pin dsh-better-sidebar@0.19.0-alpha.1. Users on the 0.1.2-rc.1 stable line stay on 0.18.x. Anyone on DSH 0.1.1-rc.2 or earlier uses 0.17.1. Four parallel tracks, each with its own pin.

That is a deliberate consequence of building on a release-candidate API. The v0.19.0 release itself was a break: the plugin stopped drawing its own right panel and moved onto DSH's native sidebar API, and the older floating-window capability was removed rather than kept as a fallback. If your DSH version and your plugin version drift apart, the failure mode is a sidebar that does not mount, not a degraded one. The README documents the pins but does not document a rollback path for a bad upgrade, so treat the version table as the thing you check before every DSH bump.

The second constraint is the install itself. Because pnpm 11 blocks node-pty's build script, a single-command install does not work; the README turns the failure into a documented three-step sequence. That is honest, but it means automated or unattended provisioning of this plugin needs the approve-builds step encoded, not just the add.

Built-in pages versus plugins you assemble yourself

The README states a principle it calls service-first: the built-in tabs and viewers use the same registration API as third-party plugins, and features the maintainers no longer ship in core are left to ecosystem plugins. It cites 28 or more ecosystem plugins and a GitHub topic, dsh-better-sidebar, for discovering them.

The alternative is the obvious one: install separate DSH plugins for each capability, a file viewer here, a terminal there, a Git panel somewhere else, and let DSH's own right sidebar host them. The difference is in who owns the container. With separate plugins, each one registers its own tab through DSH's API and you configure them independently; nothing coordinates layout, and per-session persistence is whatever each plugin implements. With dsh-better-sidebar, one plugin owns the bottom workbench, per-session layout persistence, the tab registry and the file-icon registry, and other plugins plug into that. You get coordination at the cost of a dependency: the sidebar framework becomes a piece of infrastructure your other plugins assume.

That trade-off is real and the README does not pretend otherwise. If you only want one panel, the framework is more than you need. If you are the one writing the panels, ctx.betterSidebar with registerTab, registerFileViewer and registerFileIcon is the integration surface, documented in docs/external-plugin-guide.md.

Maintenance, licence and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-16. The release history is dense: v0.19.0-alpha.1 on 2026-09-09, v0.19.0 on 2026-09-10, v0.19.1 on 2026-09-11. That cadence tracks DSH release candidates, and it cuts both ways. Fixes for a new DSH candidate arrive quickly, but the plugin is a moving target, and each DSH bump is a version-matching exercise rather than a routine update.

Licence is MIT, which is permissive and imposes no copyleft obligation on plugins that link against the service. The README does not discuss trademark or redistribution terms beyond the licence badge, and nothing here is legal advice; if you redistribute the plugin inside a product, read the LICENSE file at the repository root.

The upgrade cost is visible in the repository layout. The Makefile wraps package.json scripts and defines a check target that chains typecheck, lint, build, test and check:consumer-types, plus mount and mount-aggregate targets that build, pack and run Playwright mount smoke tests, and a registry target that packages a plugin registry. If you fork or vendor this plugin, that is the gate you inherit. For a consumer, the cost is lower: watch the version table, and re-run the approve-builds step whenever the dependency tree is rebuilt. The README does not document a downgrade procedure, so pinning before an upgrade is the safer habit.

Editorial conclusion

Adopt it if you already run DSH 0.1.5-rc.1 or later and want a file, terminal and Git workbench inside the sidebar, or if you are writing a DSH plugin and want to register tabs through ctx.betterSidebar instead of drawing your own panel. Do not adopt it if you are pinned to an older DSH line and cannot move; the README maps 0.18.x to DSH 0.1.2-rc.1 and 0.17.1 to DSH 0.1.1-rc.2 or earlier, so you would be running a branch that no longer receives the current work. Before installing, confirm your DSH version with dsh web, then check that Node.js is at least 20 and pnpm at least 10, because the install path depends on both.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. omdsh-dev/DSH-better-sidebar on GitHub
4. README
5. Releases