Preface¶

In use cases for DeepSeek Harness (DSH), developers often work in Linux-like environments such as WSL, while the target system is macOS. Directly operating macOS system notifications, shortcuts, or the clipboard from the command line can be cumbersome. The dsh-mac-companion plugin solves this cross-system invocation problem. It acts as middleware, allowing DSH running in WSL to call a daemon on the Mac over HTTP and thereby access local Mac capabilities.

What is it¶

dsh-mac-companion is a DeepSeek Harness plugin designed to act as a client for the macOS Companion Daemon. It allows DSH to communicate with a daemon on the Mac using the HTTP protocol, enabling control over system notifications, shortcut execution, and clipboard reading and writing. This plugin is an optional companion component for dsh-wsl-kit and is not included in the standard installation script.

Core Features¶

The plugin provides the following core capabilities:
* mac_companion_status: Checks the health status of the Companion daemon via GET /v1/health.
* mac_notify: Sends a notification to the Mac system.
* mac_run_shortcut: Runs a shortcut on the Mac.
* mac_clipboard_read: Reads text content from the Mac clipboard.
* mac_clipboard_write: Writes text content to the Mac clipboard.

Installation and Enablement¶

In a WSL environment, first install the plugin with the plugin management command:

dsh plugin --profile web add github:173787247/dsh-mac-companion

After installation, start the Companion daemon on the Mac. Ensure Python 3 is installed on the Mac and run it in a terminal:

python3 companion/server.py --port 18765 --token 'your-secret'

Finally, configure environment variables in WSL to connect to the Mac:

export DSH_MAC_COMPANION_URL=http://<mac-ip>:18765
export DSH_MAC_COMPANION_TOKEN=your-secret

Typical Usage¶

After the above steps, DSH can call the features listed above. For example, in DSH configuration or scripts, trigger them by specifying the corresponding tool name:
* Check status: call mac_companion_status.
* Send notification: call mac_notify.
* Run shortcut: call mac_run_shortcut.
* Read/write clipboard: call mac_clipboard_read or mac_clipboard_write.

Applicable Scenarios and Notes¶

• Prerequisites: DSH version must be ≥ 0.1.2.
• Confirmation mechanism: When calling mac_run_shortcut and mac_clipboard_write, the parameter confirm=true must be set to trigger a system confirmation.
• Alternative: If it is only used for SSH CLI scenarios, using the dsh-remote-ssh plugin directly is recommended.
• Source: The plugin is hosted in a GitHub repository and follows the MIT license. Because it is not part of install.sh, it must be installed manually.

Summary¶

dsh-mac-companion provides a way to bridge macOS local capabilities through DSH. With simple HTTP configuration and daemon startup, developers can conveniently control Mac notifications, shortcuts, and the clipboard from WSL. Related code and documentation are available on GitHub.