Skip to content

About

Semantic code search for DeepSeek Harness: the Semble index as two native MCP tools (search / find_related), so an agent finds code by behaviour instead of guessing file names.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

dsh-semble

dsh-semble

Awesome DSH Plugin Listed on dsh-plugin.org license: MIT npm version CI status GitHub stars last commit topic: dsh-plugin platform: Windows, macOS, Linux node: >=24.9 dsh: >=0.2.1-rc.2

English | 简体中文

Ask about behaviour, not file names. dsh-semble gives an agent two native tools — semble_search and semble_find_related — that find code by describing what it does. Instead of guessing a filename and grepping for it, the agent asks "where is the retry policy applied?" and gets ranked file:line hits with snippets. Upstream benchmarks measure ~99% fewer tokens than grep + read, at retrieval quality on par with code-specialized transformer retrievers — figures from the Semble project, not measured by this plugin. Runs fully local on CPU — no API key, GPU, or external service.

In one minute: need uv on PATH → install dsh-semble from Settings → Plugins → Install → restart DSH once → ask your agent a "where/how does X work" question. The first call downloads the package and embedding model (~1–2 min); everything after is local. Details in Install.

Contents

What you get

Tool Hand it Back comes
semble_search a sentence describing the code or where it lives ranked file:line hits with snippets
semble_find_related one location you already know its neighbours: other implementations, callers, tests

The bundle also registers one slash command, /semble, for the reporting subcommands the tools do not expose: /semble savings, /semble file-types, /semble version and /semble clear <index|savings|orphans|all>. See Commands.

A typical exchange:

You: Where does DSH decide that a plugin is "loaded"?

Agent: calls semble_search, gets a hit in the plugin inventory, opens it with read, finds isEntryLoaded comparing loader entry names against the package name, and answers from the source rather than from a guess.

How it works

Semble splits every file into code-aware chunks with tree-sitter, then retrieves against two complementary signals: static Model2Vec embeddings (the code-specialized potion-code-16M-v2 model) for semantic similarity, and BM25 for lexical matches on identifiers and API names. The two result lists are fused with Reciprocal Rank Fusion (RRF), then re-ranked by code-aware signals: a chunk that defines the queried symbol outranks one that merely mentions it, query words matching identifier stems inside a chunk earn extra weight (parse config → parseConfig / config_parser), several hits from the same file promote the file as a whole, and test files, examples and compat shims are demoted so the canonical implementation surfaces first. The embedding model is static — no transformer forward pass at query time — so (per the same upstream benchmarks) indexing a typical repo takes under a second and every query lands in milliseconds, entirely on CPU. Indexes are cached to disk on first use and refreshed incrementally as files change; https:// repositories are cloned on demand into the same cache.

Before first use. The plugin runs on uvx, which must be on PATH, and the first call is online: it installs semble[mcp] from PyPI and downloads the potion-code-16M-v2 model from huggingface.co. Indexing and queries run locally once that is done; if your network cannot reach huggingface.co, point HF_ENDPOINT at a mirror.

Using the tools

  • query / path + line — a behaviour sentence for semble_search; a known file:line for semble_find_related (line is 1-indexed, path exactly as a search result showed it).
  • repo — required on the first call unless defaultRepo is set. Absolute path of the repository, or an https:// git URL. A list searches several repositories at once. After any call naming a single repository, later calls may omit repo and reuse it automatically; a multi-repo call is deliberately not remembered, since reusing one of several would silently narrow the next search. See Settings and Several repositories.
  • top_k — number of results, 1–100; default 5. Raise to 10–20 when the first pass misses.
  • max_snippet_lines — default 10; 0 returns locations only.
  • content — a list of content types: code (default), docs, config, all; pass ["all"] to index docs and config as well. Multiple values are deduplicated.

