DSH-better-sidebar

1.9kStars126Forks89Issues3Watchers

Provides a VS Code-style dual workspace (sidebar + bottom panel) for DSH: file editing, real terminal, Git, embedded browser and background tasks; session isolation with open page and file previewer registration for other plugins.

omdsh-devomdsh-dev
·omdsh-dev/DSH-better-sidebar.git
Language
TypeScript
License
MIT
Branch
main
deepseekdeepseek-harnessdshdsh-better-sidebardsh-pluginsidebar

Install

$ dsh plugin --profile web add github:omdsh-dev/DSH-better-sidebar

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

One-Line Pitch

Provides a VS Code-style right sidebar + bottom panel dual workspace for DeepSeek Harness (DSH) Web, featuring built-in file browsing/editing, real terminal, Git panel, embedded browser, and background tasks view, isolated per session, and exposes ctx.betterSidebar service for other plugins to register new pages and file viewers.

Core Features

  • Browse and edit files in session workspace: Indentable directory tree (with symlink recognition, broken links in red) + CodeMirror editor, supporting 14+ language syntax highlighting, search/replace, undo/redo; preview images/PDF/Markdown/HTML directly (sandbox iframe), Office requires recommended plugin
  • Run real terminal in sidebar: xterm.js rendering + node-pty backend shell, reconnection replays last transcript; switching tabs or refreshing keeps shell alive
  • Stage/commit/revert/checkout/history and diff viewing (diff uses dedicated tab), supports cherry-pick/revert
  • Embedded browser: Opens web pages in independent tabs, content runs in sandbox iframe; external links can be intercepted to sidebar by protocol (HTTP on by default, HTTPS off by default)
  • Background tasks panel: Sub-agent topology + exit codes, real-time output, and force termination
  • Exposes ctx.betterSidebar service to any third-party plugins via registerTab/registerFileViewer for new sidebar pages and file type viewers, with capabilities equal to built-in features

