dsh-researchcraft

ResearchCraft as a DeepSeek Harness profile: the DSH web UI and DSH agent, with ResearchCraft’s scientific skills, living lab notebook, and specialist subagents.

Install

1. Install DeepSeek Harness first (dsh). Follow that repo's README — for example:

   npm install -g @deepseek-ai/dsh
   

   or run without a global install: npx @deepseek-ai/dsh web. You need a working dsh CLI before the next step.

2. Then add this plugin:

dsh plugin --profile researchcraft add github:raktim-mondol/dsh-researchcraft

This creates the researchcraft DSH profile (if it doesn't exist yet) and adds the plugin to it.

To update to the latest version:

dsh plugin --profile researchcraft update dsh-researchcraft

To install from a local checkout instead (for plugin development):

dsh plugin --profile researchcraft add /path/to/dsh-plugin

The profile must also list @deepseek-ai/dsh-web-app before this bundle.

Run

dsh --profile researchcraft
# or, if you use the shared launcher:
dsh-researchcraft

Opens the Harness web UI (typically http://127.0.0.1:3080).

One DSH surface at a time. dsh-web, dsh-tui, dsh-martty, and dsh-researchcraft share $DSH_HOME (including port 3080 and the zvec-grep daemon). Ctrl+C does not always wait for those to exit, so starting another launcher while one is still in the background will fail or pick up the wrong process. The shared launcher (scripts/dsh-launch, installed as those four commands) stops leftover DSH processes and zg server off before exec. If you invoke dsh --profile … directly, stop the previous one first:

# leftover web UI
ss -ltnp | grep 3080
# leftover zg daemon
zg server off

Switching to dsh-tui / dsh-web also clears a global agent-presets default of researchcraft if one was saved. That default lives in ~/.dsh/settings.yaml and is shared across profiles — dsh-tui does not ship dsh-researchcraft/* plugins, so booting with that default crashes the agent. The ResearchCraft profile still defaults to the ResearchCraft preset from its own patch.

Select the ResearchCraft agent preset for each chat. Installing this plugin adds a ResearchCraft option to the agent-preset picker — it does not replace whatever your default preset already is (commonly "Standard mode" / "PTC mode"). A new chat starts on that default, not on ResearchCraft, until you pick it explicitly:

1. Start a new session.
2. Click the preset selector at the top of the message box (reads "PTC mode", "Standard mode", or similar by default).
3. Choose ResearchCraft from the list.

The persona, the longer research system prompt (notebook discipline, specialist roster, connector guidance, …), academic search (mcp__parallel__*, parallel_search, mcp__firecrawl__*, mcp__scite__*, consensus_search), and workspace semantic search (mcp__zvec_grep__zvec_grep_search) are only present on this preset — a session left on the default one won't have them, and asking it to use e.g. the Parallel connector will fail with tools[name] is not a function. The general-purpose tools below (notebook, image_generate, sci_inspect, latex_compile, pdf_to_markdown, modal_run/runpod_run, workflow) are available on every preset regardless, since they're registered at the plugin/bundle level rather than inside the ResearchCraft preset. Native grep / glob come from the ResearchCraft preset's filesystem-search row.

The preset picker remembers your last choice per browser, so you'll typically only need to do this once.

What it adds

• ResearchCraft agent preset — persona, research system prompt (notebook discipline, specialist roster, connector guidance), standard coding tools, and the academic search connectors below. Select it explicitly per chat — see Run.

• Scientific skills catalogue vendored into skills/ from six open-source K-Dense-AI projects, bundled with the plugin like the specialist briefs below — no separate checkout or setup needed (see NOTICE for exactly what was changed vs. each source):

  • 140 domain skills (chemistry, genomics/bioinformatics, imaging, stats, ML, writing, …) — scientific-agent-skills
  • 16 research-discipline/methodology skills (question framing, pre-registration, verification-before-claiming, red-team review, …) — science-superpowers
  • 503 profession-specific expert-reasoning skills (accelerator-physicist, zoologist, actuarial-scientist, …), converted from AGENTS.md profiles — scientific-agents
  • 23 small-molecule/protein-therapeutics skills (autodock-vina, retrosynthesis, protein-binder-design, …) — drug-discovery-agent-skills
  • a docx-editor-zotero skill (edit .docx files without breaking Zotero citations) — adapted from claude-scientific-writer
  • an agentic-data-science-pipeline skill (plan/review/implement/verify/reflect loop for large multi-stage tasks) — adapted from agentic-data-scientist
  • a hyperparameter-optimization skill (pre-registered, verify-before-claiming search loop for tuning a DL/LLM model) — adapted from karpathy

  RESEARCHCRAFT_SKILLS_DIR (or a ~/scientific-agent-skills/skills checkout) still works as an override if you want a different catalogue instead — available on every preset

• notebook tool — log, read, and export a living lab notebook (JSONL under /.dsh/notebook/), shared across a subagent delegation tree, with a zip-bundle export alongside the plain Markdown one — every preset

• scientific_result tool — a structured, schema-validated "final finding" card (table or statistical-test), distinct from the notebook's running log — every preset

• Specialist briefs (code-reviewer, literature-researcher, …) for the DSH subagent tool, plus subagent_pro and subagent_vision — two more delegation tools pinned to a different model for unusually heavy reasoning and image-reading tasks respectively — see Subagent model routing — every preset

• image_generate tool for conceptual scientific figures (Gemini "nano banana" by default) — every preset

• sci_inspect tool for scientific file formats (chemistry, structure, mass spec, arrays, imaging, AnnData) — every preset

• latex_compile tool (.tex → PDF, bibtex/biber-aware) — every preset

• pdf_to_markdown tool (PDF → Markdown, via pdf-inspector) for literature-survey conversion of downloaded papers — every preset

• modal_run / runpod_run tools for remote GPU/CPU compute offload, plus bundled modal/runpod skills covering the rest of each CLI (Serverless endpoints, volumes/secrets, Hub templates, …) — see Remote compute — every preset

• workflow tool over a ~330-template research-task catalogue — every preset

• Academic search: Parallel, Firecrawl, Scite (MCP connectors), parallel_search / consensus_search (native REST tools), and paper_download (Unpaywall open-access PDF resolver) — ResearchCraft preset only

• Workspace semantic search via zvec-grep: mcp__zvec_grep__zvec_grep_search (local BM25 + vectors). First ResearchCraft start installs the zg CLI into ~/.dsh/zvec-grep. Indexing is off at session start by default (Settings → Index at session start); you can index later from chat, and the agent asks first when semantic search would help. While indexing, a progress bar with estimated time and Cancel is shown (no timeout) — exact lookup stays on native grep / glob — ResearchCraft preset only — see Workspace search

• Bundled agent-browser skill for interactive web browsing (navigate, log in, fill forms, download datasets), with screenshots delegated to subagent_vision — see Browsing the web — every preset

• A Settings → ResearchCraft API keys page for all of the above — no shell env vars required

API keys

Every credential below (PARALLEL_API_KEY, FIRECRAWL_API_KEY, CONSENSUS_API_KEY, SCITE_API_KEY, UNPAYWALL_EMAIL, GEMINI_API_KEY, MODAL_TOKEN_ID, MODAL_TOKEN_SECRET, RUNPOD_API_KEY, ZVEC_GREP_API_KEY) can be set two ways:

• Settings → ResearchCraft API keys in the DSH web UI — type a key, Save. Persisted in the profile's settings.yaml; a blank field always means "keep the current value", Clear removes it.
• Shell environment variable — takes priority over Settings when both are set.

The same Settings page also has an Image model dropdown for IMAGE_MODEL — not a credential, so it isn't password-masked and applies immediately on selection rather than needing Save (see Image generation). It also has two more model-id dropdowns, Complex-task model (SUBAGENT_MODEL_COMPLEX) and Image-reading model (SUBAGENT_MODEL_VISION) — not credentials either, but these two behave like the MCP connectors below, not like Image model: they need a restart to apply (see Subagent model routing). zvec-grep embedding (ZVEC_GREP_EMBEDDING) is the same restart-needed dropdown: it is passed into zg server on at mount time. Index at session start (ZVEC_GREP_AUTO_INDEX, default No) is live for the next ResearchCraft session — no restart (see Workspace search).

Tools that call resolveEnv() per invocation (image_generate, modal_run, runpod_run, consensus_search, parallel_search, paper_download) pick up a Settings change on the very next call, no restart needed.

The MCP connectors (Parallel, Firecrawl, Scite, zvec-grep) and the two subagent-model fields are different: the researchcraft agent preset mounts once as a standing composition shared by every chat session for the life of the running dsh process, so a change only reaches them after you stop and restart dsh itself — a new chat session on the same running process is not enough. consensus_search and parallel_search aren't MCP connectors — see below — so they don't have this restart requirement.

Also make sure the chat session is actually on the ResearchCraft preset. The MCP connectors, native academic-search tools (consensus_search, parallel_search), and mcp__zvec_grep__zvec_grep_search are wired into the researchcraft agent preset only; a session left on the default preset (Standard/PTC/etc.) has none of them, and calling one fails with tools[name] is not a function. Check the preset selector next to the session title (top of the message box for a new chat, top-left of an existing one) reads "ResearchCraft" before asking the agent to search.

Workspace search

zvec-grep (zg) is the local-first hybrid search layer on the ResearchCraft preset: BM25 + vectors over an on-disk index, exposed as mcp__zvec_grep__zvec_grep_search. Exact words, quotes, identifiers, filenames, regexes, and exhaustive hit lists stay on the preset's native grep / glob (@deepseek-ai/dsh-tool-fs-search). Open-web and literature search stay on Parallel / Consensus / Firecrawl / Scite — zg is workspace-only.

You do not install zg yourself. The first time the ResearchCraft preset mounts after dsh plugin add, the plugin runs npm install --prefix ~/.dsh/zvec-grep @zvec/zvec-grep, starts zg server on (the loopback daemon), and mounts search over Streamable HTTP at http://127.0.0.1:7999/mcp — no second restart. That first start can take several minutes (npm + later the ~130 MB Potion model). Later starts reuse ~/.dsh/zvec-grep and start the daemon again. Stopping dsh runs zg server off, so the daemon does not stay up in the background. Override with ZVEC_GREP_CLI if you already have zg on PATH. If install or the daemon fails, the rest of the preset still loads and the search tool is absent (a warning is logged).

The plugin talks to the daemon over HTTP rather than zg server --stdio. zg 0.2.1's stdio bridge can exit with zvec-grep daemon stopped while the stdio bridge was connected while the daemon is still healthy (zvec-grep#106); DSH would then reconnect the child and print that error repeatedly.

Indexing is opt-in. Settings → ResearchCraft API keys → Index at session start defaults to No. When No (the default), a new chat does not index; you can still type “index this workspace” in the chat, and whenever semantic search would help the agent asks first (and only indexes if you say yes). When Yes, opening a ResearchCraft session indexes that workspace in the background if no index exists yet (zg index --embedding local/potion-retrieval-32m, local, no API key).

While an index runs — from session start or from chat — the UI shows a progress bar with estimated time in Settings and in the session header, and Cancel is always available. There is no timeout. Existing indexes are left alone (no silent rebuild/drop). Home directory and / are not indexed. Indexes live in /.zvec-grep/; the model cache is ~/.zvec-grep/models (~130 MB once).

# only if you want to index by hand or pick a different local model
zg index --embedding local/potion-retrieval-32m    # default — papers / notes / mixed
zg index --embedding local/potion-code-16m-v2      # smaller (~65 MB model), code-heavy trees
zg status --check-ready

Every MCP call needs an absolute root (the session working directory). Relative paths fail. The native zvec_index tool (start / status / cancel) is what the agent uses instead of shelling out to zg index.

Setting / env	What it does
ZVEC_GREP_AUTO_INDEX	yes / no. Index this workspace when a ResearchCraft session opens. Default no. Live for the next session (no restart).
ZVEC_GREP_EMBEDDING	Default model id for new indexes. Unset means local/potion-retrieval-32m. Existing indexes keep their stored model. Restart dsh after changing — the next start brings up a fresh daemon with the new value.
ZVEC_GREP_API_KEY	Not used with the default local Potion models. Only if you opt into a remote (Qwen) embedding provider.
ZVEC_GREP_CLI	Absolute path to zg or to @zvec/zvec-grep's dist/cli/index.js. Env only.

The loopback daemon under ~/.zvec-grep/daemon/ is started with the ResearchCraft preset and stopped when dsh exits. You do not need zg server off by hand.

Install, index, and routing details for the agent are in the bundled zvec-grep skill (skills/zvec-grep).

Academic search

Three literature/web MCP servers are wired into the researchcraft preset and surface as mcp__parallel__*, mcp__firecrawl__*, mcp__scite__* tools:

Connector	Key	Without it
Parallel — mcp__parallel__web_search (search fallback, always basic) and mcp__parallel__web_fetch (read a URL)	PARALLEL_API_KEY (required)	Connector stays disabled. The key is always sent as a Bearer token so MCP calls are not on the anonymous rate limit.
Firecrawl — scrape/crawl/extract	FIRECRAWL_API_KEY (optional)	Works keyless, rate-limited
Scite — Smart Citations, retraction/correction checks, evidence datasets (patents, clinical trials, grants, drug safety, …)	SCITE_API_KEY (required)	Connector stays disabled

parallel_search is the primary Parallel search tool: a native REST call to POST /v1/search (x-api-key auth). It requires `PARAL