nicremo/dsh-cli

Unofficial community project. dsh-cli is not affiliated with, endorsed by or sponsored by DeepSeek. “DeepSeek Harness” is a trademark of DeepSeek and is used here only to describe compatibility.

Why

I use DeepSeek Harness (dsh) mostly for research and for many parallel sessions: ten research questions at once, collecting screenshots of articles, scroll videos of blog posts, stock footage. DeepSeek is fast and cheap, which makes it a great worker pool. What was missing is a way for my main coding agent to drive it: start the sessions, wait for them, read the results, follow up. That is what dsh-cli does.

dsh-cli is agent first. Every command is non-interactive, returns at once, prints compact text or --json, and uses stable exit codes. It ships an Agent Skill that teaches Claude Code, Codex, OpenCode, Pi and other harnesses when and how to delegate work to DeepSeek Harness.

Features

• Parallel research batches: dsho research "q1" "q2" ... runs one worker per question; each writes report.md and sources.json, dsho collect merges them into one INDEX.md.
• Material gathering: dsho materials "brief" runs one worker per kind (screenshots, scroll videos, news articles, stock footage, stock photos) with a manifest.json that records source and licence for every file.
• Live in the DSH web UI: when dsh web is running, every job is a real session in that UI. A batch becomes its own workspace, every session gets a readable title, and you can watch or step in.
• Headless fallback: without the UI, each job runs in its own headless dsh process with a lean profile (orchestra) that reuses your research MCP servers.
• Steer like a human would: wait, status, logs -f, result, files, continue (same session, same folder), cancel.
• Deterministic captures: dsho capture shot|scroll takes clean screenshots and smooth 1080p scroll videos with Playwright (cookie banners dismissed, overlays hidden, ad networks blocked, watchdog for hanging pages).
• No daemon: state is plain JSON in ~/.dsho/; detached runner processes keep jobs alive after the calling shell exits.

How it works

flowchart LR
    A["Your agent(Claude Code, Codex, OpenCode, Pi)"] -- "dsho research ... --json" --> C[dsh-cli]
    C -- "DSH web UI running" --> W["dsh websessions in one workspace"]
    C -- "otherwise" --> H["headless dshone process per job"]
    W --> F[("workspace folderreport.md, manifest.json, ...")]
    H --> F
    C -- "dsho wait / collect" --> F
    F -- "INDEX.md" --> A

1. Your agent calls dsho (usually through the bundled skill).
2. dsh-cli creates a workspace folder and one job per task, then hands each job to a detached runner and returns ids at once.
3. The runner either creates a session in the running DSH web UI (through its HTTP API) or starts dsh --profile orchestra --json - with the task on stdin.
4. Events are recorded in ~/.dsho/jobs//events.jsonl, progress in job.json, the final answer in result.md.
5. Your agent waits with dsho wait, reads dsho result or dsho collect, and continues sessions with dsho continue.

Requirements

• Node.js >=22.19
• DeepSeek Harness, installed with npm install -g @deepseek-ai/dsh (or a source checkout), logged in once
• Optional, for dsho capture: Python 3 with Playwright (pip install playwright && python3 -m playwright install chromium) and ffmpeg
• macOS or Linux

Install

npm install -g dsh-cli && dsho setup

dsho setup creates the headless dsh profile orchestra and installs the dsh-orchestration skill into ~/.agents/skills (read by OpenCode and other harnesses) with links for Claude Code, Codex and Pi when they are installed. Run dsho doctor to check everything.

Only want the skill? npx skills add nicremo/dsh-cli works too, but the skill needs the CLI.

Two commands are installed: dsh-cli and the short alias dsho.

Quick start

dsho ui start                       # optional: start the DSH web UI to watch jobs live
dsho research "AI agent pricing 2026" "State of MCP servers" "Prompt caching strategies" \
  --depth standard -C ~/dsh-workspaces/ai-2026
dsho wait last-batch --timeout 9m   # exit code 4: still running, wait again
dsho collect last-batch             # writes ~/dsh-workspaces/ai-2026/INDEX.md

