Introduction¶

In scenarios where multiple AIs collaborate independently, having a particular AI focus on PR and issue changes in a specific GitHub repository is a common requirement—such as creation, push, comments, merge, and so on. Manually refreshing GitHub pages repeatedly is inefficient, while directly polling the GitHub API is prone to triggering rate limits.

gh-watch is a plugin for DeepSeek Harness (DSH) that aims to solve this problem. It polls the target repository in the background and, upon detecting changes, generates a notification and injects it into the AI conversation. By design, it strictly separates “watching” from “acting”: the plugin only discovers and notifies, without performing code review, automatically replying, or executing merge operations.

Core Features¶

gh-watch provides a complete watching and notification mechanism, including the following capabilities:

• Session-level independent configuration: Each AI session can have an independent watcher that does not interfere with others. You can configure different repository lists, polling intervals, notification modes, and push targets for each session.
• Automatic polling and change detection: The plugin automatically polls GitHub PR and issue APIs. It can identify 9 change types: created, new push, new comment, comment changed, merged, closed, reopened, updated, and active query.
• Baseline snapshot mechanism: When first watching a repository, the plugin creates a cursor snapshot and does not push historical data, avoiding excessive notifications from historical records.
• Exponential backoff retry: If polling fails, it uses an exponential backoff strategy of 2x→4x→8x to delay the next poll, resetting after a fully successful execution, effectively reducing the risk of hitting GitHub API rate limits.
• State persistence: Watcher configurations and cursor snapshots are persisted to $DSH_HOME/gh-watch/state and can be restored after a process restart.

Installation and Enablement¶

As a DSH user plugin, gh-watch needs to be mounted into your profile via cordis.patch.yml.

1. Install dependencies:

    npm install
    # 或 pnpm install

2. Mount the plugin:
   Insert the following content into your cordis.patch.yml and add the plugin to the layer stack:

    - insert:
      - id: gh-watch
        name: 'gh-watch'
        config: {}

3. Configure the token:
   The plugin needs to access api.github.com. It is recommended to use a read-only Personal Access Token (PAT) and pass it through an environment variable or DSH credentials. Setting the environment variable GH_TOKEN or GITHUB_TOKEN is sufficient.

Typical Usage¶

gh-watch registers four tools in the session context. These tools can be used to configure and manage watchers, as well as to handle notifications.

1. Configure the Watcher¶

Call gh_watch_configure to start watching the specified repository. The repos parameter is required, intervalMin is the polling interval in minutes, notifyMode controls the notification mode, and pushTarget controls the notification destination.

// 通知模式：inform=仅告知，auto=通知并请AI检查
// 推送目标：current=回当前对话，new=新开对话
gh_watch_configure({
  repos: ['psenY/gh-watch'],
  intervalMin: 10,
  notifyMode: 'inform',
  pushTarget: 'current'
})

2. Proactive Query¶

If you need to immediately get the latest state of a PR or issue, you can call gh_watch_act.

gh_watch_act({
  repo: 'psenY/gh-watch',
  id: 123,
  kind: 'pull', // 或 'issue'
  target: 'current'
})

3. Acknowledge Notifications¶

Notifications pushed by the plugin include an ID (such as gw-xxxxx-1). After handling that change, call gh_watch_ack to confirm so the plugin can remove the pending item.

gh_watch_ack({ id: 'gw-xxxxx-1' })

4. View Status and Stop¶

Use gh_watch_status to view the current session’s watcher configuration and runtime status, including the number of pending acknowledgment notifications. If you need to stop watching, call gh_watch_stop.

// 查看配置与状态
gh_watch_status()

Notification Acknowledgment and Timeout Repush¶

gh-watch introduces an acknowledgment mechanism to prevent the AI from missing notifications when it is busy.

• Acknowledgment mechanism: Each notification ends with a 【本条 id: xxx】 identifier. After the AI finishes handling it, it needs to call gh_watch_ack. If it is not acknowledged within 15 minutes, the plugin will remind again (up to 2 times) and then leave a log record.
• Configuration: The acknowledgment timeout ackTimeoutMin and maximum retry count ackMaxRetries can be configured in gh_watch_configure (defaults are 15 minutes and 2 times).

Applicable Scenarios and Notes¶

gh-watch is suitable for scenarios where the AI needs to maintain real-time awareness of a specific codebase, such as a code review assistant or an automatic issue-reply bot.

Notes:
* Permission separation: The plugin itself does not perform any review or reply operations; it only sends notifications. Make sure the AI or user has the corresponding GitHub permissions to handle those changes.
* Network environment: The plugin runtime environment must be able to access api.github.com.
* State file: The watching state is stored in $DSH_HOME/gh-watch/state.json. Modifying this file may affect plugin operation, and manual editing is not recommended.

Conclusion¶

By separating “discovery” from “action,” gh-watch reduces the complexity of DSH plugin development and avoids endless notification spam from the AI. With independent configuration and a complete acknowledgment mechanism, it provides stable GitHub watching capabilities for multi-AI collaboration scenarios.

• Plugin directory page
• GitHub repository