DeepSeek Harness (DSH) adopts a plugin-based architecture, aiming to inject capabilities directly into the tool runtime and credential system. gmail-dsh is a native plugin that does not depend on an MCP server or a third-party runtime; instead, it registers directly into DSH’s command system and system prompt. It handles Google authorization through a browser-based OAuth flow and delegates approval for each mutable operation (sending emails, modifying labels) to the user.

Core Capabilities

The plugin provides the following tools and commands:

  • gmail_search: Executes Gmail query search (for example, is:unread, from:x, newer_than:1w), sorted in reverse chronological order and supports pagination.
  • gmail_read: Reads the full message, including plain text (HTML optional), headers, attachments, labels, and the associated thread.
  • gmail_send: Sends plain-text emails; supports thread replies based on replyTo; prompts the user for approval before sending.
  • gmail_labels: Adds or removes labels on a single message or an entire thread; prompts the user for approval before the operation.
  • gmail_status: Displays authorization status, including the authorized account, default account, OAuth scopes, and client status.
  • /gmail 命令: Provides helper commands such as /gmail status, /gmail auth [email], and /gmail unauth [email].
  • system-prompt: Adds a system prompt in the configuration file, informing the model that Gmail is connected (it does not consume tokens before authorization).

Installation and Enablement

  1. Clone the repository or prepare the project directory.
  2. Install the plugin into the specified profile in DSH:
    dsh plugin --profile web add file:$PWD
  1. Add the plugin to the bundles list in the profile’s package.json:
    "dsh": {
      "profile": {
        "bundles": [
          "@deepseek-ai/dsh-base",
          "@deepseek-ai/dsh-web-app",
          "yolo-mode",
          "gmail-dsh"
        ]
      }
    }
  1. Restart dsh web or wait for HMR to load it automatically.

Google Cloud Configuration

Before use, complete project setup in the Google Cloud Console:

  1. Create or select a project.
  2. Go to APIs & Services → Enable APIs and Services and enable Gmail API.
  3. Configure the OAuth consent screen (select External or Internal), and add your account to the test users list during testing.
  4. Create an OAuth client ID and select Desktop application as the type. Download the JSON file and extract client_id and client_secret.

Credential Storage

Store the Google OAuth client credentials in DSH’s credential store (recommended) or set them through environment variables. Add the following to ~/.dsh/.credentials.yaml:

version: 1
refs:
  GMAIL_OAUTH_CLIENT_ID: <your-client-id>
  GMAIL_OAUTH_CLIENT_SECRET: <your-client-secret>

Authorization and Usage

Run the following command in a DSH session to authorize:

/gmail auth

The browser opens the Google authorization page. After approval, the plugin completes verification using the PKCE (S256) + state mechanism and stores the refresh token in the credential store.

Check the status:

/gmail status

Remove the account:

/gmail unauth [email]

Typical operation examples:
* Search: Use gmail_search to query unread emails.
* Read: Use gmail_read to retrieve email content.
* Send: Use gmail_send to send an email; the system prompts for the recipient and subject.
* Manage: Use gmail_labels to label an email; the system prompts for the label name and target.

Configuration and Notes

Configuration Items

Configuration can be adjusted by overriding cordis.patch.yml or environment variables. The default configuration includes:
* scopes: [openid, email, gmail.modify]
* callbackHost: 127.0.0.1
* callbackPath: /gmail/callback

Development Notes

  • Node module resolution: For file: installations, Node must be able to traverse upward to resolve @deepseek-ai imports. If the node_modules/@deepseek-ai symbolic link is missing, create it manually.
  • pnpm and development: When installing with pnpm, file: packages are copied into node_modules (frozen snapshot), so later code changes do not take effect. For development, remove the installed package and use a symbolic link to the checkout directory.
  • Approval mechanism: All read operations (search/read) do not prompt the user. Only sending and label operations trigger an ask decision. If no approval service is mounted, these operations are downgraded to rejection, ensuring the plugin is read-only in unprivileged environments.

Summary

gmail-dsh provides direct and secure Gmail access for DeepSeek Harness agents. Through native integration and prompt-based approval flows, it meets the need for automated email operations by agents while avoiding the risk of unauthorized modifications.