The first query against a repository builds its index (slow, one-time); later queries reuse it. Hits are ranked by similarity. Search scores are rank-fusion values that stay small (0.0x) even for exactly-relevant code — treat them as a relative ordering, not an absolute confidence. An empty result is the real "nothing relevant here" signal.

Install

Desktop app

Settings → Plugins → Install, and paste:

dsh-semble

Pin a version with dsh-semble@3.2.0. The settings page is the only supported route for the desktop profile — the CLI refuses it because the Electron app owns that profile's node_modules and lockfile.

CLI

dsh plugin --profile web add dsh-semble

The subcommand runs pnpm add inside the profile and reconciles dsh.profile.bundles, so the bundle mounts on the next start. There is no build step, so pnpm needs no allowBuilds exemption.

From source

To track main, a fork, or an unreleased commit, install from the repository instead:

dsh plugin --profile web add github:CodeIntegrity/dsh-semble

github:owner/repo, git+https://…, https://github.com/owner/repo and .tgz URLs are accepted; these need git on PATH.

Local checkout

dsh plugin --profile web add link:/absolute/path/to/dsh-semble   # macOS / Linux
dsh plugin --profile web add link:D:\path\to\dsh-semble          # Windows

The profile then points at your working copy, so edits to cordis.patch.yml apply on the next start without reinstalling.

Prerequisites

uv must be on PATH — uvx launches Semble from PyPI. Node.js >=24.9 is required by the host (see Compatibility).

winget install astral-sh.uv                      # Windows
brew install uv                                  # macOS
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS / Linux

First start downloads the package and the embedding model (~1–2 min, one-time, offline afterwards). Restart DSH once after installing; until then the settings row may read 待重启.

Settings

Edit the plugin's row in Settings → Plugins (the loader row's config, read by the plugin on every call):

Field Default Why change it
command / args uvx / --from 'semble[mcp]' semble point command at uvx.exe if only a .cmd shim is installed; use semble[mcp]==X.Y.Z in args to pin a release. Both tools and /semble use these values. To search docs/config, pass content: ["all"] or set defaultContent — do not append CLI flags to args
toolTimeoutMs 300000 call ceiling for both tools and /semble; lower it to fail faster
defaultContent [code] content types used when a tool call omits content, e.g. [all] or [code, docs]
maxConcurrent 2 cap on simultaneous CLI children; raise only when the machine can afford parallel index builds
defaultRepo unset absolute path used on the first repo-less call; after any single-repo call the last repository is reused automatically
env empty HF_ENDPOINT on restricted networks, SEMBLE_CACHE_LOCATION to move the index; applied to both tools and /semble

Changing settings re-applies the plugin (re-registering the tools and command); disk index caches survive. A value of the wrong type fails validation and the row stops loading — fix the field and re-apply.

Tuning

Semble reads its configuration from the environment of the process that runs it. Put overrides in the env field of the plugin config; both the search tools and /semble now launch through that same runner, so a report and a search see the same SEMBLE_* values.

Variable Default Effect
SEMBLE_INDEX_WORKERS 4 worker processes that chunk a repository during the first index; 0 chunks in-process. Raise it on a many-core machine, lower it to stop a background search from saturating the CPU
SEMBLE_MCP_IDLE_TIMEOUT 0 (never) seconds an idle repository index stays in the in-memory cache of the MCP server mode; the CLI exits per call, so the variable has no effect on it
SEMBLE_MODEL_NAME minishlab/potion-code-16M-v2 alternative Model2Vec embedding model, as a local path or a Hugging Face repository
SEMBLE_MAX_FILE_BYTES 1000000 files above this size are skipped; raise it for generated code worth indexing
SEMBLE_CLONE_TIMEOUT 60 seconds allowed for cloning an https:// repository
HF_ENDPOINT https://huggingface.co mirror used for the one-time model download

