Waifu Companion and Web Skins for DeepSeek Harness

@thewaifu/dsh-waifu adds two optional experiences to DeepSeek Harness:

Harness profile	What you get
web	A Skin Center with six full-page backgrounds plus the desktop Live2D companion while the Web host runs.
tui	The dsh-waifu desktop character with task reactions, speech bubbles, voice playback, and a /waifu menu.

Install the package in the profile you use. Installing it in web does not automatically enable it in tui, and installing it in tui does not change the WebUI.

Requirements

• Node.js ^22.19.0 or >=24.0.0
• DeepSeek Harness (dsh) 0.1.x from 0.1.0-rc.6
• A modern desktop browser for Web skins
• A graphical desktop session for dsh-waifu
• Internet access for the first Electron download, the first use of an optional character, and the speech service

You can run Harness directly from npm throughout this guide. If dsh is already installed globally, replace npx @deepseek-ai/dsh with dsh in any command.

Waifu 1.5.19 supports Harness 0.1.x from 0.1.0-rc.6, including the 0.1.1 release candidates and 0.1.2-rc.1. Its Web client follows the locale, settings, and theme services supplied by each Harness version, so it works with both the legacy client runtime and the split client renderer architecture. When using Harness 0.1.2-rc.1 in a terminal, the installed TUI must support the user-questions/request answerer event used by that Harness version.

Use Web Skins

Install and start

Add Waifu to the Web profile:

npx @deepseek-ai/dsh plugin --profile web add @thewaifu/dsh-waifu

Start the WebUI:

npx @deepseek-ai/dsh web

The desktop companion is owned by this dsh web Host process. Stopping the Web host with Ctrl+C, closing its terminal, or otherwise ending the Host closes the companion too; the Electron process also exits when its parent stdin closes unexpectedly.

Open the address printed in the terminal. Go to Settings -> Skin Center, directly below Agent presets, and select a skin.

Skin	Appearance
Ani	Light theme with ice blue, navy, and cyan.
Valentine	Light theme with pearl silver, cool gray, and emerald.
Mika	Dark theme with midnight blue, steel blue, and champagne gold.
Mika Business	Dark theme with black surfaces, white text, and cool blue accents.
Black Gold	Dark theme with black glass surfaces, warm ivory text, and gold accents.
YaDianNa	Dark theme with violet, lavender, and magenta.

Selecting a skin changes the full-page background and the matching colors used by the sidebar, conversation, input, menus, overlays, context rows, reasoning, timestamps, and statistics. The selected skin is saved in this browser and restored after a page reload. Restoration waits for Harness to finish loading its built-in appearance preference, so a delayed Light, Dark, or System sync cannot overwrite the selected Waifu skin.

To remove the character background, open the standard appearance settings and choose Light, Dark, or System.

Update the Web skins

Stop the running Web server, then run:

npx @deepseek-ai/dsh plugin --profile web update @thewaifu/dsh-waifu
npx @deepseek-ai/dsh web

Refresh the browser after the server restarts. Use a hard refresh if the page still shows an older design.

Remove the Web skins

Stop the Web server, then run:

npx @deepseek-ai/dsh plugin --profile web remove @thewaifu/dsh-waifu
npx @deepseek-ai/dsh web

Use the Desktop Companion

Install and start

Add the terminal UI and Waifu to the same TUI profile:

npx @deepseek-ai/dsh plugin --profile tui add @tomowang/dsh-tui
npx @deepseek-ai/dsh plugin --profile tui add @thewaifu/dsh-waifu

Start the TUI:

npx @deepseek-ai/dsh --profile tui

The companion starts automatically. To resume an existing Harness session:

npx @deepseek-ai/dsh --profile tui --resume <session-id>

First Electron startup

The desktop companion needs Electron. The first TUI start may download the Electron binary for your operating system. The terminal remains responsive and shows download percentage, downloaded bytes, verification, and extraction progress. Later starts reuse the Electron cache and normally do not download it again.

For a slow connection, use the Electron mirror:

ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npx @deepseek-ai/dsh --profile tui

If you stop the first download, run the same start command again to retry.

Character downloads and cache

Version 1.5.19 keeps Ani in the npm package so dsh-waifu can start without a model download. Valentine, Mika, and YaDianNa are downloaded from https://file.thewaifu.ai/live2d/ only when selected for the first time. The terminal shows download progress, and the plugin verifies both the exact byte count and SHA-256 before loading an archive. During the first download, the terminal shows a fixed-width progress bar headed by 人物加载中，请稍后.

Verified encrypted archives are stored outside node_modules in the operating system's user cache:

Platform	Default cache directory
macOS	~/Library/Caches/dsh-waifu/models
Linux	${XDG_CACHE_HOME:-~/.cache}/dsh-waifu/models
Windows	%LOCALAPPDATA%\\dsh-waifu\\Cache\\models

Switching back to a character in the same process reuses the already loaded model. Starting Harness again revalidates and reads the encrypted disk cache, so the archive is not downloaded a second time. A damaged or incomplete cache entry is deleted and downloaded again. Set DSH_WAIFU_MODEL_CACHE_ROOT or the plugin's modelCacheRoot config to use a different cache directory.

R2 credentials are never shipped to clients. Downloads use the public HTTPS domain and require neither an R2 key nor a separate backend service. If the network is unavailable, Ani remains usable; selecting an uncached optional character reports the download error without replacing the current character.

Use /waifu

Type the following command in the Harness prompt, then press Enter:

/waifu

Type /waifu by itself and press Enter. Waifu 1.5.6 includes a compatibility fallback for TUI 0.6.0: it consumes this exact command before any model request, then opens the same interactive menu. Newer TUI versions use the normal Harness command registry instead.

The menu provides these actions:

Action	What it does
Show Waifu	Shows or restarts the desktop companion.
Hide Waifu	Hides the companion without ending the Harness session.
Switch character	Selects Ani, Valentine, Mika, or YaDianNa.
Switch voice	Chooses and saves a voice for the current character.
View current status	Shows the selected character, current voice, visibility, and speech status.
Connect speech service	Opens browser authorization for this computer.
Check speech connection	Completes pending setup or checks the current connection.

Switch voice reads the currently selected character and immediately shows only that character's available voices. It does not ask you to select a character again. To switch voices, type /waifu, press Enter, and choose Switch voice. Ani, Mika, and YaDianNa each support their own voice plus lulu; all three default to lulu:

Character	Default voice	Available voices
Ani	lulu	Ani, lulu
Mika	lulu	Mika, lulu
YaDianNa	lulu	YaDianNa, lulu
Valentine	Valentine	Valentine only

Voice choices are saved in the Harness settings for the current TUI profile and restored the next time that profile starts. Valentine always uses its one dedicated Valentine voice, so choosing Switch voice while Valentine is current shows its fixed assignment without opening a redundant voice menu. Successful character and voice selections also show an English confirmation in the dsh-waifu bubble and read that confirmation aloud with the newly selected character and voice. Every bubble and spoken line starts with the Master, address. The menu returns immediately while audio streams, so slow speech generation does not hold the terminal interaction open.

Waifu reads only the preset lifecycle cues aloud during task execution, plus the explicit selection confirmations described above. It uses the current character's selected voice. The same preset text appears in the dsh-waifu speech bubble; AI responses, reasoning, and tool-call content are never copied into the bubble or sent to TTS:

Status	Bubble and spoken text
Running	Master, I'm working on your task.
Waiting for confirmation	Master, I need your confirmation to continue.
Completed	Master, I've completed your task.
Failed	Master, I couldn't complete your task.

Selecting a voice does not connect the speech service by itself: use /waifu -> Connect speech service, approve this computer, and use Check speech connection to verify that audio is ready.

Use Hide Waifu when you want to close the companion while keeping Harness running. It hides the existing Electron window without discarding the selected character. Use Show Waifu to reveal the same window again.

Desktop controls