dsho run -w "Summarize the release notes of Astro 6"           # one task, print the answer
dsho materials "Electric cars in Europe, neutral tone" --kinds screenshots,articles,stock-video
dsho continue last "Add three sources from 2026 and update report.md"
dsho capture scroll https://example.com/blog/post -o post.mp4 --duration 12

Use it from your agent

After dsho setup your agents know the skill. Ask in plain language:

Use DeepSeek Harness to research these 10 topics in parallel and give me a summary.

Get me screenshots of recent news articles and some stock footage about solar power for my video.

The skill tells the agent to start a batch, wait in steps that fit its shell timeout, read INDEX.md, spot-check the results and follow up where needed. dsho guide prints the same manual for any agent without skill support.

Commands

References: job id, batch id, unique prefix, name, last, last-batch. Common options: -C workspace folder, -m flash|pro|v4-flash|vision, --effort off|low|high|max, -t time limit, -p parallelism, -b auto|web|headless backend. Every command has --help.

JSON and exit codes

Every command accepts --json and prints one object: { "ok": true, ... } or { "ok": false, "error", "code", "hint" }.

The DSH web UI backend

When the web UI is reachable, dsh-cli talks to its HTTP API (POST /api//): it registers the workspace folder, creates a session in it, names it, optionally selects a model, sends the task, and polls the session log until the turn that answers the task has ended. The session log is translated into the same event format the headless mode produces, so logs, status and result work the same everywhere.

• dsho ui start starts dsh web in the background, captures the token URL it prints and logs in.
• If you start dsh web yourself, pass the URL it prints once: dsho ui login "http://127.0.0.1:3080/?token=...". The resulting cookie is stored in ~/.dsho/web-auth.json (mode 0600) and stays valid for 30 days, also across restarts.
• -b web makes a missing UI an error instead of falling back to headless.

The headless backend and dsho setup

Headless jobs run dsh --profile orchestra --json - in the job folder. dsho setup builds that profile from the shipped headless template plus:

• MCP servers copied from another profile (default web): --mcp research (firecrawl, Brave, context7, Exa, Tavily, Perplexity, Jina and similar; default), all, none or a comma list of ids. Copied rows can contain API keys, so the profile file is written with mode 0600 and nothing is printed.
• A curated skill folder (~/.dsh/skills-orchestra, symlinks into ~/.agents/skills) instead of your whole skill pool, which keeps the worker prompt about a third smaller. --skills a,b,c picks others, --skills all keeps dsh defaults.
• .dsho-workspace as an extra project root marker, so workers in batch subfolders still load the workspace AGENTS.md.

Configuration

dsho config set stores settings in ~/.dsho/config.json. Environment variables win over the file.

Other variables: DSHO_HOME (state folder, default ~/.dsho), DSH_HOME (dsh home, default ~/.dsh), DSHO_WEB_TOKEN_URL / DSHO_WEB_TOKEN_FILE (token URL of the web UI).

Files

~/.dsho/
  config.json            settings
  web-auth.json          cookie for the DSH web UI (0600)
  jobs//             job.json, task.md, events.jsonl, stderr.log, result.md
  batches//          batch.json
  logs/                  runner logs
/
  AGENTS.md, .dsho-workspace
  /              one folder per batch job
  INDEX.md               after dsho collect

Troubleshooting

Safety

dsh workers can run shell commands; many setups run dsh with full access and no sandbox. Keep tasks scoped to the workspace and never delegate deletes, deploys, git pushes or anything that touches secrets. Material found by workers is not automatically yours to publish: check licence and source in manifest.json. See SECURITY.md for reporting vulnerabilities.

Development

git clone https://github.com/nicremo/dsh-cli && cd dsh-cli
npm install
npm test            # node:test with a fake dsh and a fake web UI; never touches your real setup
node bin/dsho.mjs help

Architecture notes: docs/architecture.md. Contributions are welcome, see CONTRIBUTING.md.

License

MIT. The logos in the demo animation belong to their owners (Anthropic, OpenAI, OpenCode, Pi, DeepSeek) and only identify compatible tools.