dsh-granular-settings
A DeepSeek Harness (DSH)
plugin: install it into a profile alongside your own plugins.
Settings that other plugins contribute. Plugins need knobs at more than
one granularity: a model choice for this session, a build flag for the whole
workspace, an accent color for the entire install. This plugin is the shared
platform for all of them. One registration API, eight control types, three
scopes, and one Granular Settings page in the settings dialog that renders
everything, grouped one box per plugin.
Every registration is namespaced by the owning plugin's package name, so
enabled from dsh-foo and enabled from dsh-bar are different settings
in different namespaces. Generic keys are safe; collisions cannot happen.
Not sure how to wire your own plugin? dsh-bouncing-squares-example
is a small working example, built exactly for that: three bouncing squares,
one per scope, driven entirely by registered settings. Copy it and go.
Three scopes, one page
image
| scope | value lives |
|---|
session | one value per session, in <workspace>/.dsh/settings/sessions/<sid>.json |
workspace | one value per workspace, shared by its sessions, in <workspace>/.dsh/settings/workspace.json |
global | plugin-wide, unrelated to any workspace, in ~/.dsh/settings/plugins/<namespace>.json |
The page has three tabs, Workspace, Session, Plugin, one per scope. It works
with no session open (the Plugin tab is the only scope that exists without
one). A Granular Settings view tab can also sit beside Chat in each session,
rendering the same page; its visibility is itself a plugin setting, default
on. A Plugin-tab setting can also move session/workspace storage centrally
under ~/.dsh/ instead of inside the workspace.
How to install
Requires a DeepSeek Harness checkout and a profile, here web. Clone both
dependencies into a plugins folder:
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
# verify the profile still composes
pnpm dsh --profile web --dump-config
Then restart the harness. The Granular Settings page appears in the settings
dialog; nothing else to wire up.
How to use in my plugin
Host side: register controls (inject granularSettings):
const gs = ctx.get('granularSettings')
const s = gs.register({
namespace: 'my-plugin', // REQUIRED: your package name, [a-z][a-z0-9-]*
scope: 'session', // 'session' | 'workspace' | 'global'
key: 'model', // [a-z][a-z0-9-]*, unique only within the namespace
type: 'enum',
label: 'Model',
owner: 'My Plugin', // display name for the settings box
description: 'Which model this session uses',
options: [{ value: 'a', label: 'Model A' }], // enum and multiselect only
defaultValue: 'a',
onChange: (value, target) => {}, // optional, serialized after persist
})
await s.get(sessionIdOrWorkspacePath) // sessionId, workspace path, or ignored for global
await s.set(sessionIdOrWorkspacePath, 'b')
s.dispose()
Control types and their metadata:
| type | value | registration extras |
|---|
toggle | boolean | |
text | string, max 4000 chars | |
color | hex string | |
number | finite number | optional min, max |
slider | number | required min, max, step |
enum | one option value | required options or a provider function |
multiselect | array of option values | required options or a provider function |
path | absolute directory string | |
For enum and multiselect, options may instead be a zero-argument
function evaluated at describe time, so an option list can track a live
library without re-registration.
Browser side: one hook, same service name as the host (inject
granularSettings; the browser and host planes never see each other):
const gs = ctx.get('granularSettings')
// inside any component:
const [model, setModel] = gs.useSetting('my-plugin', 'session', 'model')
const [speed, setSpeed] = gs.useSetting('my-plugin', 'workspace', 'speed')
const [accent, setAccent] = gs.useSetting('my-plugin', 'global', 'accent') // works sessionless
useSetting derives the session context itself, subscribes to changes
(doorbell, reconnect, window focus, write completion), serves the registration
default while a context's truth loads, and writes optimistically through
the host. With no session open, session and workspace values read as
undefined and their writers are no-ops; global values keep working.
Whole tabs can be contributed too, when rows are not enough:
const off = gs.registerTab({ id: 'my-tab', label: 'My Plugin', order: 40 }, MyComponent)
The component renders inside the page's scroll area and receives the
settings-section props, useSessions among them. The built-in tabs sit at
order 10, 20, 30.
Debugging
Read what the page reads, from a terminal:
curl 'http://127.0.0.1:3080/granular-settings/describe'
curl 'http://127.0.0.1:3080/granular-settings/describe?session=<sid>'
Watch the doorbells live:
curl -N 'http://127.0.0.1:3080/relay/events?topics=granular-settings'
-N makes curl stream instead of buffering.
Dependencies
- dsh-event-relay carries the change doorbells (hard dependency, both halves)
Plugins dependent on this
- dsh-granular-prompt, the prompt-composition manager: registers persona and system-prompt settings and a Prompt tab
- dsh-bouncing-squares-example, the tutorial example: three bouncing squares, one per scope, exercising seven control types
- dsh-workspace-overview, the Workspace Overview tab: registers the global "GitHub pill in session header" toggle
- dsh-workspace-history, the compaction journal: registers the per-session "Save compaction history" toggle