• The visible character opens about 19% smaller than the previous default. Its native transparent window reserves 1.35x zoom capacity around that smaller character; the reserved transparent pixels remain click-through.
• Drag the companion with the primary mouse button. When dragging begins, the native window releases unused zoom headroom while preserving the character's bottom-center screen position, so the character can reach the upper work area. This changes only the native window; the Pixi framebuffer stays fixed.
• Use the mouse wheel or trackpad to zoom. The Pixi framebuffer is allocated once before the character appears and is never rebuilt during a wheel gesture. Trackpad input is normalized, capped, and protected from short inertial direction reversals; queued input cannot run far ahead of the visible scale. The native window starts with 1.35x zoom capacity and grows only when that capacity is exceeded. It never contracts at the end of a wheel gesture, so repeated zooming cannot alternate native resize operations. Zoom is capped against the current display's available work area, with a safety margin on every edge, so even rapid scrolling keeps the complete character on screen. Extra transparent capacity remains click-through. Pointer hit testing never reads or captures the Live2D render surface. This avoids disturbing Cubism clipping masks while the character is moving or the pointer enters the window. Moving the pointer over the character therefore never hides masked model parts such as the face, hair, or clothing.
• Double-click the companion to restore automatic sizing.
• Click the compact close button at the character's upper-right corner to hide the companion. While a speech bubble is open, the button automatically moves clear of the bubble with an 8px gap. Use /waifu -> Show Waifu to reveal it again.
• Transparent window areas and the speech bubble pass pointer input to the application underneath. The renderer tests the pointer against Cubism's currently visible drawable triangles, so transparent gaps inside the old rectangular character bound also pass through. Forwarded mouse movement and a cross-platform main-process cursor fallback switch the native window back to interactive only over those triangles or the close button. This CPU-side test does not read the WebGL framebuffer and therefore does not interrupt model animation or clipping masks. A speech bubble temporarily expands the window upward without widening its reserved character viewport. The fixed Pixi framebuffer remains unchanged and anchored at the bottom center while only the native surface grows, so showing or closing a bubble does not move the character on screen and never clears a character frame. The native window shadow is disabled, and the compact opaque bubble has no translucent outer shadow. Its position follows the tight bound of the visible drawable meshes with an 8px character gap, instead of the model file's often much taller logical bound. After it closes, the window returns to the reserved character viewport. Speech actions replace the current motion without exposing an intermediate reset-pose frame.

Set the plugin configuration option clickThroughTransparentAreas to false only when the legacy behavior, where the whole transparent window accepts pointer input, is required.

Connect speech

The TUI profile connects to https://tts.thewaifu.ai/ by default, including when dsh --profile tui is run from a local terminal. No local 3018 or 3020 service is required. The first connection may open a browser authorization page for this computer.

1. Keep DeepSeek Harness running.
2. Enter /waifu.
3. Choose Connect speech service.
4. Approve this computer in the browser.
5. Return to the terminal and wait for confirmation.

If confirmation does not appear, open /waifu and choose Check speech connection.

Update or remove the companion

Update Waifu:

npx @deepseek-ai/dsh plugin --profile tui update @thewaifu/dsh-waifu
npx @deepseek-ai/dsh --profile tui

Remove Waifu:

npx @deepseek-ai/dsh plugin --profile tui remove @thewaifu/dsh-waifu

Command Reference

Web profile

Task	Command
Install	npx @deepseek-ai/dsh plugin --profile web add @thewaifu/dsh-waifu
Start	npx @deepseek-ai/dsh web
List installed plugins	npx @deepseek-ai/dsh plugin --profile web list
Update	npx @deepseek-ai/dsh plugin --profile web update @thewaifu/dsh-waifu
Remove	npx @deepseek-ai/dsh plugin --profile web remove @thewaifu/dsh-waifu

TUI profile

