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 four full-page backgrounds and matching WebUI themes. | | tui | A desktop Live2D companion 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)
• A modern desktop browser for Web skins
• A graphical desktop session for the Live2D companion
• Internet access for the first Electron download and optional 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.

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

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. | | 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.

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 Live2D bubble and read that confirmation aloud with the newly selected character and voice. 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 Live2D 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 | I'm working on your task. | | Waiting for confirmation | I need your confirmation to continue. | | Completed | I've completed your task. | | Failed | 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. Use Show Waifu to open it again.

Desktop controls

• Drag the companion with the primary mouse button.
• Use the mouse wheel or trackpad to zoom.
• Double-click the companion to restore automatic sizing.

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.

/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.