Introduction

When handling long tasks in dsh web, the message stream keeps scrolling, but sometimes you just want to quickly confirm which stage the current session is in: queueing, waiting for confirmation, thinking, calling tools, writing an answer, or encountering an error. falser101/dsh-mascot is a plugin for DeepSeek Harness (DSH) Web: a draggable cartoon cat or dog that stays on the interface, switching expressions and text based on the current session state. It is a pure frontend projection and does not send session events.

What is this

falser101/dsh-mascot is maintained by falser101 and is licensed under MIT. It solves the lightweight status indication problem in dsh web: using a floating pet to display the session stage, providing an entry point for parallel task jumping, and retaining common operations like changing appearance, hiding, and opening settings.

GitHub:

https://github.com/falser101/dsh-mascot

Core Features

Session State

The pet switches expressions and text following the current session state, covering states such as queueing, waiting for confirmation, thinking, calling tools, writing an answer, completing, error, and greeting. It only performs a frontend projection and does not send events to the session.

Drag and Collapse

The pet supports drag-and-drop movement; it stops at the drop position when released. When the window is resized, it is clamped back within the screen. When the focus is on the chat input box and the pet is idle, it collapses into a small avatar; it expands again after sending.

Status Bubble

The status bubble displays accompanying text. Tool names are turned off by default but can be enabled on hover or in settings. While idle, it can automatically pop up at three frequencies: quiet, standard, and lively. On hover, it switches to softer phrases.

AI Theater

AI Theater is turned off by default. When enabled, it occasionally calls the current default model to write witty remarks; if there is no key or it fails, it falls back to built-in sentences. Keeping high-reasoning models open is a bit wasteful, so it is not used by default.

Parallel Task Hints

When multiple sessions or sub-agents are running in parallel, a number is displayed in the top-right corner. Hovering over it allows you to view the busy object, and clicking jumps to it.

Appearance and Interaction

Clicking the pet makes it speak; double-clicking collapses it into a small avatar. Hovering opens buttons for changing the pet, jumping to the current task, hiding, and opening settings. The settings have a master switch for “Show Floating Pet,” and you can also right-click to hide it. The text follows the interface language (Chinese/English); if the system is set to reduce motion, the animations stop.

Installation and Enablement

First, confirm that the local machine can already run:

dsh --profile web

The README requires @deepseek-ai/dsh-client-* version no lower than 0.1.0-rc.5. The package.json declared peerDependencies include @deepseek-ai/cordis >=4.0.0, react >=18.2.0, and multiple @deepseek-ai/dsh-client-* packages >=0.1.0-rc.5.

Install to web profile:

dsh plugin --profile web add @falser101/mascot

Then restart the Web process and open the page:

dsh --profile web

After installation, the pet will appear in the bottom-right corner, and a separate “Floating Companion” page will appear in the settings.

If there is no npm environment, you can also install via the GitHub repository:

dsh plugin --profile web add github:falser101/dsh-mascot

If you want to debug the local source code, link the repository to the profile:

dsh plugin --profile web add /path/to/dsh-mascot

The lib/ in the repository is committed along with the repository; no need to rebuild for git/npm installation.

Uninstall:

dsh plugin --profile web remove @falser101/mascot

Typical Usage

  1. Switch Appearance

Go to Settings → Floating Companion, select the target appearance. The selection is remembered locally.

  1. View Tool Names

Tool names are turned off by default. They can be enabled on hover or in settings.

  1. Use Parallel Hints

When multiple sessions or sub-agents run simultaneously, check the number in the top-right corner of the pet, hover to confirm the busy object, and then click to jump.

  1. Development Build

The repository provides the following commands:

pnpm build
pnpm watch
pnpm test
  1. Change Character Art

Overwrite the same-name jpg in docs/<species>/, then run:

node scripts/build-art-assets.mjs

Then rebuild.

Applicable Scenarios and Notes

Suitable for developers already using DSH Web who want to use lightweight animations to determine session stages, need entry points for parallel task jumping, or are willing to customize the pet’s appearance.

Notes:

  • The plugin is a pure frontend projection and does not send session events.
  • AI Theater is turned off by default; when enabled, it calls the current default model, falling back to built-in sentences if there is no key or if it fails.
  • The plugin runs with the current dsh process permissions; you should check the source code and license before installing.
  • Text follows the interface language, and animations stop when the system’s “reduce motion” setting is enabled.
  • The license is MIT.

Conclusion

The value of falser101/dsh-mascot lies in mapping the session states of DSH Web into a draggable, collapsible, and interactive floating companion. It does not replace the task panel, but makes states like queueing, thinking, tool calling, writing answers, completion, and errors more intuitive and facilitates quick jumping between parallel sessions.

Directory Page:

@falser101/mascot

GitHub:

https://github.com/falser101/dsh-mascot