Concurrent Semble CLI processes are capped by an in-process FIFO semaphore (default 2, set maxConcurrent to change it), so parallel tool or sub-agent calls do not contend on uvx setup, index locks and embedding-model memory. On POSIX a timed-out or aborted call tears down the whole child process tree (SIGTERM, then SIGKILL after a short grace); on Windows only the direct child is terminated.

Excluding files

The indexer honours .gitignore, plus a .sembleignore at the repository root for files git keeps but search should skip: generated clients, fixtures, vendored trees. The syntax is gitignore's, negation included:

# .sembleignore
packages/client/generated/
test/fixtures/
*.min.js
!*.proto          # force-include a file .gitignore excludes

A pattern that only ever needs one repository should stay in that repository's .sembleignore; keep the plugin settings free of per-repository rules.

Several repositories

repo accepts a list, so one call can compare a service with the shared library it depends on:

{ "query": "where is the retry policy applied", "repo": ["D:\\work\\service", "D:\\work\\shared"] }

Git URLs work the same way and are cloned once into the cache. Each repository gets its own index; a list costs one first-time index build per repository. Hit paths are prefixed per repository and the output ends with a Sources: <label> → <path> line. Use that path for a git-URL hit: its label only names the temporary clone upstream made for it. A multi-repo call is not remembered as the default for the next call (see Using the tools).

Commands

The two tools cover retrieval only; Semble's reporting and cache-maintenance subcommands exist only in its CLI. The bundle registers /semble for them:

Command Prints
/semble savings tokens saved by returning snippets instead of whole files, per period and per call type
/semble file-types the extensions Semble indexes, as JSON grouped by content type
/semble version the Semble release the uvx installation resolved — the quickest install check
/semble clear index drop the search index cache; the next search rebuilds it
/semble clear orphans remove only indexes whose source path no longer exists (handy after DSH cleans up archived git worktrees)
/semble clear savings reset the token-savings statistics
/semble clear all all of the above

All of them run in the host process: nothing is sent to the model, no approval prompt appears, and the output is the CLI's own (colour disabled). The same uvx --from "semble[mcp]" semble installation is used, so /semble works exactly where the search tools work.

savings reads the cache Semble wrote, so it only counts searches made against the same SEMBLE_CACHE_LOCATION. Clearing can also be done from a terminal: uvx --from "semble[mcp]" semble clear index.

clear always names its target: a bare /semble clear, or a misspelled one, only prints the usage and deletes nothing. Clearing is safe — indexes rebuild on the next search — but not free: the first search after clear index / clear all re-indexes from scratch. /semble is deliberately not a search shortcut — that is what the two tools are for. Type /semble alone for the usage line.

Platform notes

The bundle ships no OS-specific path and no region-specific endpoint, so one installation serves all three platforms. What differs is only what you type:

Concern Windows macOS / Linux
Executable uvx.exe, resolved through PATH uvx
Repository paths D:\work\repo /home/me/repo
Profile home C:\Users\<you>\.dsh ~/.dsh
Retrieved paths keep \ separators POSIX /

Bundled skill

Installation also registers one routing skill, semble-code-search. The tools do not advertise when they are worth calling, and a model that reaches for grep first never learns that the index existed.

DSH loads skills lazily:

When Enters the session Cost
Before the first request one catalog entry (name + capped description) a few hundred bytes per session
Model calls skill the full skills/semble/SKILL.md body ~2 KB, only when used
You type /semble-code-search same body, injected into that step manual

/semble-code-search loads instructions: the search itself still runs through the two native tools. The real executable command is /semble (see Commands), which runs a CLI report in the host and costs no model tokens.

The body never enters the system prompt. To keep the tools and drop the skill, delete the ctx.skills.register(...) block in lib/index.js; /semble keeps working because it is registered separately.

How it is wired

The bundle inserts one loader row: semble-anchor — this very plugin, loaded under its own package name. DSH decides "loaded" by matching loader entry names against the installed package name, so the row doubles as the plugin's entry point, and its config is read by the plugin to become the tools' launcher settings (command / args / toolTimeoutMs / env).

