Introduction

In DSH’s plugin ecosystem, download progress previously relied on a floating window in the bottom-right corner. This approach could obscure session content, required manual dragging to avoid, and was disconnected from DSH’s own sidebar system. dsh-sidebar-downloads is an add-on plugin for dsh-better-sidebar. It integrates aria2 download progress into the sidebar as a first-class page, placed alongside pages such as the file explorer and terminal, and managed uniformly by the DSH base.

What This Is

This is a plugin that displays aria2 download progress in the sidebar. It is the sidebar view for the aria2 download channel: it reads the task ledger written by aria2-dl.js (~/.dsh/downloads/tasks/*.json) and queries aria2 RPC for records with gid to correct the information. It does not reimplement the downloader; it only renders the real state as a sidebar page. It works together with dsh-download-guard: the guard is responsible for intercepting non-aria2 paths, while this plugin is responsible for displaying path status.

Core Features

  • Real-time progress: progress bar + percentage, color-coded by status (in progress / completed / failed / canceled).
  • Speed and remaining time: MB/s and ETA, displayed only while a task is in progress.
  • Downloads with unknown size: displays a pulse bar when the server does not return Content-Length, instead of fabricating a percentage.
  • History: completed / failed tasks remain in the list; you can switch to “show in-progress only.”
  • Byte counts use actual disk values: tasks without size information use the actual file size on disk; even if the process is killed, wrong numbers are not shown.
  • aria2 real-time correction: tasks with gid are queried directly via aria2 RPC; stale records enqueued with --no-wait can also display real progress and speed.
  • Paused state: manually paused tasks display “Paused · percentage” and are distinguished in amber color, counted as “N paused” rather than “in progress.”
  • Show in folder: locate downloaded files in the file explorer with one click.
  • Persistent operation feedback: failure / notice messages are anchored to a bottom overlay of the panel and are not scrolled away with the list.
  • Automatic cleanup of invalid records: clicking an invalid record automatically removes it and explains the reason.
  • Explicit prompt when the ledger is missing: if the download record directory does not exist, it displays “File missing” and the specific path.
  • Remove record: deletes only the ledger record; downloaded files are preserved.
  • Expand details: click any task row to expand: output path, source URL, elapsed time, and error message.

Installation and Enablement

Prerequisite: dsh-better-sidebar is already installed (>=0.19.0).

cd ~/.dsh && dsh plugin --profile <your-profile> add dsh-better-sidebar && dsh plugin --profile <your-profile> add "dsh-sidebar-downloads@github:BeiWay1145/dsh-sidebar-downloads"

After installation, restart DSH, then click the + menu in the sidebar and select “Downloads.” The build artifacts have already been committed to the repository, so local compilation is not required.

Data Sources and Configuration

This plugin reads the task ledger files ~/.dsh/downloads/tasks/<taskId>.json (one JSON file per download task). It does not fetch from the network and does not write files. The ledger now has only one writer—aria2-dl.cjs (distributed with the dsh-download-guard package).

The panel and aria2-dl.cjs use the same environment variables and default values; both sides must point to the same engine:

Variable Default Description
ARIA2_RPC_URL — Full URL; if set, takes precedence over the two variables below
ARIA2_RPC_HOST 127.0.0.1 Engine host
ARIA2_RPC_PORT 16800 Engine port (works out of the box with Motrix Next)
ARIA2_RPC_TIMEOUT_MS 1500 Status query timeout

If your aria2 uses another port (for example, the common 6800), just change this variable. When the engine is unreachable, the panel shows a persistent notice (including the attempted address and the variable name to change) instead of silently letting the progress stop.

Notes

  • The plugin runs with the permissions of the current DSH process; you should review the source code and license before installing.
  • Removing a record only deletes the ledger record; it does not delete downloaded files.
  • When the engine is unreachable, it automatically degrades to rendering from the ledger and does not raise an error.

Conclusion

dsh-sidebar-downloads frees download status from the bottom-right floating window and manages it uniformly through the sidebar. It solves specific issues such as preserving download history, displaying downloads with unknown size, and real-time RPC correction. Together with dsh-download-guard, it forms a complete download closed loop.

  • Source repository: https://github.com/BeiWay1145/dsh-sidebar-downloads
  • Ecosystem directory: https://www.skillhub.cn/plugins/BeiWay1145/dsh-sidebar-downloads