dsh-turnbar
English | 简体中文
A progress bar for your agent conversations.
Long agent sessions are productive — until you need to find that one requirement
you mentioned 80 turns ago. Native scrollbars make you guess and re-scroll.
dsh-turnbar gives your DeepSeek Harness chat a video-style progress bar: hover to
preview any turn, drag to scrub, click to jump, Esc to come back.
hover preview
scrub, hover cards, and ⌘K search landing on the bar
Install
Three ways, pick one:
① Plugin market (easiest): open dshmarket
inside dsh, search "turnbar", one click (listing pending; until it lands, use the options below).
② Command line: open your macOS Terminal app and paste:
dsh plugin --profile web add dsh-turnbar
This runs in the Terminal app, not in the dsh chat box. If your terminal doesn't
know the dsh command (dsh --version says command not found — you never installed
dsh globally, e.g. you use a desktop build or let your AI launch it), install it first:
npm install -g @deepseek-ai/dsh
③ Ask your AI: just tell your agent "install dsh-turnbar for me" — it runs the
same command on your machine, exactly how you've been installing your other plugins.
Restart dsh afterwards. Zero config; historical sessions are backfilled automatically
and the bar always shows the whole conversation.
jump to a turn
Features
- 🎚 Full-map progress bar — every turn is a segment; the playhead highlights
the segment you're reading. 150+ turns aggregate into ≤40 groups so the bar
never becomes a mess.
- 🖼 Hover preview cards — see who said what before you jump: the turn's
first lines, tool-call count, file edits, token usage, and steering messages.
Terminated empty turns are dimmed and labeled 「该轮已终止，无对话内容」instead
of pretending to have content.
- 🔎 In-conversation search — the magnifier button at the bar's right edge or
⌘K opens it. Search everything the agent said or you said, across the whole
session (including history beyond what's loaded); results show a count, arrow
keys scroll the highlight into view, Enter lands the pick on the bar. Results
are also drawn on the bar itself — matching turns glow amber, so a query like
"TypeScript" shows you at a glance where in the conversation it lives (v0.3).
- ⛽ Context fuel gauge — hover any turn to see the context window occupancy
at that moment ("上下文 62% · 余 38k"), with color escalation at 80%/95%.
When the latest turn passes those thresholds, the bar's tail edge glows amber,
then red — you notice the tank is nearly empty without even hovering (
v0.3).
- 📑 Chapter ticks —
/goal rounds are marked as thin ticks on the bar, so a
long session gets visible "milestones" without any manual bookkeeping (v0.3).
- 🧭 Trajectory view jump —
⌘/Alt + click a segment opens the official
Trajectory view and scrolls to that turn's row, centered and highlighted.
Falls back to a normal in-chat jump when trajectory is unavailable (v0.3).
- ⤴ Click / drag to jump — click a segment to land in ≤300 ms;
press and drag to scrub through turns like a video timeline.
Jumps across unloaded history page it in automatically.
- ⌨️
⌘↑ / ⌘↓ — hop one turn at a time from where you're reading; empty
turns are skipped automatically.
- ↩ Esc to return — after any jump,
Esc (or the toast) takes you back to
exactly where you were.
- 🧩 Graceful degradation — if your dsh version changes APIs, dsh-turnbar
hides itself instead of breaking your session.
Why yet another navigation plugin?
Nine navigation plugins appeared in dsh's first four days — all of them are
rails, drawers, or dot chains: a list of user messages you click through.
dsh-turnbar is the only one shaped like a video player:
| dsh-turnbar | dsh-navbar | dsh-chat-timeline | dsh-message-navigator | dsh-conversation-outline | dsh-codex-timeline | dsh-outline | dsh-chat-outline | dsh-message-preview | dsh-turn-marks |
|---|
| Form | full-map bar, always visible | sliding dot window | official-rail clone (right rail) | outline drawer | sidebar outline tab | left rail (Codex-style) | outline overlay | left sidebar outline | right-edge navigator | left-turn strip |
| Whole-conversation map (beyond loaded window) | ✅ event log | ❌ | ❌ | ❌ | ❌ | ⚠️ auto-loads history | ❌ | ⚠️ full mode on demand | ❌ | ❌ |
| Drag scrub | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Rich hover meta (tools/files/tokens) | ✅ | ❌ | ❌ | ❌ | ❌ | ⚠️ latency/tok-s only | ❌ | ❌ | ✅ preview | ✅ preview |
| Context fuel gauge (window occupancy) | ✅ from usage events | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Search (whole conversation incl. assistant) | ✅ + results on the bar | ❌ | ❌ | user msgs only | ❌ | ⚠️ local browser-only | ⚠️ headings/keywords | ⚠️ keyword filter | ❌ | ❌ |
Chapter ticks (/goal milestones) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ⚠️ markdown headings | ❌ | ❌ | ❌ |
| Trajectory view jump | ✅ ⌘/Alt+click | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ Ctrl/Shift click | ❌ | ❌ |
Esc return | ✅ | ❌ |
All of them are MIT and genuinely useful — dsh-turnbar just goes further on the
feel: it's a video player, not a list. See also
Companions below.
Companions
- dsh-rewind — roll the conversation
back to an earlier turn (jump over, then rewind).
- dsh-turn-fold — collapse
tool-call storms; its per-turn stats pair well with our preview cards.
Acknowledgements
Built on paths others paved first — with gratitude:
- @vlln's dsh-navbar —
the hover-preview / click-to-jump DOM patterns and the wheel+scrollTop jump recipe;
- @YesSanSan's dsh-conversation-outline —
the host↔client same-origin JSON bridge pattern and its invaluable
PLUGIN_DEV_NOTES.md;
- the DeepSeek Harness team — official slots, session event streams, and
persistence APIs that let this plugin take the paved road end to end, zero patches.
Compatibility
Tested against dsh 0.1.5-rc.1 (web profile, handle-based persistence
open/read/close) and 0.1.0-rc.7 (one-step inspect/readRaw persistence).
Both persistence generations are auto-detected at runtime, so history backfill
works on either. Works with the official web UI's conversation.composer.dock
slot; no patches, no UI hacks — which is the point: upgrading dsh does not
require uninstalling dsh-turnbar first. The one plugin that does require that
dance is
dsh-codex-timeline: it pins an
exact dsh commit by replacing the official conversation adapter, so the upgrade
checklist says "uninstall before upgrading". Different trade-off, stated plainly.
Coexists with other plugins that share the same composer.dock slot —
dsh-web-ui-all and its
included dsh-live-stats / dsh-aionui-panel. A built-in co-existence CSS layer
(v0.2.2+) forces the dock into a wrapping row so the TurnBar always owns its own
full-width line while the official StatsLine sits beside any third-party entries,
so the bar is never squeezed sideways. Single-turn sessions now show a one-segment
progress bar too (only brand-new 0-turn sessions stay hidden).
| dsh version | status |
|---|
| 0.1.5+ (web, handle-based persistence) | ✅ full features |
| 0.1.0-rc.5 – 0.1.1-rc.x (web, inspect/readRaw) | ✅ full features (legacy chain) |
| older / non-web profiles | plugin stays inert; nothing breaks |
Roadmap
- Next: task-boundary chapters (beyond
/goal), bookmarks, trajectory ↔ chat
round-trip polish.
Development
pnpm install
pnpm test # vitest (fold logic, card model, host-half degradation)
pnpm build # tsdown: lib/index.mjs (node half) + lib/client.js (web half)
Architecture: a dual-half plugin — the node half folds the session/event
firehose into per-turn records (persisted sidecar), serves them over
/plugins/dsh-turnbar/state; the web half renders the bar into the official
composer dock slot. All dsh API contact is confined to src/platform/dsh/.
License
MIT — same as dsh.
