dsh-better-sidebar

A service-oriented sidebar framework, and a complete workbench out of the box







A dual workbench (right sidebar + bottom panel) that opens its ctx.betterSidebar service to every plugin —
register new sidebar pages and file viewers via registerTab / registerFileViewer.

📑 Contents

• ✨ Features
• 🚀 Installation
• 🖼️ Feature Tour
• 🌐 Plugin Ecosystem
• 🆕 Recent Updates
• ⌨️ Keyboard Shortcuts
• 🔌 Service API
• 🛠️ Development & Build
• 🔐 Security · ⚠️ Known Limitations · 🖥️ Platform Support
• 🤝 Contributing · ⭐ Star History · 🔗 Friends

✨ Features

• 🗂️ File Workbench: file explorer (lazy-loading tree; symlinks show their target kind — directory links expand, dangling links flagged) + CodeMirror editor; inline preview for images / Markdown (incl. Mermaid diagrams, strict-mode safe rendering + click-to-zoom) / HTML / PDF
• 🌐 Embedded Browser: multiple web tabs with back / forward / refresh; content runs in a sandboxed iframe; external links are routed by protocol by default — HTTP opens in the sidebar, HTTPS goes to the system browser (both adjustable in settings)
• 💻 Real Terminal: xterm.js + node-pty real shell, reconnect with transcript replay; optionally injects terminal_* tools for the model
• 🌿 Git Panel: real diff + VSCode-style diff tabs, history, right-click to stage / commit / revert
• 🧩 Background Tasks: agent topology + background tasks (exit codes / live output / force-kill)
• 💬 Side Chat (beta): Codex-style side threads — the child inherits the parent's FULL context (completed turns + the pending question + the in-progress turn's assistant output and tool activity, honestly frozen as "interrupted") and runs independently without entering the main conversation; threads support continuous follow-ups (auto-resumed after a DSH restart) and one-click "Save as new session" promotion to a top-level session
• 🪟 Dual Workbench: right sidebar + bottom panel; drag tabs to split / merge panes (cross-panel), mobile auto-merges into a full-width drawer
• 🔁 Session Isolation: layout / tabs / panels persisted per session, stale state auto-purged
• ⚙️ Declarative Settings: per-item toggles in the "Side Cards" settings section, secondary settings via the gear dialog
• ⚡ On-demand Loading: only ~325KB core at startup; heavy deps (terminal / editor / mermaid diagrams) load on demand (design)
• 🌏 i18n: UI text follows DSH's language (zh / en) with live switching

🔌 Core principle: service-first — the 7 built-in tabs + 6 viewers register through the same ctx.betterSidebar API as third-party plugins, with fully equal capabilities; anything the ecosystem can provide better is delegated to ecosystem plugins (26+ ecosystem plugins already — see "🌐 Plugin Ecosystem" below). See "🔌 Service API" and the external plugin guide.

🚀 Installation

Prerequisites: DSH installed (dsh web boots), Node.js ≥ 20, pnpm ≥ 10.

Supported DSH versions:

dsh plugin --profile web add dsh-better-sidebar@latest   # first run fails: pnpm 11 blocks node-pty build scripts (the dependency is still written)
cd ~/.dsh/profiles/web && pnpm approve-builds --all      # allow the build scripts (re-runs the install automatically)
dsh plugin --profile web add dsh-better-sidebar@latest   # re-run succeeds

Then hard-refresh the browser (Cmd/Ctrl+Shift+R) to see the sidebar (DSH hot-reloads client changes; only host-half updates need a restart).

Or 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. Run: dsh plugin --profile web add dsh-better-sidebar@latest (the first run fails because pnpm 11 blocks node-pty build scripts — that's expected)
2. In ~/.dsh/profiles/web run: pnpm approve-builds --all (allows the build scripts and re-runs the install)
3. Run the add command again: dsh plugin --profile web add dsh-better-sidebar@latest
4. When done, remind me to hard-refresh the browser (Cmd/Ctrl+Shift+R)
If anything fails, check the troubleshooting table in the README at https://github.com/omdsh-dev/DSH-better-sidebar

dsh plugin --profile web add dsh-better-sidebar@latest

1. git clone https://github.com/omdsh-dev/DSH-better-sidebar.git ~/Code/DSH-better-sidebar
   cd ~/Code/DSH-better-sidebar && pnpm install && pnpm build
2. In ~/.dsh/profiles/web/package.json dependencies write "dsh-better-sidebar": "link:<absolute path of the clone>"
3. Append this mount line to ~/.dsh/profiles/web/cordis.patch.yml (to pick the terminal shell, add `config.shell`; `config.shellArgs` starts it with explicit args — when non-empty they replace the default `-l`. When omitted the host resolves `$SHELL` / the login shell / powershell.exe):
   - insert:
       - id: better-sidebar
         name: 'dsh-better-sidebar'
         config:
           shell: /bin/zsh
           shellArgs:
             - --noprofile
             - --no-rc
4. Run pnpm install in ~/.dsh/profiles/web
5. Restart DSH and hard-refresh

git clone https://github.com/omdsh-dev/DSH-better-sidebar.git && cd DSH-better-sidebar
pnpm install && pnpm build
node scripts/package-registry.mjs   # assemble the registry/ staging (manifest + artifacts + README, not committed)
dsh registry install ./registry     # install (disabled by default)
dsh registry enable dsh-external/dsh-better-sidebar

🖼️ Feature Tour

Below are real UI screenshots.

🗂️ File Workbench: Explorer

Two explorer modes: embedded in the file preview / standalone file tree. Lazy-loading directory tree, symlinks classified by target kind (directory links expand, dangling links flagged), global filename search, file/folder upload buttons plus drag-drop upload, context menu (open in new tab / open to the side / copy paths), and a hover @file button that references a file straight into the composer.

📝 Inline Preview: Markdown · Images · PDF

The Markdown preview renders Mermaid diagrams (strict-mode safe rendering + a second sanitize pass; click a diagram for a zoom modal with wheel-zoom and drag-pan); images / PDFs display inline via the media route; the Office suite is covered by an ecosystem plugin.

💻 Real Terminal

xterm.js + node-pty real shell (not an emulator): transcript replay on reconnect, configurable shell / shellArgs (settings page or cordis.patch.yml), and optional terminal_* model tools so the agent can open terminals and run commands itself.

🌿 Git Panel

Stage / unstage / commit (Ctrl+Enter) / revert, plus a history list; clicking a changed file opens a VSCode-style diff tab (line-level red/green).

🌐 Embedded Browser

Multiple web tabs with back / forward / reload / address bar; content runs in an opaque-origin sandboxed iframe (live sandbox status in the UI, per-page temporary unlock available); external-link clicks in the chat can be taken over into the sidebar (protocol-based routing, configurable).

🧩 Tasks: Agent Topology + Background Jobs

Live subagent-tree topology (run states, batched live previews) plus the background-jobs list (exit codes / live output / force-kill); new subagents / jobs can auto-expand the sidebar (configurable).

💬 Side Chat (beta)

Codex-style side threads: one independent tab per conversation; the thread inherits the parent's full context (including the in-progress turn, honestly frozen as "interrupted") and runs independently without polluting the main session; follow-ups survive restarts; one click promotes the thread to a top-level session.

🪟 Dual Workbench: Sidebar + Bottom Panel + Split Panes

The right sidebar and the bottom panel can stay open together; drag a tab to a pane edge to split, to the middle to merge (works across panels); panel width/height drag from the left/top edge; on mobile everything merges into a full-width drawer.

⚙️ Declarative Settings

The "Side card" section in DSH settings: one small card per tab / viewer with an independent toggle (highlighted enabled state + brand switch); secondary settings open from the "Feature settings" strip at the card bottom (switch / text / number / select rows); plugin-owned settings persist under pluginSettings.

📱 Mobile

On narrow screens (<768px) the panels become a full-width drawer: bottom-panel tabs merge into the sidebar once, with touch-friendly dragging.

🌐 Plugin Ecosystem

The ctx.betterSidebar service opens two extension points to every plugin: registerTab (sidebar pages) and registerFileViewer (file previewers). The 7 built-in tabs + 6 viewers register through the exact same API — fully equal capabilities.

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} />,
  }))
  ctx.effect(() => ctx.betterSidebar.registerFileViewer({
    id: 'my-plugin:csv', exts: ['csv'], fetchStrategy: 'custom',
    load: async (path, scope) => parseCsv(await fetchText(scope, path)),
    component: ({ customData }) => <CsvGrid rows={customData} />,
  }))
}

The GitHub topic dsh-better-sidebar already hosts 26+ ecosystem plugins (and growing):

The built-in "Add plugins" modal in settings: recommended catalog + one-click install command + a direct link to the GitHub topic

📑 Tab Plugins (sidebar pages)

Plugin	⭐	Description
ChenRuoT/dsh-sidebar-qa		Selection-based side Q&A — Codex-style side questions / Claude Code /btw
fuhefei/dsh-sentinel		Condition-driven wakeup: file / command / HTTP / process / webhook watches that wake the agent; dock + sidebar branch + global dashboard
jiuge2467/dsh-studio		Full-stack enhancement workbench: multi-source MCP visual debugging hub, visual thinking engine
Iwctwbh/dsh-flowglass		Flowglass: live session flowgraph (messages / tool groups / subagent branches)
FeatherHunter/dsh-mattpocock-skills-deck		Game-like mission system for mattpocock/skills: fog-of-war map + task bar
GULI-lab/DSH-element-source		Click any UI element on your dev page to jump to its Vue / React / Svelte / Angular source, straight into the chat
Lzh3070/dsh-file-review-tab		File-change review tab: line-level red/green diffs + undo + chat-line deep links
yq04/dsh-git-remotes		Git remotes tab: branches / upstream / ahead-behind, fetch with prune, ff-only pull, confirm-before-push
ztyhehe/dsh-better-sidebar-svn		SVN source-control tab: status / diff / log / commit / update / revert / conflict resolution — symmetric to the built-in Git panel
Melody-max114/dsh-excel-panel		Excel editing: xlsx preview/edit, live formula evaluation, merged cells, save back to the original file
v587d/dsh-anysearch-refs		AnySearch results as sidebar cards: query, source snippets, highlighted keywords
mlosun/dsh-docs-panel		Global docs panel: portable Markdown notes, readable from any workspace
lnyuqian/dsh-skill-sidebar		Skills panel: scans local skill directories, one-click invocation copy, pinning
g-yixuan/dsh-sidechat		Codex-style side chat + selection annotations (a thin consumer plugin)
thirsty5034/dsh-ssh-tunnel		Multi-host SSH tunnels + SSH manager tab
thirsty5034/dsh-git-forge		GitHub / Gitea accounts, project grants and push policy
YesSanSan/dsh-conversation-outline		Conversation outline tab: per-turn structure, quick jump, one-line LLM titles
Wulabalabo/dsh-sidebar-Explorer-Plus		File-manager tab: 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 wall, sidebar board, downloads, save-to-Eagle
yzlin499/dsh-yzlin499-easy-plugins		A handy utility bundle for a bare-bones DSH

🖼️ Viewer Plugins (file previewers)

Plugin	⭐	Description
HuanLinOTO/dsh-plugin-better-sidebar-plugin-office		Office-suite preview (.docx / .xlsx / .pptx) as a separate bundle to slim the core (in the official recommended catalog)
zemul/dsh-video-preview		Inline video preview: .mp4 / .webm / .mov / .mkv / .avi with a /video host route supporting HTTP Range scrubbing
dong-victor/dsh-better-sidebar-jupyter		Runnable .ipynb notebook view: lazy-start Python kernel, streaming outputs, save-back

🧰 Enhancements & Tools

Plugin	⭐	Description
dong-victor/dsh-better-sidebar-terminal-plus		Terminal enhancement: bundled Nerd Font icons, xterm glyph fixes, stable terminal cwd
Max-Null/dsh-sidebar-preview-select		Preview selection boost: select text in any sidebar preview → floating "send to session"

📣 List your plugin: tag your repo with the dsh-better-sidebar topic to appear on the topic page; then PR one PluginEntry into src/client/plugins-tabs.ts / src/client/plugins-viewers.ts to join the built-in recommended catalog (data integrity is guarded by tests/plugin-list.spec.ts).

🆕 Recent Updates

Supported DSH versions: · full release history on the Releases page

v0.15.0

All changes since v0.14.0:

✨ New features

