# DSH-better-sidebar

> 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.

## Metadata

- Author: [@omdsh-dev](https://github.com/omdsh-dev)
- Repo: <https://github.com/omdsh-dev/DSH-better-sidebar.git>
- GitHub: [omdsh-dev/DSH-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)
- Stars: 1,928
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `deepseek`, `deepseek-harness`, `dsh`, `dsh-better-sidebar`, `dsh-plugin`, `sidebar`
- Forks: 126
- Open Issues: 89
- Last push: 2026-08-17T16:45:30.000Z
- Added: 2026-08-14T00:00:00.000Z

## Install

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

## Wiki

## 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

| Dependency | Min Version | Notes |
|---|---|---|
| DeepSeek Harness (DSH) | `0.1.0-rc.6` | All `@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 | `>=20` | Declared in `engines.node` field (`package.json:39-41`) |
| Platform | macOS / Windows / Linux | macOS 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 Module | `node-pty ^1.0` | Only terminal feature depends on it; when missing, other plugin capabilities remain usable (lazy loading + fallback introduced in 0.12.3, see issue #140) |
| Package Manager | pnpm `>=10` | pnpm 11 blocks build scripts by default; first install needs `pnpm approve-builds --all` in `~/.dsh/profiles/web` to allow `node-pty` |

## Installation

```bash
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)

| Config | Type | Description | Default |
|---|---|---|---|
| `readLimit` | number | Byte limit for single file text reading (exceeds = marked truncated) | `524288` (512 KB) |
| `mediaLimit` | number | Max bytes for image/PDF/HTML preview | `20971520` (20 MB) |
| `listLimit` | number | Max entries per directory level in file tree | `1000` |
| `terminalsPerSession` | number | Max concurrent UI terminals per session | `3` |
| `reconnectGraceMs` | number | Grace period (ms) to keep shell process alive after terminal WebSocket disconnects, for seamless reconnect after refresh/tab switch | `30000` |
| `shell` | string | Shell 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)

| Preference | Type | Description | Default |
|---|---|---|---|
| `openByDefault` | boolean | Whether to expand sidebar by default for new sessions | `false` |
| `defaultWidthPercent` | number (20–60) | Sidebar width as percentage of window | `35` |
| `autoOpenSubagent` | boolean | Whether to auto-expand sidebar and jump to sub-agent page when session spawns a sub-agent | `true` |
| `autoOpenJobs` | boolean | Whether to auto-expand sidebar and jump to jobs page when new background tasks appear | `true` |
| `agentTerminalTools` | boolean | Whether to inject model with `terminal_create/list/send/read/wait_for/resize/signal/close` tools; when off, existing agent terminals are released together | `false` |
| `bottomPanelAutoTerminal` | boolean | Whether to also open a terminal tab when bottom panel is first expanded in current session | `true` |
| `terminalFontFamily` | string | Terminal font stack, empty follows theme (`--ds-font-family-code`) | `""` |
| `terminalFontSize` | number (9–32) | Terminal font size (px) | `13` |
| `interceptOpenPath` | boolean | Whether 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` |
| `editorExplorer` | boolean | Whether editor uses merged mode (top path input + dockable tree panel); when off, reverts to old standalone editor | `true` |
| `titleBarCompat` | boolean | Compatibility mode for reserving native title bar space at top (only needed for Windows frameless window) | `false` |
| `titleBarStripPx` | number (0–120) | Height reserved for above compatibility mode | `40` |
| `htmlViewerNoSandbox` | boolean | Whether to disable sandbox for HTML preview (not recommended, only for fully trusted local content) | `false` |
| `htmlViewerDefaultUnsafe` | boolean | Whether HTML preview defaults to non-sandboxed state (each page can restore sandbox via top status bar) | `false` |
| `browserNoSandbox` | boolean | Whether to disable sandbox for browser tabs (not recommended, only for fully trusted sites) | `false` |
| `browserInterceptLinks` | boolean | Whether to intercept external link clicks in GUI to sidebar (master switch) | `true` |
| `browserInterceptHttp` | boolean | Whether HTTP external links are intercepted to sidebar by default | `true` |
| `browserInterceptHttps` | boolean | Whether HTTPS external links are intercepted to sidebar by default (most HTTPS sites reject iframe, default off) | `false` |
| `tabsEnabled` | object | Per-tab-id disable (e.g., `{"editor": false}`), missing = enabled | `{}` |
| `viewersEnabled` | object | Per-file-viewer-id disable (e.g., `{"code": false}`), missing = enabled | `{}` |
| `pluginSettings` | object | Settings 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

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [DSH-better-sidebar](https://deepseek-plugin.org/plugins/omdsh-dev/DSH-better-sidebar)
Wiki generated by AI (model: `MiniMax-M2.5`)