Introduction

When running agents in DeepSeek Harness (DSH), they are usually run in the background. If an agent encounters a request requiring approval or an error in the background, it is easy to miss if you do not actively check the terminal. The dsh-caps-beacon plugin uses the Caps Lock indicator on a MacBook’s built-in keyboard to provide visual feedback, allowing you to monitor agent status from the keyboard even when away from the terminal.

What Is This

dsh-caps-beacon is a client plugin for DeepSeek Harness, maintained by the user xinyang920. It turns the Caps Lock LED into a status beacon, indicating the state of agents inside DSH through the LED’s on/off state and blinking frequency.

Core Features

The plugin mainly provides the following status indicators:

  • Solid on: The root agent is running (executing tools, calling models, retrying, etc.).
  • Blinking: User attention is required. This includes waiting for approval, waiting for an answer (ask_user_question), plan review, or being in an error/blocked state at the end of the previous turn.
  • Off: Idle state.

Mechanically, the plugin is a “pure observer”: it listens to DSH public host events (such as approval/request and tools/execute) and controls the LED through a C helper program. It does not perform keystroke injection and does not modify keyboard mappings.

Installation and Enablement

Installation requires three steps. Assume you are using the web profile; other profiles use similar steps.

  1. Add the plugin to the profile:
    dsh plugin --profile web add github:xinyang920/dsh-caps-beacon
  1. Build the LED helper program:
    Enter the plugin directory and run make:
    cd ~/.dsh/profiles/web/node_modules/dsh-caps-beacon && make

This step generates the `build/beacon-led` binary.
  1. Restart DSH Web:
    Restart dsh web

The plugin is loaded at startup.

If the system reports insufficient permissions, manually add access for dsh-caps-beacon/build/beacon-led in System Settings → Privacy & Security → Input Monitoring.

Configuration

The plugin supports configuration through cordis.patch.yml. Add a dsh-caps-beacon entry to the configuration file:

- id: dsh-caps-beacon
  config:
    enabled: true
    ledPath: ""            # Use built-in build/beacon-led by default
    blinkIntervalMs: 250
    rootsOnly: true        # By default, only respond to the root agent and ignore sub-agents
    verbose: false         # Log every mode change
    triggers:
      approval: true       # Enable approval request detection
      question: true       # Enable ask_user_question detection
      error: true          # Enable error/blocked detection

Typical Usage

After installation and startup, you can grasp the overall state via the Caps Lock light on the keyboard:

  • Observe working status: After handing a task to the agent, the LED stays solid on, indicating that the agent is working in the background.
  • Test blinking: In a conversation, ask the agent to call the ask_user_question function; the LED starts blinking, prompting you to provide an answer.

Notes

  • Hardware requirement: Requires a MacBook with a built-in Apple keyboard (external keyboards such as Magic Keyboards are not supported).
  • Dependency environment: Requires Xcode Command Line Tools in a macOS environment (for make compilation).
  • Permissions: You may need to grant Input Monitoring permission.
  • License: The plugin is under the MIT license.

Conclusion

If you are used to judging agent status by keyboard state, this plugin can reduce interruptions caused by frequently switching windows. You can view more plugin information on the directory page or see the source code on GitHub.

  • Plugin directory: https://www.skillhub.cn/plugins/xinyang920/dsh-caps-beacon
  • GitHub repository: https://github.com/xinyang920/dsh-caps-beacon