Foreword

When running long tasks with DSH, a common pain point is missing important events when you’re away from the screen—like task completion, agent approval requests, or questions asked via ask_user_question.

dsh-speak addresses this by vocalizing the final replies, approval requests, and questions from a DSH session through system text-to-speech. Below, we cover its positioning, core features, installation methods, and practical usage notes.

What is This

dsh-speak is a DSH web plugin maintained by Alan2Z, licensed under MIT.

Its primary goal is to make the AI coding harness “speak”:

  • Uses SAPI5 speech synthesis on Windows.
  • Uses the system say command on macOS.
  • Supports DSH and other AI coding harnesses that can tap into the harness event stream.

The project documentation states directly: its purpose is to provide a validated voice reporting solution for the harness; unless unexpected issues arise, it will not be actively updated further.

Core Features

Vocalizing Final Replies

The DSH web plugin listens to the session event stream and vocalizes the final reply.

It skips intermediate narrations during reasoning and tool-call processes and consolidates multi-step messages. Simply put, it doesn’t read out every step but focuses on delivering the final response to the user.

Reminders for Approvals and Questions

dsh-speak vocalizes two types of user-critical events:

  1. Approval requests initiated by the agent.
  2. Questions posed by the agent via ask_user_question.

These are ideal for voice reminders as they typically indicate the task has paused and is awaiting user intervention.

Bundle Auto-Registration

Starting with version 1.3.0, bundle auto-registration is supported:

  • Declare the package in dsh.profile.bundles.
  • The plugin registers itself using its included cordis.patch.yml.
  • No manual addition of patch entries is required.

If bundle auto-registration is not used, you can manually add the plugin entry to the DSH profile’s cordis.patch.yml.

Best-Effort Operation

dsh-speak follows a best-effort strategy:

  • Does not throw exceptions.
  • Does not block the harness.
  • Does not disrupt the current session.

In other words, if voice reporting fails, it aims not to interfere with DSH’s main workflow.

Natural Voices

Natural voices are prioritized on Windows:

  • Windows 11: Uses built-in natural voice packages.
  • Windows 10: Natural voices can be registered via NaturalVoiceSAPIAdapter (e.g., Xiaoxiao).

On macOS, system speaking voices are used; on newer macOS versions, Siri natural voices may also be available.

If no natural voices are available on the system, it falls back to any installed voice.

Text Cleaning

Text-to-speech can be disrupted by Markdown, URLs, emojis, and other characters, sometimes failing silently.

dsh-speak cleans the text to be vocalized:

  • Removes Markdown.
  • Removes URLs.
  • Removes emojis.
  • Limits the adapter’s single utterance character count.

Portable Engine

It provides a standalone voice engine callable independently:

powershell -File speak.ps1 -Text "Hello"

./speak.sh -t "Hello"

Any process can invoke voice reporting this way, not necessarily dependent on DSH.

Installation and Enabling

Environment Requirements

  • Node.js >= 18.
  • Windows: Windows 10 or 11, PowerShell.
  • macOS: Uses built-in say, no additional software needed.
  • License: MIT.

Method 1: Install via npm

First, install to the web profile:

dsh plugin --profile web add dsh-speak

If pnpm is not installed on the machine, you can also install directly to the web profile using npm:

npm install --prefix "$env:USERPROFILE\.dsh\profiles\web" dsh-speak

On macOS:

npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak

Then register the plugin to DSH’s patch file. Edit:

~/.dsh/profiles/web/cordis.patch.yml

Append:

- insert:
    - id: speech-hook
      name: 'dsh-speak'

On Windows, restart the DSH web app.

On macOS, no restart is needed as the patch watcher hot-reloads.

Method 2: File Installation

If not installing via npm, you can use file installation on Windows:

git clone https://github.com/Alan2Z/dsh-speak.git
cd dsh-speak
powershell.exe -NoProfile -ExecutionPolicy Bypass -File adapters\dsh\install.ps1

After installation, restart the DSH web app.

Let the Agent Install for You

You can also provide the repository URL to the agent within DSH and have it install the plugin according to the README:

https://github.com/Alan2Z/dsh-speak

Since the installation process writes to ~/.dsh outside the workspace, approval for these out-of-workspace writes is required.

Typical Usage

Testing the Windows Voice Engine

After installation, you can directly test the PowerShell voice engine:

powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.dsh\hooks\speak.ps1" -Text "Hello, voice reporting is ready."

If the system reads this sentence, the Windows voice pipeline is operational.

Testing the macOS Voice Engine

On macOS, you can download and test the script directly:

curl -sfL -o ~/speak.sh "https://cdn.jsdelivr.net/gh/Alan2Z/dsh-speak@main/engine/speak.sh"
chmod +x ~/speak.sh
~/speak.sh -t "Hello, macOS voice reporting test"

If the system reads this sentence, the macOS say pipeline is operational.

Observing in DSH

After installation and enabling, the DSH web plugin listens to the session event stream.

When the agent provides a final reply, the plugin vocalizes it. When the agent requests approval or asks a question via ask_user_question, the plugin also provides a voice reminder.

Voice Configuration and Notes

Windows 10 and Windows 11

Windows 11’s natural voice packages are built-in and require no additional installation.

For Windows 10 to use natural voices:

  1. Install NaturalVoiceSAPIAdapter.
  2. Use its VoiceDownloader to download natural voice packages.
  3. Register voices via NaturalVoiceSAPIAdapter.

For example, you can register Xiaoxiao.

If no natural voices are available, dsh-speak falls back to a standard stock voice like Huihui.

macOS

On macOS, the built-in say command is used.

Two points to note:

  1. Siri voices and system speaking voices are separate settings.
  2. Siri voices are not exposed via say -v '?'.

Additionally, opening the Spoken Content / Siri Voice settings panel may reset the system voice to Tingting (婷婷), even if no changes are made. If the voice suddenly changes, you can reselect the system speaking voice.

Logs on macOS are located at:

$TMPDIR/dsh-speech-hook.log

Note this uses os.tmpdir(), not /tmp.

say has no volume flag; volume follows the system output volume.

Use Cases and Considerations

Suitable for the following scenarios:

  • Running long DSH tasks while away from the screen.
  • Needing quick reminders when the agent awaits approval.
  • Needing to know when the agent’s question halts the task.
  • Wanting to convert DSH’s final reply into voice to reduce screen-watching time.

Usage notes:

  • dsh-speak runs as a DSH web plugin, using the permissions of the current DSH host process.
  • Before installation, it’s advisable to review the GitHub source code, scripts, and MIT license.
  • If allowing the agent to install for you, approval for writes outside the workspace to ~/.dsh is required.
  • It is a best-effort component; its goal is not to affect DSH’s main workflow if voice reporting fails.

Conclusion

dsh-speak addresses a specific need: making DSH vocalize during final replies, approval requests, and ask_user_question interactions, reducing missed screen information. Its scope is limited, but the path is validated, making it suitable for those wanting to add a lightweight voice reminder to the harness.

GitHub Repository:

https://github.com/Alan2Z/dsh-speak

For the community directory page, refer to the actual listing page for the DSH plugin directory you use.