dsh-agent-preset-recommender
English | 中文
A persistent, host-side DeepSeek Harness bundle that privately summarizes local Codex, Claude Code, and WorkBuddy/CodeBuddy activity and recommends a built-in DSH agent preset. It is advisory only: there is no LLM call, installation, preset mutation, or network request.
Compatibility baseline: DeepSeek Harness 0.1.2-rc.1, Cordis 4.0.2, and Schemastery 3.18.2.
The installed Host result is recorded in Windows DSH 0.1.2 acceptance.
Preview
Synthetic aggregate recommendation overview in DeepSeek Harness
Synthetic aggregate project detail in DeepSeek Harness
These previews use synthetic aggregate fixture data. They illustrate the bounded tool results only; no user sessions, paths, prompts, commands, or secrets appear.
Capability map
| Area | What the plugin does | Deliberate boundary |
|---|
| Local inventory | Boundedly scans supported session, project, and workflow metadata from Codex, Claude Code, CodeBuddy, and WorkBuddy. | Skips caches, builds, .git, symlinks, inaccessible roots, and unknown content. |
| Privacy-preserving evidence | Aggregates tool, session, workflow, and day-level activity under installation-local HMAC project IDs. | Never persists prompts, replies, commands, arguments, raw events, paths, usernames, secrets, or file bodies. |
| Deterministic advice | Maps observed evidence to minimal/standard capability presets plus optional delegation, workflow, web, MCP, and LSP capabilities. | Knows the shipped minimal, standard, ptc, and cordis roster, but never changes the user's current selection. |
| Agent-facing access | Provides scan_agent_projects for a fresh bounded scan and get_agent_preset_recommendations for the saved report. | Both tools return bounded readable text; neither installs, enables, or authenticates anything. |
| Durable local operation | Atomically persists a private report, supports startup and scheduled scans, and serializes all scan triggers. | No LLM call, network request, discovered-command execution, or background work survives plugin disposal. |
Install
dsh plugin --profile web add github:LeemanCheung/dsh-agent-preset-recommender
Restart the selected DSH profile after installation. The package declares dsh.bundle.patch and mounts one host plugin.
What it recommends
Observed aggregate behavior is mapped to:
- capability presets:
minimal or standard.
DSH 0.1.2-rc.1 ships minimal, standard, ptc, and cordis. The scanner lists that roster for accuracy, but automatic advice remains limited to the general-purpose minimal and standard choices. It never writes a default or current preset, so an explicit user selection remains unchanged.
- optional capabilities: Codex delegation, Claude Code delegation, workflows, web, MCP, and LSP.
Every recommendation includes confidence and numerical evidence. Thresholds are deterministic and local; results never automatically change DSH.
Exact recommendation and evidence rules
standard is recommended when at least one recognized session, workflow, or categorized tool call exists. Metadata files alone—and an empty observation set—yield minimal.- Codex/Claude Code delegation needs a recognized session from that source. Workflows need a workflow count or
workflow-category tool call; web, MCP, and LSP need their corresponding category count.
- Confidence is
0 with no observations; otherwise it is min(0.95, 0.35 + 0.2 × log10(observations + 1)), rounded to two decimal places, where observations are sessions + workflows + categorized tool calls.
- Tool names first use exact delegation aliases, then the fixed heuristic order delegation → workflow → MCP → LSP → web → shell → search → files; the first match wins and unmatched names are
other. These are trend signals, not an audit of every product tool.
Architecture
cordis.patch.yml → src/index.js (Cordis lifecycle + raw model tools)
├─ scanner.js (bounded traversal and aggregation)
├─ extractors.js (selected JSON/JSONL metadata fields)
├─ recommender.js (deterministic rules)
├─ store.js (atomic private report file)
└─ render.js (bounded readable tool output)
Runtime code is plain ESM JavaScript for Node.js 20+. It uses Node built-ins plus @deepseek-ai/schemastery for plugin configuration validation. Tool definitions are registered directly through ctx.tools.register and do not import unpublished DSH tool runtime helpers.
Privacy
The scanner persists aggregate metadata only:
- source and installation-keyed project identifier;
- categorized tool counts;
- session, workflow, and project-metadata counts;
- first/last observation dates (day-level);
- recommendation, confidence, and evidence counts;
- an explicit machine-readable privacy declaration.
It never persists prompts, responses, commands, tool arguments, raw events, absolute paths, usernames, secrets, or file contents. Project identifiers are derived with a random installation-local HMAC key, so report IDs cannot be dictionary-matched without the private key. WorkBuddy/CodeBuddy memory metadata is counted from file presence and modification time only; workflow/plan files are likewise never opened. The scanner makes no network requests and runs no discovered command.
Cache, dependency, build, output, coverage, virtual-environment, and .git directories are skipped. Symbolic links are not followed.
The default report is:
$DSH_HOME/state/agent-preset-recommender/report.json
If DSH_HOME is unset, ~/.dsh is used. The directory also holds a private random identity.key used only to derive project IDs. Report writes use a same-directory temporary file and atomic rename; restrictive permissions are requested where the platform supports them.
Supported locations and formats
| Source | Defaults | Read behavior |
|---|
| Codex | $CODEX_HOME/sessions, $CODEX_HOME/archived_sessions or ~/.codex/* | Bounded .jsonl/.json; selected session/project and tool-name fields |
| Claude Code | $CLAUDE_CONFIG_DIR/projects or ~/.claude/projects | Bounded .jsonl/.json; selected project and tool_use name fields; workflow sidecars, journals, task/session/plan stores, and global history are excluded |
| Claude personal workflows | $CLAUDE_CONFIG_DIR/workflows or ~/.claude/workflows | .js file presence and day only; scripts are never opened. Add project-local <repo>/.claude/workflows explicitly to claudeWorkflowRoots if desired |
| Claude transcripts | Disabled | Scanned only when claudeTranscriptRoots is explicitly configured |
| CodeBuddy CLI | $CODEBUDDY_CONFIG_DIR/projects or ~/.codebuddy/projects | Bounded canonical project .jsonl records; ~/.codebuddy/workflows/*.js and project-local workflow scripts are inventoried by presence only. Process maps, tool-result/blob directories, and workflow runtime sidecars are excluded |
| WorkBuddy | $WORKBUDDY_CONFIG_DIR/projects or ~/.workbuddy/projects, ~/.workbuddy-ai/projects | Heuristic, version-sensitive project .jsonl inventory; native session layout is not vendor-contracted, so it is never treated as proof of CodeBuddy session equivalence |
| Project-local CodeBuddy/WorkBuddy metadata | <project>/.codebuddy or <project>/.workbuddy memory, workflows, plans, or automations | Count and day only, including workflow .js; content is not read; memory never becomes workflow evidence |
Formats vary between product releases. CodeBuddy paths/workflow scripts are documented; WorkBuddy session-file detection is an observed heuristic. Unknown fields are ignored, malformed records are skipped, and malformed files are counted as errors without stopping the scan.
Configuration
Configure the inserted agent-preset-recommender row in a DSH patch:
- id: agent-preset-recommender
config:
scanOnStart: true
intervalMinutes: 360 # 0 disables scheduled scans
maxFilesPerSource: 500
maxBytesPerFile: 1048576
recentDays: 90
stateDirectory: '' # empty = $DSH_HOME/state/agent-preset-recommender
codexRoots:
- ~/.codex/sessions
- ~/.codex/archived_sessions
claudeRoots:
- ~/.claude/projects
claudeTranscriptRoots: [] # opt in explicitly
claudeWorkflowRoots:
- ~/.claude/workflows # inventory only; script content is never read
workbuddyRoots:
- ~/.codebuddy
- ~/.workbuddy
- ~/.workbuddy-ai
- ~/WorkBuddy
- ~/CodeBuddy
Defaults honor CODEX_HOME, CLAUDE_CONFIG_DIR, CODEBUDDY_CONFIG_DIR, and WORKBUDDY_CONFIG_DIR when DSH starts. Supplying an explicit root list in the plugin configuration takes precedence over those defaults.
Bounds are validated: intervalMinutes is 0–35,791, maxFilesPerSource 1–100,000, maxBytesPerFile 1 KiB–64 MiB, and recentDays 1–3,650. Missing/inaccessible roots are skipped. Startup, scheduled, and tool-triggered scans share one serialized queue and are aborted on plugin disposal.
Set both scanOnStart: false and intervalMinutes: 0 to disable automatic scans; the model tool can still scan on demand. Before deleting the state directory to reset the report, stop the plugin: this also removes identity.key, intentionally rotating every keyed project ID.
Model tools
scan_agent_projects
Runs and persists a fresh scan. Optionally refresh only selected sources:
{ "sources": ["codex", "claude"] }
Unselected source aggregates from the previous report remain intact.
get_agent_preset_recommendations
Reads the persisted report without scanning:
{}
Or retrieve one keyed project:
{ "project_id": "codex-0123456789abcdef" }
Both tools return bounded readable text strings. Omitting sources or passing an empty list scans every source; a selected-source scan preserves the prior aggregate for unselected sources.
Each persisted source report exposes filesConsidered, truncatedFiles, skippedOld, skippedOversize, skippedLimit, and parseOrAccessErrors alongside counts. Summary output lists at most 50 projects and is capped at 12,000 characters; query a project_id for its bounded detail.
Limitations
- Metadata schemas are intentionally conservative; unrecognized tool events may be undercounted.
- Keyed IDs are stable only while the private state directory remains available; deleting
identity.key intentionally creates a new identifier set.
- A recommendation reflects observed local frequency, not task quality or organizational policy.
- The plugin does not verify that optional products or capabilities are installed or authenticated.
- JSONL files above the byte cap are prefix-sampled within the byte/record bounds; their remaining data, oversized JSON files, old files, and older files beyond a source limit are intentionally omitted. Compressed Codex
.jsonl.zst rollouts are not read in 0.1.7. Claude workflow scripts and dynamic workflow sidecars are deliberately not parsed.
Development
npm install
npm test
Tests use synthetic temporary fixtures and Node's built-in node:test; no local product data is read. See SECURITY.md for private vulnerability reporting guidance.
License
MIT
