dsh-session-nav

Readme

# dsh-session-nav

[![dsh-plugin](https://img.shields.io/badge/topic-dsh--plugin-1f6feb)](https://github.com/topics/dsh-plugin)

English | [中文](README.zh.md)

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) **Web** plugin that adds a Codex-style session navigator on the left of the conversation.

![Session navigator: packed left-edge dashes, Worked-for duration, and a prompt bubble over the conversation](docs/screenshot.png)

It is an overlay only. It does not replace Chat, the sidebar, or the Trajectory tab.

## What you get

- **Idle:** a packed stack of short dashes on the left edge of the conversation column — one dash per user, steering, or slash-command turn.
- **Hover:** neighbouring dashes lengthen in a delayed wave, then a prompt bubble, an optional **Worked for** duration, and an optional **Edited N files +X −Y** card.
- **Jump:** click a dash (or use ↑ / ↓ on the rail) to scroll that turn into view.
- **Full log:** older turns are listed from `session.history` even if Chat has not loaded them yet. Clicking one pages `loadOlder` until the row exists, then scrolls to it.
- **Toggle:** a tick-mark button in the session header. Preference is stored as `dsh-session-nav:enabled` in `localStorage`.

The rail sits vertically centered, capped at 66% of the conversation column, and scrolls inside itself when the stack is long.

## Install

Wait until DSH is idle. Adding a plugin rebuilds the web profile and will interrupt a running task.

```sh
dsh plugin --profile web add github:karmiy/dsh-session-nav
```

Git-hosted plugins build on install. pnpm ≥10 blocks that `prepare` script until you allow it, so the first `add` fails with an `allowBuilds` hint. Copy the exact key into `~/.dsh/profiles/web/pnpm-workspace.yaml`:

```yaml
allowBuilds:
  dsh-session-nav: true
```

Then run the same `add` again and restart the web profile.

Pin a commit if you do not want a later push to change what runs:

```sh
dsh plugin --profile web add github:karmiy/dsh-session-nav#v0.1.0
```

Local checkout (after `pnpm install`):

```sh
dsh plugin --profile web add link:/absolute/path/to/dsh-session-nav
```

Find more community plugins under the [`dsh-plugin`](https://github.com/topics/dsh-plugin) topic.

## How it maps to the session

| UI | Source |
| --- | --- |
| One tick | A visible `user`, `steering`, `command`, or `manual-compaction` Chat Node in the loaded window, plus older human `user/message` events from `session.history` |
| Idle length | Short dash; hover applies a Gaussian envelope around the pointer |
| Scroll mark | Slightly brighter dash nearest the upper third of `[data-conversation-scroll]` — not expanded |
| Worked for / bubble / file card | Shown only while the pointer is on the rail |
| Worked for | `turn/start` … `turn/end` (live while the turn is open) |
| Bubble | Text of that user / steering / slash-command message |
| File card | Diff / edit tool cards in the turn (`locations` + `oldText` / `newText` line counts) |

## Development

Requires Node `^22.19 || >=24`. Keep a DeepSeek Harness checkout as a sibling if you want `pnpm typecheck` / `pnpm build` (they resolve host types through `../deepseek-harness`). Unit tests and `prepare` do not need it.

```text
../deepseek-harness
../dsh-session-nav
```

```sh
pnpm install
pnpm test
pnpm typecheck
pnpm build
```

`prepare` runs `tsdown` only — no typecheck — so `dsh plugin add github:…` can build on a machine that does not have the harness source.

Do not `dsh plugin add` against a profile that is currently running a task.

## License

MIT