Technical Implementation

  • Languages: TypeScript (ESM); React 18 frontend, Node 20+ backend, bundles both host and client halves
  • Key Dependencies: node-pty (real terminal shell); @xterm/xterm + @xterm/addon-fit (terminal frontend); @codemirror/* (code editor family); ws + rxjs + schemastery (terminal WebSocket, reactive state, schema validation)
  • Architecture Pattern: Dual-half plugin. Host half (src/index.ts) registers /sidebar/api/* JSON endpoints, /sidebar/file media, /sidebar/html sandbox preview, /sidebar/ws/terminal terminal WebSocket, /sidebar/ws/agent-terminals push, all via same-origin Host-header trust fence as /api; client half (src/client/index.tsx) exposes registry service to all plugins mounted after via ctx.provide('betterSidebar', service)
  • Entry Files: host src/index.ts (exports apply/Config/Context), client src/client/index.tsx (exports apply/inject), mount declarations in cordis.patch.yml + package.json#dsh.bundle.patch

Use Cases

When DSH users need to "see and operate" project files generated by AI collaboration within the browser—manually editing a piece of code, running some shell commands to check intermediate outputs, comparing differences between two edits—without leaving DSH for VS Code or system terminal. Another typical scenario is plugin authors wanting to add dedicated sidebar pages and file viewers for their plugins; DSH-better-sidebar provides a registry service for horizontal extension between plugins, avoiding duplicating a set of panels, tab bars, split panes, terminal, and state management.

Prerequisites & Compatibility

DependencyMin VersionNotes
DeepSeek Harness (DSH)0.1.0-rc.6All @deepseek-ai/dsh-* and @deepseek-ai/cordis locked to ^0.1.0-rc.6, pre-release dist-tag must align (see package.json lines 84-104)
Node.js>=20Declared in engines.node field (package.json:39-41)
PlatformmacOS / Windows / LinuxmacOS verified daily by CI, Linux/Windows covered by unit tests; node-pty prefers prebuilt binaries, otherwise requires local build toolchain (macOS Xcode CLT / Linux make+g+++python3 / Windows VS Build Tools)
Native Modulenode-pty ^1.0Only terminal feature depends on it; when missing, other plugin capabilities remain usable (lazy loading + fallback introduced in 0.12.3, see issue #140)
Package Managerpnpm >=10pnpm 11 blocks build scripts by default; first install needs pnpm approve-builds --all in ~/.dsh/profiles/web to allow node-pty

Installation

dsh plugin --profile web add github:omdsh-dev/DSH-better-sidebar

Configuration

This plugin has two types of configuration: host pipeline configuration (written in ~/.dsh/profiles/web/cordis.patch.yml, rarely changed) and user preferences (in DSH Settings → Sidebar card, frequently changed).

Host Pipeline Configuration (defaults of Config schema)

ConfigTypeDescriptionDefault
readLimitnumberByte limit for single file text reading (exceeds = marked truncated)524288 (512 KB)
mediaLimitnumberMax bytes for image/PDF/HTML preview20971520 (20 MB)
listLimitnumberMax entries per directory level in file tree1000
terminalsPerSessionnumberMax concurrent UI terminals per session3
reconnectGraceMsnumberGrace period (ms) to keep shell process alive after terminal WebSocket disconnects, for seamless reconnect after refresh/tab switch30000
shellstringShell to use uniformly for UI terminal and agent terminals (absolute path or executable name); empty = auto-detect (POSIX uses $SHELL/login shell, Windows probes pwsh → PowerShell 5.1)""

User Preferences (in DSH Settings → Sidebar Card)

PreferenceTypeDescriptionDefault
openByDefaultbooleanWhether to expand sidebar by default for new sessionsfalse
defaultWidthPercentnumber (20–60)Sidebar width as percentage of window35
autoOpenSubagentbooleanWhether to auto-expand sidebar and jump to sub-agent page when session spawns a sub-agenttrue
autoOpenJobsbooleanWhether to auto-expand sidebar and jump to jobs page when new background tasks appeartrue
agentTerminalToolsbooleanWhether to inject model with terminal_create/list/send/read/wait_for/resize/signal/close tools; when off, existing agent terminals are released togetherfalse
bottomPanelAutoTerminalbooleanWhether to also open a terminal tab when bottom panel is first expanded in current sessiontrue
terminalFontFamilystringTerminal font stack, empty follows theme (--ds-font-family-code)""
terminalFontSizenumber (9–32)Terminal font size (px)13
interceptOpenPathbooleanWhether to intercept file paths clicked in chat (tool output, generated files, text references) to sidebar editor (requires both this and editor's own master switch to be on)true
editorExplorerbooleanWhether editor uses merged mode (top path input + dockable tree panel); when off, reverts to old standalone editortrue
titleBarCompatbooleanCompatibility mode for reserving native title bar space at top (only needed for Windows frameless window)false
titleBarStripPxnumber (0–120)Height reserved for above compatibility mode40
htmlViewerNoSandboxbooleanWhether to disable sandbox for HTML preview (not recommended, only for fully trusted local content)false
htmlViewerDefaultUnsafebooleanWhether HTML preview defaults to non-sandboxed state (each page can restore sandbox via top status bar)false
browserNoSandboxbooleanWhether to disable sandbox for browser tabs (not recommended, only for fully trusted sites)false
browserInterceptLinksbooleanWhether to intercept external link clicks in GUI to sidebar (master switch)true
browserInterceptHttpbooleanWhether HTTP external links are intercepted to sidebar by defaulttrue
browserInterceptHttpsbooleanWhether HTTPS external links are intercepted to sidebar by default (most HTTPS sites reject iframe, default off)false
tabsEnabledobjectPer-tab-id disable (e.g., {"editor": false}), missing = enabled{}
viewersEnabledobjectPer-file-viewer-id disable (e.g., {"code": false}), missing = enabled{}
pluginSettingsobjectSettings blobs for third-party plugins (key = descriptor id, for settings.pluginToggles){}

FAQ

Q: There are two sidebars on the page after installation. What should I do?

A: This indicates two mount paths were used simultaneously (npm bundle + manual patch), or manual mount entry wasn't cleared before switching to bundle path. Delete the manual - insert: ... better-sidebar ... line from ~/.dsh/profiles/web/cordis.patch.yml to let npm path take exclusive control (see README_EN.md:117-119).

Q: Terminal shows "node-pty failed to load" or terminal won't open at all. What now?

A: This is node-pty not loading correctly. After 0.12.3 (issue #140), the plugin won't crash because of this: UI terminal tab shows a copyable fix command, agent terminal tools are automatically skipped. Just run pnpm approve-builds --all && pnpm rebuild node-pty in ~/.dsh/profiles/web, restart DSH, and click "Retry" on the terminal tab.

Q: What Node and DSH versions are required? Why can't I install with an older Node?

A: Hard constraint: engines.node: ">=20"; all @deepseek-ai/dsh-* and @deepseek-ai/cordis are locked to ^0.1.0-rc.6 (package.json:84-104). After upgrading DSH or Node, if you encounter load failure, first check if the dist-tag and lockfile are in sync.

Q: How do other plugins register new pages and file viewers?

A: Use ctx.betterSidebar.registerTab({...}) / registerFileViewer({...}) in your plugin's client half—the same API as the built-in 6 tabs + 6 viewers. Be sure to wrap with ctx.effect(() => register(...)), whose disposer is automatically called by Cordis during HMR to avoid "already registered" errors on repeated mounts. Full guide in repository AGENTS.md / docs/external-plugin-guide.md.

Q: Where is browse/edit/terminal data stored? Will it leak across sessions?

A: UI state like layout, tab list, panel geometry is stored in browser localStorage and isolated by sessionId; host-side file read/write, Git operations, terminal processes, media/HTML preview paths are all scoped to current session's cwd, never reading other sessions' workspaces. Uninstalling the plugin clears UI state; project files and .git on disk are completely unaffected.

Q: Can I fully uninstall it?

A: Yes. Remove "dsh-better-sidebar" from dependencies in ~/.dsh/profiles/web/package.json, run pnpm install, restart dsh web, and hard-refresh the browser. The plugin doesn't write to home directory or depend on background processes, no "residue".

Q: Can the embedded browser log into sites like GitHub?

A: Browser and HTML preview run in sandbox by default (opaque-origin iframe, allow-same-origin off), cannot carry third-party cookies/login state; sites requiring login automatically open in system browser; when sites reject embedding via X-Frame-Options or CSP frame-ancestors, sidebar shows reason and provides "Open in browser" button. Sites requiring login can temporarily disable sandbox in settings, but this gives browsing content same-origin privileges as GUI, only use on trusted sites.

Q: Works on mobile?

A: Sidebar auto-merges to full-width drawer on narrow screens (<768px), still usable; bottom panel unavailable on narrow screens, browser panel tabs merged into right bar once; when returning to wide screen, these tabs won't automatically return to right bar, need manual drag back. This is a known behavior already documented in README.

Getting Started Difficulty

Beginner — single dsh plugin add + hard refresh to use; what you get is right sidebar + file editing + built-in terminal/HTTP external link browsing. For deeper customization: select which previewers to enable in settings, adjust panel width, decide whether to inject agent terminal tools, decide whether to disable HTML/browser sandbox, etc.

Known Issues & Limitations

  • Git has no push/pull/fetch: Built-in Git panel covers status / diff / stage / commit / branch / checkout / log / cherry-pick / revert / discard / show; push/pull/fetch requires recommended plugin dsh-git-remotes
  • No file watcher: File tree doesn't auto-refresh, need manual refresh button
  • Inline "Open File" button in toolbar cannot be intercepted: Only paths through ctx.workspaces.openPath (i.e., "in generated files", text references, etc.) are intercepted by interceptOpenPath
  • Dragging terminal tab to another pane restarts it: Moving terminal tab across panes remounts it, shell process doesn't persist across panes
  • Office suite preview moved to recommended plugin: Since 0.12, .docx/.xlsx/.pptx are no longer built-in, need to install Office preview plugin from "Add Plugins" popup; without it, these files fall back to download button or code viewer
  • Browser sandbox has no login state + some sites reject embedding: Pages requiring login should be completed in browser; sites rejecting embedding show "Open in browser" in sidebar
  • HTML preview only shows saved files: Unsaved editor changes don't reflect in preview
  • No bottom panel on mobile: When width <768px, bottom panel unavailable, tabs merge into right bar once; when returning to wide screen, these tabs don't automatically return to right bar (already documented in README, README_EN.md:226)
  • node-pty loading failure has been downgraded (issue #140): Terminal tab shows fix banner, agent terminal tools automatically skipped, other plugin features unaffected
  • Dual mount results in two sidebars: When enabling npm bundle + manual patch (or npm bundle + plugin-registry simultaneously), must keep one path; see "FAQ" above for details
  • Handling transparent/glassmorphism skins (issue #90): Terminal and editor panels actively fall back to opaque background to avoid text overlapping skin painting during scroll; non-panel surfaces still follow theme
← Back to plugin directory