DeepThonk

DeepThonk

*thonk harder, not richer.*

DeepThonk implements the OpenDeepThink algorithm (Zhou et al., 2026, arXiv:2605.15177) as a budget-friendly, provider-neutral "deep think / pro mode" wrapper, with first-class DeepSeek support. See Acknowledgments.

DeepThonk runs a population of candidate answers through pairwise judging, Bradley-Terry ranking, critique-guided mutation, elite preservation, and a final dense ranking pass. The CLI and MCP server both call the same TypeScript core engine.

Designed for agents. Every algorithm dimension — population shape (n, k, t, m), regularization (lambda), per-phase temperatures, prompt style, and per-phase prompt templates — is reachable inline through MCP arguments and CLI flags. CLI can load prompt files with --prompts or inline JSON with --prompts-json; MCP accepts inline structured prompt args. Every intermediate artifact (config, candidates, populations, comparisons, scores, per-call usage, status) is exposed as an MCP resource so an agent can inspect any step. See Customization for the full agent-composable surface.

Use it for hard, verifiable reasoning, coding, planning, and synthesis where breadth plus judgment can beat one expensive single shot. Avoid it for highly subjective tasks where judge noise dominates.

Quickstart

Requires Node ≥ 22.13.

Run without installing:

npx -y deepthonk plan --profile paper

npx -y deepthonk run --provider fake --profile quick \ --task "Find the smallest positive integer divisible by 3, 4, and 5." \ --out runs/test-quick npx -y deepthonk inspect runs/test-quick

Or install globally:

npm install -g deepthonk

deepthonk plan --profile paper

The paper profile plans 285 model calls and 8 sequential rounds. Confirm budget and provider pricing before pointing it at paid models. The short alias dt is installed alongside deepthonk. Develop from source: see Development.

DeepThonk is an independent TypeScript reimplementation and practical integration layer; the published algorithm is the load-bearing part. Cost guarantees rely on provider pricing being present in config. Trace-v2 resume can reuse validated per-item receipts after a crash, while older traces replay an incomplete phase wholesale. The MCP HTTP transport remains loopback-only. The included acceptance smoke uses the deterministic fake provider and a toy task — it is not a CF-73 / HLE reproduction; see docs/ and Acknowledgments for the canonical paper and Python reference.

Setup

Create a reusable local config:

deepthonk setup \

--provider deepseek \ --api-key-env DEEPSEEK_API_KEY \ --fast-model deepseek-v4-flash \ --judge-model deepseek-v4-pro

By default this writes ~/.config/deepthonk/config.yaml. deepthonk run loads that file automatically when --config is not supplied. If you pass --api-key, setup stores it in ~/.config/deepthonk/env; otherwise it uses the named environment variable from your shell.

DeepSeek

export DEEPSEEK_API_KEY=...

deepthonk run \ --task task.md \ --profile paper \ --provider deepseek \ --generator-model deepseek-v4-flash \ --mutator-model deepseek-v4-flash \ --judge-model deepseek-v4-pro \ --out runs/task-paper

DeepSeek is implemented as an OpenAI-compatible profile using https://api.deepseek.com/v1. DeepThonk ships default USD pricing for deepseek-v4-flash and deepseek-v4-pro from the official DeepSeek pricing page, including cache-hit/cache-miss input rates. Model names and prices are still editable config because both can change.

Before paid runs, inspect cost shape and resolved config:

deepthonk plan --config ~/.config/deepthonk/config.yaml

deepthonk run --task task.md --config ~/.config/deepthonk/config.yaml --profile quick --dry-run

Start with --profile quick and consider --max-concurrency, --max-calls, --max-input-tokens, --max-output-tokens, --max-usd, and --request-timeout-ms before larger paid profiles. max_calls is reserved before dispatch and counts logical model invocations, including failed calls and invalid-JSON retries; provider-internal HTTP retries are reported separately. Token/USD totals are known only after responses and can overshoot by at most the active concurrency window. Plans keep nominal calls separate from finalizer and retry headroom in worst_case_calls.

OpenAI-Compatible Providers

export DEEPTHONK_API_KEY=...

deepthonk run \ --task task.md \ --profile balanced \ --provider openai-compatible \ --base-url https://provider.example.com/v1 \ --api-key-env DEEPTHONK_API_KEY \ --generator-model cheap-model \ --judge-model strong-model

The driver calls POST {base_url}/chat/completions and requests JSON mode for comparisons when supported. If a provider returns 400 or 422 with a body that mentions response_format or json, the driver retries without JSON mode, coordinates that capability probe across concurrent calls, and remembers the result for the process. Set supports_json_mode: false in YAML to disable JSON mode up front.

