DSH-better-sidebar

✨ Features

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@latest

Then hard-refresh the browser (Cmd/Ctrl+Shift+R). Requires DSH 0.2.1-rc.1+.

Compatibility warning — match the plugin to the host line. As of 2026-10-26, DSH's npm latest is 0.2.1-rc.2, so the command above installs the compatible v0.28.2. Hosts still on 0.2.0-rc.2 must pin dsh-better-sidebar@0.26.1 (and should upgrade the host to 0.2.1-rc.2 first); DSH 0.2.1-alpha.5 users must pin dsh-better-sidebar@0.28.0-alpha.0. The marketplace installer picks the plugin's latest regardless of host version, so an old host gets a version-rejection error — upgrade the host or pin the version explicitly. The two packages' latest tags are independent.

Always pin exact versions for older releases (latest moves forward with each new stable). Replace web with your own profile name.

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.1-rc.1 or newer, then run dsh plugin --profile web add dsh-better-sidebar@0.28.2
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.28.2 (macOS / Linux / Windows Git Bash; ./scripts/install.ps1 -Version 0.28.2 for native Windows). It handles installation + bundle registration.

Updating: just re-run the install command, then hard-refresh the browser.

🆕 Recent Updates

v0.28.2 — large-session cold-read fix

• Root cause fixed: a detached session's cwd no longer decodes the whole session log — it reads the workspace address stored in the header (first zstd frame only, header-only), memoized per session with in-flight sharing; activeWorktreeRootOf no longer folds the stored log for a detached session
• Why 0.28.1 missed it: the single-flight only covered /sidebar/api, while the real startup fan-out is one fs-watch frame per watched directory and one cwd resolution per /sidebar/file|html resource — a 39 MB session was still fully decoded dozens of times in parallel
• Behavior: an attached session still follows working_directory and linked worktrees; before attach the sidebar roots at the original project and the next 5 s poll switches back
• Measured (40.2 MB session, local): 12 routes + 36 bypass-entry calls concurrently → 1 header read, 0 full reads, 3 ms, +0.3 MB RSS; pre-fix, 6 bypass calls were 6 full reads with a +1.0 GB peak (≈6 GB extrapolated for 36)

v0.28.1 — UX and reliability patch

• OOM fix: cold cwd reads shared by the twelve /sidebar/* routes are merged per session and client hint, so a session-switch burst no longer decodes the same large session log N times in parallel
• Silent wrong-file writes are gone: tab reconciliation now covers tabs in background sessions, and worktree sessions use one address base — a renamed/deleted file is no longer re-created on the next save, and a chat link never opens a same-named file from another checkout
• Host crash guard: pathological git status output is capped with a latch and a process-tree kill, turning "host dies with RangeError" into one failed SCM refresh
• Git page: histories with more than 1,000 branches load again; tags now decorate commits, rows and details, and tag changes invalidate pagination
• Editor: saving after an mtime-only change no longer deadlocks on fs-conflict; the reading position survives tab re-seating; “Add to conversation” lands as a compact reference chip and never flattens earlier chips
• Markdown links: local destinations normalize Windows backslashes, so C:\ws\_analysis\report.md opens instead of a bare ENOENT
• Sidebar: the bottom-workbench toggle stays visible while the right panel is open; the macOS dock fallback avoids the traffic lights; a content-stable tab scope ends needless full-file re-reads; closing a side-chat tab archives its session

v0.28.0 — stable plugin release for DSH 0.2.1-rc.1+

• Move all 13 DSH peer floors to ^0.2.1-rc.1; retain the alpha.0 functionality without runtime changes
• The upstream alpha.5 → rc.1 full-tree diff contains 355 files, all package.json; no source changes
• DSH 0.2.0-rc.2 hosts stay on plugin v0.26.1; DSH 0.2.1-alpha.5 hosts stay on v0.28.0-alpha.0
• Validation: RC adaptation record

🔌 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} />,
  }))
}

📑 Tab plugins (sidebar pages)

🖼️ Viewer plugins (file viewers)

🧰 Enhancements & tools

📣 List your plugin: tag your repo with the dsh-better-sidebar topic to appear on the topic page; then PR a PluginEntry into src/client/plugins-tabs.ts / plugins-viewers.ts to join the in-app recommended catalog.

• Routes sit behind a Host-header trust fence (same as /api); fs.write is 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; 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

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:mount

Architecture: 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; run pnpm typecheck && pnpm build && pnpm test (or make check) before submitting
• List an ecosystem plugin: tag your repo with dsh-better-sidebar + PR an entry into src/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-plugin topic, 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