Task	Command
Install the TUI	npx @deepseek-ai/dsh plugin --profile tui add @tomowang/dsh-tui
Install Waifu	npx @deepseek-ai/dsh plugin --profile tui add @thewaifu/dsh-waifu
Start	npx @deepseek-ai/dsh --profile tui
Resume a session	npx @deepseek-ai/dsh --profile tui --resume <session-id>
List installed plugins	npx @deepseek-ai/dsh plugin --profile tui list
Inspect the profile	npx @deepseek-ai/dsh --profile tui --dump-config
Update Waifu	npx @deepseek-ai/dsh plugin --profile tui update @thewaifu/dsh-waifu
Update the TUI	npx @deepseek-ai/dsh plugin --profile tui update @tomowang/dsh-tui
Remove Waifu	npx @deepseek-ai/dsh plugin --profile tui remove @thewaifu/dsh-waifu

Troubleshooting

Skin Center is missing

Check the Web profile:

npx @deepseek-ai/dsh plugin --profile web list

The list must contain @thewaifu/dsh-waifu. If it is only installed in the TUI profile, add it to the Web profile and restart the Web server:

npx @deepseek-ai/dsh plugin --profile web add @thewaifu/dsh-waifu
npx @deepseek-ai/dsh web

A skin or background does not change

1. Stop the old Web server.
2. Update the plugin.
3. Start the Web server again.
4. Hard-refresh the browser page.
5. Choose Light, Dark, or System once, then select the Waifu skin again.

npx @deepseek-ai/dsh plugin --profile web update @thewaifu/dsh-waifu
npx @deepseek-ai/dsh web

dsh --profile tui stays blank

Check that both packages are installed in the TUI profile:

npx @deepseek-ai/dsh plugin --profile tui list
npx @deepseek-ai/dsh --profile tui --dump-config

The plugin list must contain @tomowang/dsh-tui and @thewaifu/dsh-waifu. Repair the profile and start it again if either one is missing:

npx @deepseek-ai/dsh plugin --profile tui add @tomowang/dsh-tui
npx @deepseek-ai/dsh plugin --profile tui add @thewaifu/dsh-waifu
npx @deepseek-ai/dsh --profile tui

Electron downloads slowly

The Electron download is separate from the Waifu npm package download. Wait for the terminal progress bar to finish, or restart with the mirror:

ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npx @deepseek-ai/dsh --profile tui

An interrupted download can be retried. Once it succeeds, later starts use the cache.

A character model does not download

• Confirm https://file.thewaifu.ai/live2d/catalog-v1.json opens over HTTPS.
• Retry Switch character; interrupted .part files are discarded safely.
• Confirm the user can write to the cache directory listed above.
• If a cached archive is damaged, dsh-waifu deletes it and downloads the content-addressed archive again.
• Ani is bundled and remains available while the model host is offline.

/waifu is unavailable

Update both the TUI and Waifu packages, then restart Harness:

npx @deepseek-ai/dsh plugin --profile tui update @tomowang/dsh-tui
npx @deepseek-ai/dsh plugin --profile tui update @thewaifu/dsh-waifu
npx @deepseek-ai/dsh --profile tui

Waifu 1.5.6 supports the published TUI 0.6.0 through its pre-model compatibility fallback. Confirm that plugin --profile tui list shows @thewaifu/dsh-waifu 1.5.6 or newer, type /waifu by itself, and press Enter. Restart the TUI profile after updating. Newer TUI versions open the same menu through the normal Harness command registry.

The companion does not appear

• Enter /waifu and choose Show Waifu.
• Wait for Electron preparation to finish on the first start.
• Confirm that you are running Harness in a graphical desktop session.
• If connected through SSH, start Harness from the desktop where the companion should appear.
• Restart the TUI profile after checking the items above.

Browser authorization does not open

• Enter /waifu and choose Connect speech service again.
• Open the authorization address printed in the terminal if necessary.
• Keep Harness running until authorization finishes.
• Choose Check speech connection after approving the computer.

Speech is connected but no audio plays

• Enter /waifu and choose View current status.
• Check the system output volume and selected audio device.
• Confirm that the operating system allows the companion to play audio.
• Restart Harness and choose Check speech connection again.

License

Licensed under the Apache License 2.0.