Provider names are flexible. For a custom OpenAI-compatible endpoint, use any provider label with --base-url, --api-key-env, and role-specific model flags. For OpenRouter:

export OPENROUTER_API_KEY=...

deepthonk run \ --task task.md \ --profile balanced \ --provider openrouter \ --generator-model openrouter/auto \ --mutator-model openrouter/auto \ --judge-model openrouter/auto

For mixed-provider runs, use YAML config and override individual roles under providers, especially judge.

Optional finalizer_model / --finalizer-model can post-process the ranked winner. Leave it unset when you want the raw ranked answer as the final artifact.

MCP

The MCP server exposes the same engine the CLI runs. Once wired into an MCP host, the host can plan budgets, kick off background runs, poll status, fetch winners, and stream structured trace artifacts — all through MCP tools, resources, and prompts.

DeepThonk is listed on the MCP Registry as `io.github.linxule/deepthonk` (since v0.2.1). Hosts that install by registry name resolve it to npx deepthonk serve-mcp automatically. For hosts that don't, the explicit configs below do the same thing by hand.

Provider API keys come from the host process's environment, not from DeepThonk's config alone. Each host handles env passthrough slightly differently — see the concrete patterns below. No key is required to start the server: with a sampling-capable host you can run provider: "sampling", and the fake provider needs no network at all.

MCP Sampling is supported as provider: "sampling" when the connected host advertises the MCP sampling capability. Blocking run, rank, and mutate work over stdio and stateful Streamable HTTP. HTTP background start rejects Sampling because nested Sampling must remain attached to the initiating request; stdio background runs and direct-provider HTTP background runs remain available. Sampling is not available from standalone CLI runs.

Claude Code

claude mcp add deepthonk \

-e DEEPSEEK_API_KEY=$DEEPSEEK_API_KEY \ -- npx -y deepthonk serve-mcp --transport stdio

Use -s user for cross-project scope or -s project to commit registration into .claude/. Verify with claude mcp list. See claude mcp --help for the authoritative flag set.

Claude Desktop

Config path: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows), ~/.config/Claude/claude_desktop_config.json (Linux). Add:

{

"mcpServers": { "deepthonk": { "command": "npx", "args": ["-y", "deepthonk", "serve-mcp", "--transport", "stdio"], "env": { "DEEPSEEK_API_KEY": "sk-..." } } } }

Restart Claude Desktop after editing.

Cursor

Project-scoped: .cursor/mcp.json in the workspace. User-global: ~/.cursor/mcp.json. Same JSON shape as Claude Desktop:

{

"mcpServers": { "deepthonk": { "command": "npx", "args": ["-y", "deepthonk", "serve-mcp", "--transport", "stdio"], "env": { "DEEPSEEK_API_KEY": "sk-..." } } } }

Other MCP hosts (stdio)

Any host that speaks MCP stdio launches:

npx -y deepthonk serve-mcp --transport stdio

with the relevant provider env vars set on the process. If you'd rather install globally, npm install -g deepthonk then use command: "deepthonk" directly. Refer to the host's MCP registration docs for the configuration shape.

Streamable HTTP

For local web hosts, or when stdio isn't available:

deepthonk serve-mcp --transport http --port 3333 \

--max-active-jobs 2 --max-queued-jobs 32

The server binds 127.0.0.1:3333 only and exposes stateful POST, GET, and DELETE at http://127.0.0.1:3333/mcp. Sessions use cryptographic IDs, expire after 30 idle minutes when no request is active, and are capped at 64. DNS rebinding protection is on (CVE-2025-66414): requests with Host headers outside 127.0.0.1:3333 / localhost:3333 are rejected. The wrapper also rejects non-JSON POSTs, non-loopback Origin headers, and Sec-Fetch-Site: cross-site before reading the body. It has no bearer auth. Do not expose this port through a reverse proxy without re-evaluating that trust boundary.

Tools

All tools accept inline provider/model fields, or config_path pointing at a DeepThonk YAML config.

Resources

• deepthonk://runs — JSON index of all runs in runs/.
• deepthonk://runs/{run_id}/summary — run summary (JSON).
• deepthonk://runs/{run_id}/config — redacted run config (JSON).
• deepthonk://runs/{run_id}/{candidates|comparisons|scores|usage|trace} — per-phase and per-call NDJSON.
• deepthonk://runs/{run_id}/population/{generation} — population snapshot for a generation (JSON).
• deepthonk://runs/{run_id}/{winner|final} — text artifacts.
• deepthonk://runs/{run_id}/status — run state (JSON).
• deepthonk://runs/{run_id}/prompts/{sha256} — verified content-addressed rendered prompt (JSON).
• deepthonk://runs/{run_id}/trace-v2