English | 简体中文
Ask about behaviour, not file names.
dsh-semblegives an agent two native tools —semble_searchandsemble_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 rankedfile:linehits 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.
- What you get
- Using the tools
- Install
- Settings
- Tuning
- Commands
- Platform notes
- Bundled skill
- How it is wired
- Update
- Compatibility
- Uninstall
- Troubleshooting
- Development
- Publishing
- License
| 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 withread, findsisEntryLoadedcomparing loader entry names against the package name, and answers from the source rather than from a guess.
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.
query/path+line— a behaviour sentence forsemble_search; a knownfile:lineforsemble_find_related(line is 1-indexed, path exactly as a search result showed it).repo— required on the first call unlessdefaultRepois set. Absolute path of the repository, or anhttps://git URL. A list searches several repositories at once. After any call naming a single repository, later calls may omitrepoand 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;0returns 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.
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.
dsh plugin --profile web add dsh-sembleThe 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.
To track main, a fork, or an unreleased commit, install from the repository instead:
dsh plugin --profile web add github:CodeIntegrity/dsh-semblegithub:owner/repo, git+https://…, https://github.com/owner/repo and .tgz URLs are accepted;
these need git on PATH.
dsh plugin --profile web add link:/absolute/path/to/dsh-semble # macOS / Linux
dsh plugin --profile web add link:D:\path\to\dsh-semble # WindowsThe profile then points at your working copy, so edits to cordis.patch.yml apply on the next start
without reinstalling.
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 # Windowsbrew install uv # macOS
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / LinuxFirst 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 待重启.
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.
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.
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 excludesA pattern that only ever needs one repository should stay in that repository's .sembleignore; keep
the plugin settings free of per-repository rules.
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).
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.
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 / |
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.
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.
Re-run the install with a newer version, or press 更新 in settings:
dsh plugin --profile web add dsh-semble@3.2.0Source installs re-run with the new ref, e.g.
dsh plugin --profile web add github:CodeIntegrity/dsh-semble#v3.2.0.
The package follows semver. The public surface, which 3.x keeps stable:
- the two native tools
semble_searchandsemble_find_related(their behavior tracks the PyPIsemblerelease uvx resolves — the plugin pins nothing, see How it is wired); - the plugin entry: the default export and the named
applyfromdsh-semble, receiving(ctx, config)—configis the loader row'sconfig, coerced by the plugin; the context carriesskillsand optionallyinject/tools/commands; - the
/semblesubcommand allow-list (savings,file-types,version,clear) and its result shape ({ kind: 'success' | 'error', text }); - the plugin settings
command,args,toolTimeoutMs,defaultRepo,defaultContent,maxConcurrentandenv, and the exported Standard SchemaConfig; - 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.
Settings → Plugins → 卸载, or:
dsh plugin --profile web remove dsh-sembleInstalled 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.
| 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 |
git clone https://github.com/CodeIntegrity/dsh-semble
dsh plugin --profile web add link:$(pwd) # then edit and restart DSHRequires 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.
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-tagsThe 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.
MIT