Semble itself is not vendored. The plugin declares how to launch it from PyPI with a floating spec, so upstream bugfixes and new CLI flags arrive on the next call; only a breaking change to the CLI surface would need an edit here.

Update

Re-run the install with a newer version, or press 更新 in settings:

dsh plugin --profile web add dsh-semble@3.2.0

Source installs re-run with the new ref, e.g. dsh plugin --profile web add github:CodeIntegrity/dsh-semble#v3.2.0.

Compatibility

The package follows semver. The public surface, which 3.x keeps stable:

  • the two native tools semble_search and semble_find_related (their behavior tracks the PyPI semble release uvx resolves — the plugin pins nothing, see How it is wired);
  • the plugin entry: the default export and the named apply from dsh-semble, receiving (ctx, config) — config is the loader row's config, coerced by the plugin; the context carries skills and optionally inject/tools/commands;
  • the /semble subcommand allow-list (savings, file-types, version, clear) and its result shape ({ kind: 'success' | 'error', text });
  • the plugin settings command, args, toolTimeoutMs, defaultRepo, defaultContent, maxConcurrent and env, and the exported Standard Schema Config;
  • the exports ./locale/*.json, ./icon, and ./package.json.

Not covered by the promise: row ids and launch details inside cordis.patch.yml (they are host wiring, not API), the routing skill's name and body, and everything under lib/ except the entry point — tests may import parseSembleArgs/runSemble, but downstream packages should not. The default engines requirement (node >=24.9 and dsh >=0.2.1-rc.2) only widens within a major version; a raised minimum is a minor bump at most, since installs resolve through the package manager.

2.x → 3.0.0: the MCP bridge is gone. The tools are renamed from mcp__semble__search / mcp__semble__find_related to semble_search / semble_find_related, and the toolCallTimeoutMs setting becomes toolTimeoutMs. The old names are no longer registered; update any script that referenced them. Restart DSH once after upgrading.

3.0.0 → 3.0.1: fixes a load failure on real hosts — the default export did not carry the inject declaration, so the loader could not see the skill dependency, the plugin row reported as failed, and no tools appeared (the 2.x anchor row had the same latent defect; the MCP row was doing the actual work, which hid it). No API changes in 3.0.1; update straight from 3.0.0.

3.0.1 → 3.0.2: /semble gains the clear subcommand (index / savings / orphans / all) so the index cache can be dropped from within a session; the target word is required, and a bare /semble clear only prints the usage.

3.0.2 → 3.0.3: docs only — the routing skill's if the tools are missing section now names the usual cause of a CLI launch failure (uv absent from the host's PATH) and the Windows uvx.cmd shim workaround, so the triage loop closes inside the skill instead of the README. No code changes.

3.0.3 → 3.0.4: aligns engine declarations with DSH 0.2.2-alpha.2, raising engines.node from >=22 to >=24.9 and @types/node from ^22 to ^24. No runtime code changes.

3.0.4 → 3.0.5: tracks upstream semble 0.7.3 without pinning it. semble_search output now ends with a Sources: <label> → <path> line from the upstream repos map, which is what makes git-URL hits openable. The CLI contract is otherwise unchanged.

3.0.5 → 3.0.6: caps concurrent CLI subprocesses at 2 via a zero-dependency FIFO semaphore, sets PYTHONUTF8=1 / PYTHONIOENCODING=utf-8 on children so Windows writes UTF-8 to redirected output, and documents /semble clear orphans for cleaned-up git worktrees.

3.0.6 → 3.1.0: a single-repo call is remembered so later calls may omit repo (a multi-repo call is not); a new defaultRepo setting backs the first repo-less call. Timeout/abort now tears down the whole child process tree on POSIX (SIGTERM → SIGKILL, Windows still kills only the direct child). The skill and both tool descriptions now route behaviour questions to the tools before guessing grep keywords.

3.1.0 → 3.1.1: commits pnpm-lock.yaml so pnpm users resolve the same dev-dependency versions CI installs, and ignores the test path in .gitignore. No API changes.

3.1.1 → 3.2.0: adds the defaultContent and maxConcurrent settings; /semble now uses the plugin's command / args / env / toolTimeoutMs settings, so the Windows uvx.exe fix and cache overrides apply to reports as well as to search. CI and publishing move to Node 24.9. The exported Config schema now reports malformed fields as issues instead of silently passing them through; an issue stops the row from loading, so a settings typo appears as a failed plugin row rather than a quiet fallback to a default. No breaking API changes: the two tools, the /semble allow-list and the entry signature are unchanged, and omitted new settings keep their defaults.

Uninstall

Settings → Plugins → 卸载, or:

dsh plugin --profile web remove dsh-semble

Installed the 1.x source build? Remove it by its old name first: dsh plugin --profile web remove @local/semble-mcp. The package was renamed in 2.0.0, and the anchor row only matches an install whose package name is dsh-semble.

The cached index and the HuggingFace model stay on disk and are reused after a reinstall.

Troubleshooting

Symptom Cause Fix
Row reads 待重启 after install the host loaded its layer list before the install restart DSH once
Tools work, row reads 未加载 cordis.patch.yml lost the anchor row reinstall this version or newer
semble_search / semble_find_related never appear the plugin is not loaded (missing anchor row), or the host has no tool registry reinstall, restart DSH; type /semble version as a self-check
First search takes minutes one-time model download wait, or set HF_ENDPOINT
Search fails with "did not finish within …" index build + model download outran toolTimeoutMs raise toolTimeoutMs in the plugin settings, or warm the cache once with a CLI search
Search fails with "The Semble CLI could not be started" uvx is not on the host's PATH install uv, restart DSH; on Windows with only a .cmd shim, set command to uvx.exe
Search looks stale after a large refactor the disk index reuses files it believes unchanged uvx --from "semble[mcp]" semble clear index, then search again
/semble answers "Could not start the Semble CLI" uvx is not on the host's PATH, or command is misconfigured install uv, restart DSH; on Windows with only a .cmd shim, set command to uvx.exe
savings counts fewer calls than you made SEMBLE_CACHE_LOCATION differs between the CLI you ran by hand and the plugin runner set SEMBLE_CACHE_LOCATION in the plugin env so tools and /semble agree
ERR_PNPM_GIT_RESOLVE_FAILED no network route to github.com use a tarball URL or a mirror

Development

git clone https://github.com/CodeIntegrity/dsh-semble
dsh plugin --profile web add link:$(pwd)   # then edit and restart DSH

Requires Node.js >=24.9 (matching the host floor). No build step: lib/ is plain ESM and cordis.patch.yml is read directly. The only runtime dependency is uv.

npm test runs the suite with Node's built-in runner. The spawn tests replace uvx with the Node binary, so they neither download Semble nor touch your cache. npm run typecheck runs tsc in checkJs mode over lib/ — the JSDoc annotations are the type contract, and nothing is compiled.

Publishing

Releases are tag-driven by .github/workflows/publish.yml:

npm version minor          # bumps package.json and creates the vX.Y.Z tag
git push origin main --follow-tags

The workflow runs the tests, refuses to continue when the tag and package.json disagree, skips a version that is already on the registry, and publishes with npm provenance. It needs one repository secret:

Secret What it is
NPM_TOKEN an npm granular access token with read/write access to dsh-semble and 2FA bypass enabled for automation

Provenance requires a public repository; on a private one, drop --provenance from the publish step. A manual run of the workflow (workflow_dispatch) defaults to publishing the current package.json version; tick dry_run to only run npm pack --dry-run.

License

MIT

About

Semantic code search for DeepSeek Harness: the Semble index as two native MCP tools (search / find_related), so an agent finds code by behaviour instead of guessing file names.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages