dsh-web-search-ddg
Keyless DuckDuckGo web search for DeepSeek Harness.
No API key. No account. No credit card. No tokens burned — the search runs as a
plain HTTP scrape of DuckDuckGo's lite results page, registered through the
harness's public ctx.web provider seam.
Why
DeepSeek Harness is free software. The agent running inside it can be free.
Everything a coding agent actually needs — files, shell, git, planning,
subagents — is local and costs nothing. Web search was the one wall: every
shipped provider requires a paid account (DeepSeek platform key, Exa,
Perplexity), while closed tools like Claude Code and ChatGPT bundle live search
into their subscriptions.
This plugin exists because "free" shouldn't mean "free, except the internet."
Search should not be the feature that forces your first API signup and your
first metered bill. It runs on the same public page your browser uses — no
quota to exhaust, no key to rotate, nothing to cancel when the trial ends.
And because it lives in your checkout rather than someone's endpoint, it is
yours to audit, patch, and keep: free software deserves free search.
Features
- Zero credentials —
available() is a pure config-shape check; nothing to store in the credential vault
- Zero model tokens — unlike the in-box DeepSeek provider, one search never costs an auxiliary model turn
- Strict mode — only DuckDuckGo result-marked anchors are accepted; zero parsed results raises
WEB_PROVIDER_ERROR, never a silent empty success
- Redirect-aware parsing —
/l/?uddg= wrappers unwrapped to real targets; internal duckduckgo.com links dropped; duplicate URLs deduplicated
- Entity-safe text — numeric/hex/named entities decoded with
& last, so escaped text never double-decodes
- GET and POST — POST form fallback for deployments where GET trips anomaly checks
- Snippet pairing done right — each snippet attaches to its preceding anchor only
Install
Into a profile (recommended)
dsh plugin --profile my-profile add github:tatselkrik/dsh-web-search-ddg
Built artifacts are committed under lib/, so no build-script allowance is
needed. The bundle inserts itself into the ctx.web registry; when it is the
only usable search provider it is auto-selected. To pin it explicitly, add to
your profile's cordis.patch.yml:
- id: web
name: '@deepseek-ai/dsh-web'
config:
searchProvider: duckduckgo
Then start with your profile:
dsh --profile my-profile web
Inside a source checkout (in-tree variant)
For a Harness development checkout that already contains the in-tree package,
replace packages/web/web-search-ddg/src/ with this repository's src/, then
rebuild from the Harness root:
pnpm exec tsc -b packages/web/web-search-ddg
pnpm exec vitest run packages/web/web-search-ddg
A fresh in-tree integration also needs the package added to the Harness
workspace and build graph. For normal use, the profile installation above is
the supported route and requires no source-tree changes.
Config
| Key | Default | Meaning |
|---|
baseURL | https://lite.duckduckgo.com/lite/ | The lite results page. Extra params on the base (e.g. ?kl=us-en) are preserved. |
limit | 10 | Provider-level cap on sources per search; the seam still enforces the tool request's maxResults. |
method | get | Query verb. GET sends q in the URL; POST sends it only as a URL-encoded form body. |
timeoutMs | 15000 | Wall-clock cap per request, independent of caller cancellation; timeouts surface as WEB_PROVIDER_ERROR. |
Override any of them via a patch row:
- id: web-search-ddg
name: dsh-web-search-ddg
config:
limit: 5
method: post
Security and performance notes
Security
- No secrets, no vault access — the provider reads nothing from the credentials domain; there is nothing to leak.
- No install-time code execution — no
prepare/postinstall scripts; lib/ ships committed, so installs run zero build scripts (the supply-chain vector the harness docs warn about).
- Bounded dependency ranges — every published dependency has an explicit caret range, never
*; align them with your running harness version if you prefer exactness.
- Input handling — GET queries travel in the encoded
q URL parameter; POST queries travel only in the encoded form body. Results are parsed as inert text (never evaluated), and unmarked/internal/non-http targets are rejected before they can become citations.
- Parser honesty — extraction is regex-based, not a full HTML parser: adequate for the lite page's flat markup, and it only ever sees what DuckDuckGo returns. Treat result titles/snippets like any search tool's output — untrusted text entering model context.
- Privacy — each query is visible to DuckDuckGo Inc. (that's how searching works); nothing else receives anything, and no telemetry exists in this package.
Performance
- One small HTTP round trip per search (~20–60 KB lite page); parsing is a single linear token pass.
- Stateless between calls; per-request wall clock capped at
timeoutMs (default 15 s) even if a consumer forgets cancellation.
- Result count bounded by
limit before the seam applies its own maxResults, so context cost stays predictable.
- Contrast: the in-box DeepSeek provider pays a full auxiliary model turn (seconds + tokens) per search; this pays one fetch.
Known limitations
- Unofficial endpoint — no SLA. Aggressive bursts can earn 403s/CAPTCHAs; markup changes break parsing loudly until patched.
- No published dates — the lite page does not expose them.
- Bing-index depth — result quality tracks DuckDuckGo's index, slightly behind Google for niche technical queries.
- Peer dependency versions — declared with loose ranges against the harness packages; if you hit class-identity issues (
WebError instanceof) between a registry-installed copy and an in-box copy, pin dependencies to match your running harness version.
Development
pnpm install --frozen-lockfile
pnpm run typecheck
pnpm test # 24 tests
pnpm run build # regenerate committed lib/
git diff --exit-code -- lib
lib/ is committed so end users never need a build step.
License
MIT
