Preface

The DeepSeek Harness (DSH) ecosystem emphasizes “everything is a plugin.” Plugin developers often face a practical need: managing settings at different granularities—for example, specifying a model for the current session, setting build flags for the entire workspace, or adjusting theme colors for a global installation. dsh-granular-settings is designed to solve this. It acts as a shared platform that lets other plugins register these configuration items.

What Is This?

This is a DSH plugin that provides a Granular Settings page with Workspace, Session, and Plugin tabs. It supports scope control and provides eight control types (toggle, text, color, number, slider, enum, multiselect, path).

Core Features

  • Scope and namespace: Supports three scopes: session, workspace, and global. All settings are namespaced by plugin package name to prevent key name conflicts.
  • Control types: Provides eight control types, including text, number slider, color picker, enum, and multiselect.
  • No-session support: The Plugin scope remains available when no session is open; the Global scope can work independently of sessions.
  • Debug endpoints: Provides /granular-settings/describe and /relay/events endpoints for debugging.

Installation

Installation requires a DeepSeek Harness checkout directory and configuration files (such as a profile), and its hard dependency dsh-event-relay must be installed first.

mkdir -p ~/dsh-plugins && cd ~/dsh-plugins
git clone https://github.com/joao-paulo-santos/dsh-event-relay.git
git clone https://github.com/joao-paulo-santos/dsh-granular-settings.git

# from the harness checkout
pnpm dsh plugin --profile web add ~/dsh-plugins/dsh-event-relay
pnpm dsh plugin --profile web add ~/dsh-plugins/dsh-granular-settings

Typical Usage

Host side (registering controls):
A plugin can register settings on the Host side, specifying namespace, scope, type, and default value.

const gs = ctx.get('granularSettings')
const s = gs.register({
  namespace: 'my-plugin',
  scope: 'session',
  key: 'model',
  type: 'enum',
  label: 'Model',
  owner: 'My Plugin',
  description: 'Which model this session uses',
  options: [{ value: 'a', label: 'Model A' }],
  defaultValue: 'a',
  onChange: (value, target) => {}
})

Browser side (reading and subscribing):
On the browser side, you can use the useSetting hook to read and set values.

const gs = ctx.get('granularSettings')
const [model, setModel] = gs.useSetting('my-plugin', 'session', 'model')

Notes

  • Hard dependency: dsh-event-relay must be installed.
  • Environment requirements: A DeepSeek Harness checkout directory and configuration files are required.
  • License: MIT.