• 💬 Side Chat (beta) tab (#286): Codex-style side threads, one independent tab per conversation — the child inherits the parent's full context (completed turns + pending messages + the in-progress turn's assistant output and tool activity, honestly frozen with an "interrupted" marker); created with an identical composition (same preset / provider / model) so the first request reuses the parent's input prefix cache; threads stay invisible in the main session list with zero subagent-catalog noise; follow-ups survive DSH restarts (auto cold-resume); one-click "Save as new session" promotes the thread to a top-level session (design)
• 📤 Upload into the files window (#239): header "upload file / upload folder" buttons plus drag-drop (drop on the tree body = workspace root, on a directory row = that directory, on a file row = its parent directory, VSCode semantics); full-window blurred progress overlay while uploading (per-file progress + cancel / Esc); buttons disabled while busy, tree refreshes after the upload settles
• 🧩 Desktop compatibility in four options (#284): "Position compatibility mode" is now a main-row dropdown — Auto-detect (default, conservative: only the standard Window Controls Overlay geometry contributes; real 32/36px caption-overlay heights per shell, live on maximize/restore; zero modification on plain web) / DSH official web (explicitly no adaptation) / Shell preset (built-in, opt-in; only shells that appeared in this repo's issues/PRs with 100+ stars, "detected" badge when the environment matches) / Custom (free-form CSS + shift distance). Documents that already carried compatibility values migrate to the custom scheme; interactive chrome opts out of desktop drag regions (no-drag); the bottom-push anchor is a composite selector ([data-pane] and :has(> [data-slot]))
• 🎛️ Settings page UI/UX modernization (#300): the side-card secondary-settings entry is now a full-width "Feature settings" strip at the card bottom (replacing the invisible corner gear — much easier to discover); coordinated two-tone enabled state (brand activation accent + success-green check badge); every color is still --dsw-alias-* token-derived so skins follow automatically
• ➕ New entries in the recommended-plugin catalog: dsh-docs-panel (global docs, #230), dsh-flowglass (#261), dsh-git-forge and dsh-ssh-tunnel (#204), dsh-turn-review (#102)

🐛 Fixes

• ⚡ Batched live preview for the subagent page (#298): the old implementation polled subagents.history per running subagent, each poll triggering a full host-side enumeration — an O(N²) amplification that stalled the page with many concurrent subagents; now a single batch route subagents.live (one enumeration of the whole tree) plus one client poller with a single in-flight request; display logic and copy unchanged
• 🖱️ Interrupted / fast-release drags no longer roll back (#249, closes #247 #248): interrupted or fast-released drags commit the last known position; HMR re-activation re-locates the center column (fixes the blank bottom panel after a hot reload)
• 📐 Push variables stay effective while mounted (#259, fixes #258): the bottom panel no longer flashes full-width after a drag is released
• 🔧 Adapted to DSH 0.1.1-rc.1 / rc.2 (@next) (#297 #305): no code changes needed
• 🔒 Upload-chain hardening (#239): empty and absolute relativePath segments are refused outright; uniquely named temp files (concurrent uploads stay independent, crashed processes never block later uploads); write-stream error listeners (a failing disk can no longer crash the host); client error codes unified with the wire (too-large), 413s localized

⌨️ Keyboard Shortcuts

🔌 Service API

Since v0.4.0 the plugin exposes the ctx.betterSidebar service — other plugins can register sidebar pages and file viewers (the 7 built-in tabs + 6 viewers register through the same service). v0.12.1 completed the base capabilities (complete type exports, capability detection, state subscription, tab badges, lifecycle callbacks, targeted open, plugin-owned settings, etc.).

Full integration docs:

• AGENTS.md — the in-repo integration doc (full fields, matching algorithm, HMR pitfalls, declarative settings, version detection);
• docs/external-plugin-guide.md — the external-plugin guide (with a complete minimal example).

➕ Add Plugins (recommended plugin catalog)

The dashed cards at the end of the "Sidebar content" / "File viewers" grids in the "Side Cards" settings section open the Add tab plugins / Add preview plugins modals: each declares its open extension point, offers a "Browse more plugins on GitHub" button (the GitHub topic dsh-better-sidebar), and lists the recommended catalog (name / repo / description / install script) — "Open" jumps to the repo, "Copy" writes the install command to the clipboard.

Curating a new plugin: append a PluginEntry to src/client/plugins-tabs.ts (tab registrations) or src/client/plugins-viewers.ts (file-previewer registrations) and tag your repo with the dsh-better-sidebar topic; data integrity is guarded by tests/plugin-list.spec.ts.

🛠️ Development & Build

pnpm install      # @deepseek-ai/* devDependencies resolve to 0.1.1-rc.1 (published) — no token needed
pnpm check:style  # ESLint correctness + low-churn formatting gate
pnpm typecheck    # tsc --noEmit
pnpm build        # → lib/index.js + lib/invariant.js + lib/client.js + lib/client-registry.js + lib/types
pnpm check:consumer-types  # browser-only public declaration check (build first)
pnpm test         # vitest (includes manifest consistency guard; build first)
pnpm watch        # tsdown --watch

Architecture: a single npm package with host/client halves — host (src/index.ts): /sidebar/api/* JSON API, /sidebar/file media route, /sidebar/html preview route, /sidebar/ws/terminal WebSocket (fs / git / pty / preview, all session-scoped with a trust fence); client (src/client/index.tsx): portal sidebar + views + interception; state persisted per session in localStorage. Organized per DSH official conventions (no default export, dual client bundles); no dependency on npm / checkout at runtime (@deepseek-ai/* provided by the web profile).

🔐 Security

• Routes protected by a Host-header trust fence (same as /api); fs.write is atomic; media/preview routes only serve files inside the session cwd; git only shells out to the CLI and never sets identity
• HTML preview and browser tab content render in opaque-origin sandboxed iframes (no allow-same-origin/allow-top-navigation, no-referrer, all permission policies disabled); the /sidebar/html route carries a CSP sandbox + size/path bounds; the address bar rejects javascript:/data:/file: and local addresses like localhost
• The UI shows the sandbox status live (red warning when off) and can temporarily unlock the current page; the settings page can disable the sandbox per feature (disabled by default, with a warning) — when off, content shares the origin with the UI; only recommended for fully trusted content

⚠️ Known Limitations

• Git has no push/pull/fetch; no file watcher (manual refresh); tool inline file-open buttons cannot be intercepted
• Dragging a terminal tab to another pane remounts it (shell restarts)
• Office-suite preview (.docx/.xlsx/.pptx) moved to the recommended office plugin (see the "Add plugins" modals in settings); without it these files fall through to the code/download fallbacks
• Browser sandbox has no login state / third-party cookies are restricted; some sites need popup login; sites that refuse embedding via X-Frame-Options/frame-ancestors (e.g. arxiv.org) show a reason panel (with "Open in browser"); in-iframe navigation does not enter the back stack
• HTML preview renders the saved file (not unsaved drafts)
• No bottom panel on mobile (<768px): on narrow screens its tabs merge into the right sidebar once (after migrating back to desktop they stay in the right sidebar); the desktop bottom panel is only available on wide viewports; auto-open terminal on first bottom-panel expand does not trigger on mobile

🖥️ Platform Support

Windows / Linux / macOS (macOS validated daily; the rest covered by unit tests); node-pty prefers prebuilt binaries, otherwise a build toolchain is required (Windows VS Build Tools / Linux make+g+++python3 / macOS Xcode CLT).

🤝 Contributing

• Code changes go through PRs: develop on a feat/* / fix/* branch, then gh pr create; docs-only changes may be pushed to main directly
• Curate an ecosystem plugin: tag your repo with dsh-better-sidebar + PR a PluginEntry into src/client/plugins-tabs.ts / plugins-viewers.ts
• Before submitting: pnpm check:style && pnpm typecheck && pnpm build && pnpm check:consumer-types && pnpm test (CI additionally gates on npm-pack → real-mount → headless-render via pnpm test:mount)
• See AGENTS.md for the repository rules (hard constraints, CI lanes, release flow)

⭐ Star History

👥 Contributors

Thanks to everyone who contributed:

🔗 Friends

• dsh-tianshu-tui: an interactive terminal UI plugin for DeepSeek Harness (its rendering core evolved from the self-developed harness agent Tianshu-Tui), adding TDD and evidence-gate workflows on top of the official harness
• dsh-TUI: a Claude Code-style fullscreen interactive TUI plugin — pixel-whale top bar, live working-status row, streaming thought expansion, double-Esc rollback, context progress bar + TPS meter; one-command npm install
• dshfind Plugin Market: a third-party plugin marketplace — a listing of public repos under the GitHub topic dsh-plugin, with stars, contributors and growth data synced daily
• DeepSeek Harness Desktop: a modern desktop client for the DeepSeek Harness ecosystem — start and manage a local Harness service without configuring Node.js or running commands; official site