{
  "markdown": "# DeepThonk\n\n*thonk harder, not richer.*\n\nDeepThonk implements the OpenDeepThink algorithm (Zhou et al., 2026, [arXiv:2605.15177](https://arxiv.org/abs/2605.15177)) as a budget-friendly, provider-neutral \"deep think / pro mode\" wrapper, with first-class DeepSeek support. See [Acknowledgments](#acknowledgments).\n\nDeepThonk 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.\n\n**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](https://github.com/linxule/deepthonk/blob/main/docs/customization.md) for the full agent-composable surface.\n\nUse 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.\n\n## Quickstart\n\nRequires **Node ≥ 22.13**.\n\nRun without installing:\n\n```bash\nnpx -y deepthonk plan --profile paper\nnpx -y deepthonk run --provider fake --profile quick \\\n  --task \"Find the smallest positive integer divisible by 3, 4, and 5.\" \\\n  --out runs/test-quick\nnpx -y deepthonk inspect runs/test-quick\n```\n\nOr install globally:\n\n```bash\nnpm install -g deepthonk\ndeepthonk plan --profile paper\n```\n\nThe 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](#development).\n\n> 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](#acknowledgments) for the canonical paper and Python reference.\n\n## Setup\n\nCreate a reusable local config:\n\n```bash\ndeepthonk setup \\\n  --provider deepseek \\\n  --api-key-env DEEPSEEK_API_KEY \\\n  --fast-model deepseek-v4-flash \\\n  --judge-model deepseek-v4-pro\n```\n\nBy 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.\n\n## DeepSeek\n\n```bash\nexport DEEPSEEK_API_KEY=...\ndeepthonk run \\\n  --task task.md \\\n  --profile paper \\\n  --provider deepseek \\\n  --generator-model deepseek-v4-flash \\\n  --mutator-model deepseek-v4-flash \\\n  --judge-model deepseek-v4-pro \\\n  --out runs/task-paper\n```\n\nDeepSeek 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.\n\nBefore paid runs, inspect cost shape and resolved config:\n\n```bash\ndeepthonk plan --config ~/.config/deepthonk/config.yaml\ndeepthonk run --task task.md --config ~/.config/deepthonk/config.yaml --profile quick --dry-run\n```\n\nStart 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`.\n\n## OpenAI-Compatible Providers\n\n```bash\nexport DEEPTHONK_API_KEY=...\ndeepthonk run \\\n  --task task.md \\\n  --profile balanced \\\n  --provider openai-compatible \\\n  --base-url https://provider.example.com/v1 \\\n  --api-key-env DEEPTHONK_API_KEY \\\n  --generator-model cheap-model \\\n  --judge-model strong-model\n```\n\nThe 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.\n\nProvider 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:\n\n```bash\nexport OPENROUTER_API_KEY=...\ndeepthonk run \\\n  --task task.md \\\n  --profile balanced \\\n  --provider openrouter \\\n  --generator-model openrouter/auto \\\n  --mutator-model openrouter/auto \\\n  --judge-model openrouter/auto\n```\n\nFor mixed-provider runs, use YAML config and override individual roles under `providers`, especially `judge`.\n\nOptional `finalizer_model` / `--finalizer-model` can post-process the ranked winner. Leave it unset when you want the raw ranked answer as the final artifact.\n\n## MCP\n\nThe 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.\n\nDeepThonk is listed on the [MCP Registry](https://registry.modelcontextprotocol.io) 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.\n\nProvider 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.\n\nMCP 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.\n\n### Claude Code\n\n```bash\nclaude mcp add deepthonk \\\n  -e DEEPSEEK_API_KEY=$DEEPSEEK_API_KEY \\\n  -- npx -y deepthonk serve-mcp --transport stdio\n```\n\nUse `-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.\n\n### Claude Desktop\n\nConfig 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"deepthonk\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"deepthonk\", \"serve-mcp\", \"--transport\", \"stdio\"],\n      \"env\": {\n        \"DEEPSEEK_API_KEY\": \"sk-...\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after editing.\n\n### Cursor\n\nProject-scoped: `.cursor/mcp.json` in the workspace. User-global: `~/.cursor/mcp.json`. Same JSON shape as Claude Desktop:\n\n```json\n{\n  \"mcpServers\": {\n    \"deepthonk\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"deepthonk\", \"serve-mcp\", \"--transport\", \"stdio\"],\n      \"env\": { \"DEEPSEEK_API_KEY\": \"sk-...\" }\n    }\n  }\n}\n```\n\n### Other MCP hosts (stdio)\n\nAny host that speaks MCP stdio launches:\n\n```bash\nnpx -y deepthonk serve-mcp --transport stdio\n```\n\nwith 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.\n\n### Streamable HTTP\n\nFor local web hosts, or when stdio isn't available:\n\n```bash\ndeepthonk serve-mcp --transport http --port 3333 \\\n  --max-active-jobs 2 --max-queued-jobs 32\n```\n\nThe 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.\n\n### Tools\n\n| Tool | Purpose |\n|---|---|\n| `deepthonk.plan` | Estimate calls and sequential rounds for a profile (no model calls). Use before paid runs. |\n| `deepthonk.start` | Start a run in the background; returns `run_dir`, `job_id`, and job-scoped artifact resources. |\n| `deepthonk.status` | Poll job status from a `run_dir`. |\n| `deepthonk.result` | Return final summary + winner once a job is complete. |\n| `deepthonk.cancel` | Request cancellation by writing `cancel.json` into the run directory. |\n| `deepthonk.lock_inspect` / `deepthonk.lock_reclaim` | Inspect lock ownership and explicitly reclaim only an exact fingerprint. |\n| `deepthonk.repair_budget` | Replace legacy `[redacted]` numeric budget fields with explicit original values. |\n| `deepthonk.run` | Blocking convenience: start + await completion in one call. Prefer `start` + polling for long-running jobs. |\n| `deepthonk.rank` | Rank a user-supplied candidate set with pairwise judging + Bradley-Terry (skip generation). |\n| `deepthonk.mutate` | Mutate one supplied candidate with critique (one-shot). |\n| `deepthonk.resume` | Detect whether a run can be resumed; with `continue: true`, replay from the last validated phase boundary. |\n| `deepthonk.export` | Export run summary or full trace in JSON or markdown. |\n| `deepthonk.profile_list` | List saved named profile bundles. |\n| `deepthonk.profile_show` | Show one saved profile; manually edited secret-shaped values are rejected on load. |\n| `deepthonk.profile_save` | Save a reusable named profile bundle. |\n| `deepthonk.profile_delete` | Delete a saved named profile bundle. |\n\nAll tools accept inline provider/model fields, or `config_path` pointing at a DeepThonk YAML config.\n\n### Resources\n\n- `deepthonk://runs` — JSON index of all runs in `runs/`.\n- `deepthonk://runs/{run_id}/summary` — run summary (JSON).\n- `deepthonk://runs/{run_id}/config` — redacted run config (JSON).\n- `deepthonk://runs/{run_id}/{candidates|comparisons|scores|usage|trace}` — per-phase and per-call NDJSON.\n- `deepthonk://runs/{run_id}/population/{generation}` — population snapshot for a generation (JSON).\n- `deepthonk://runs/{run_id}/{winner|final}` — text artifacts.\n- `deepthonk://runs/{run_id}/status` — run state (JSON).\n- `deepthonk://runs/{run_id}/prompts/{sha256}` — verified content-addressed rendered prompt (JSON).\n- `deepthonk://runs/{run_id}/trace-v2` — bounded phase index; follow its manifest, commit, checkpoint-index, and checkpoint URIs to inspect every receipt.\n- `deepthonk://jobs/{job_id}/{status|result|config|candidates|comparisons|scores|usage|trace|final|winner}?run_dir=...` — job-scoped lookup; the `run_dir` query param is required.\n- `deepthonk://jobs/{job_id}/population/{generation}?run_dir=...` — job-scoped population snapshots before or after completion.\n- Job results also include `prompt_template` and `trace_v2_template` for the job-scoped equivalents.\n- `deepthonk://runs/{run_id}/{resource}/page/{cursor}` and job equivalents — opaque bounded pages. Whole reads are limited to 1 MiB; pages contain at most 1,000 records and 1 MiB.\n\n### Prompts\n\nFour templates mirror the core loop: `deepthonk/generate`, `deepthonk/compare`, `deepthonk/mutate`, `deepthonk/finalize`. Hosts can render them directly to drive the algorithm by hand without invoking the tool surface.\n\n### Limits\n\n`deepthonk.resume` reports trace state by default. With `continue: true`, it validates phase order, artifacts, run/provider/model identity, scores, usage, deterministic pair schedules, trace-v2 receipts, and phase commits. Valid incomplete-phase receipts are reused without another provider call. MCP Sampling model hints are preferences and token usage may be unavailable. Its shared adaptive limiter starts at 4; direct providers start at 8.\n\n## Customization\n\nEvery algorithm dimension is reachable through MCP arguments and CLI flags:\n\n- **Population shape**: `n`, `k`, `t`, `m` — override profile defaults inline.\n- **Algorithm constants**: `lambda`, `sample_temperature`, `mutate_temperature`, `judge_temperature`.\n- **Prompt style**: `general` or `paper-programming`.\n- **Per-phase prompt templates**: override `generate`, `compare`, `mutate`, or `finalize` with custom system/user templates and variable substitution (`{task}`, `{rubric}`, `{candidate}`, `{candidateA}`, `{candidateB}`, `{critique}`). CLI supports `--prompts <yaml>` and `--prompts-json <json>`; MCP supports inline `prompts`. Unknown variables throw a fail-fast error at run-start.\n- **Concurrency**: per-phase caps for `generate`, `judge`, `mutate`.\n- **Provider backpressure**: `provider_max_concurrency` sets the recovery ceiling for the shared adaptive provider-route limiter.\n- **Per-call output bounds**: independent generation, mutation, judge, and finalizer token caps.\n- **Final ranking schedule**: seeded `all-pairs` or `k-regular`, with an explicit logical call cap.\n- **Critique bound**: deterministic deduplication and a configurable aggregate-character cap before mutation.\n\nExample agent call (MCP), no YAML file required:\n\n```json\n{\n  \"task\": \"Draft a concise non-solicitation clause for a senior sales employee.\",\n  \"profile\": \"balanced\",\n  \"n\": 6, \"t\": 1,\n  \"provider\": \"deepseek\",\n  \"judge_model\": \"deepseek-v4-pro\",\n  \"prompts\": {\n    \"generate\": { \"system\": \"You are an experienced employment-law attorney.\" },\n    \"compare\":  { \"system\": \"Prefer enforceable clauses under California law. Return strict JSON only.\" }\n  }\n}\n```\n\nCLI accepts the same surface. Use `--prompts <yaml>` for reusable prompt files or `--prompts-json <json>` for one-off inline overrides. MCP and CLI both merge over any `--config`/`config_path` YAML defaults.\n\nSave reusable bundles as **named profiles** at `~/.config/deepthonk/profiles/<name>.yaml` and load them with `--profile-name <name>` (CLI) or `profile_name: \"<name>\"` (MCP). A named profile is a standalone bundle that replaces the main config file for that run; CLI flags and MCP inline arguments still override fields inside it. See `examples/profiles/legal-drafting.yaml` for the shape. The [Customization guide](https://github.com/linxule/deepthonk/blob/main/docs/customization.md#managing-named-profiles) covers listing, showing, saving, and deleting named profiles from both CLI and MCP.\n\nSee the [Customization guide](https://github.com/linxule/deepthonk/blob/main/docs/customization.md) for the complete variable contract, the compare-phase JSON safety rule, the named-profile schema, and three worked examples. Per-role provider routing (`providers.judge.provider = openrouter`) and per-model pricing remain YAML-only — they're nested structured config, not inline ergonomics.\n\n## Trace Files\n\nA successful run writes:\n\n```txt\nruns/{run_id}/\n  config.json\n  events.jsonl\n  candidates.jsonl\n  comparisons.jsonl\n  scores.jsonl\n  usage.jsonl\n  population-0.json\n  population-{generation}.json\n  manifests/*.json\n  checkpoints/*/*.json\n  commits/*.json\n  summary.json\n  artifacts/winner.txt\n  artifacts/final.txt\n  artifacts/prompts/<sha256>.json  # only when prompt capture is enabled\n```\n\n`status.json` is written when the run is launched through MCP `deepthonk.start` (so async clients can poll). `cancel.json` is written only when cancellation is requested. A `run.lock` file is held for the duration of the run.\n\nTrace rows are batch-appended through a single writer and flushed before lifecycle boundaries. Per-item output and usage receipts are written atomically before a phase commit. If a run is killed mid-tournament, trace-v2 resume validates and reuses completed receipts, re-materializes their JSONL rows, and calls the provider only for missing or invalid work.\n\n`usage.jsonl` carries one row per provider call (generator, judge, mutator, finalizer) with phase/role/provider/model/token/USD/latency/retry. It contains no prompt content. `jq` over `usage.jsonl` is the simplest way to break a run's cost down by role.\n\nPrompts and raw model outputs are off by default. When prompt capture is enabled, candidate/comparison rows carry a `promptRef` and identical rendered prompts share one content-addressed blob under `artifacts/prompts/`; the full prompt is not repeated in every JSONL row or receipt. API keys are never written. Candidate answers, critiques, scores, and final artifacts are trace data and are stored/exported by design, so do not use a shared run directory for sensitive tasks unless that is acceptable.\n\n## Development\n\n```bash\npnpm install\npnpm run build\npnpm test\npnpm run lint\n```\n\nThis repository is source-only. Generated run traces, paper notes, build output, coverage, logs, and `node_modules` are intentionally ignored.\n\nRelease publishing is tag-triggered through npm Trusted Publishing. See [docs/release.md](https://github.com/linxule/deepthonk/blob/main/docs/release.md) before bumping versions or pushing a `v*` tag.\n\nKnown limits for this release:\n\n- Trace-v1 resume replays an interrupted phase wholesale; per-item reuse requires a trace-v2 run created by DeepThonk v0.2.\n- HTTP Sampling is blocking-only. Use stdio or a direct provider for background `deepthonk.start` work.\n- `maxUsd` requires known model pricing; add explicit prices in YAML for custom providers and model IDs. Optional fields `longContextThresholdTokens`, `inputUsdPerMillionLong`, and `outputUsdPerMillionLong` enable tiered pricing for models with a long-context surcharge (e.g., Gemini at 200K input tokens). Cache hit/miss rates remain flat.\n\n## Acknowledgments\n\nDeepThonk is an independent TypeScript reimplementation of the OpenDeepThink algorithm. It is not a fork; no source code from the reference implementation is vendored. Credit for the algorithm, the benchmark methodology, and the empirical results belongs to the paper authors.\n\n- **Paper**: Shang Zhou, Wenhao Chai, Kaiyuan Liu, Huanzhi Mao, Qiuyang Mang, Jingbo Shang. *OpenDeepThink: Parallel Reasoning via Bradley–Terry Aggregation*. arXiv:2605.15177, 2026. <https://arxiv.org/abs/2605.15177>\n- **Reference Python implementation**: <https://github.com/ZhouShang0817/open-deep-think> (MIT). This is the authors' code release and the canonical implementation for reproducing paper results (CF-73, HLE).\n\nDeepThonk's contribution is an integration layer: a provider-neutral TypeScript core, an MCP server, a CLI, structured trace artifacts, and budget enforcement. The algorithm itself is theirs.\n",
  "bytes": 19972,
  "sha": "f3b13f4ed45d6920e9ca1480e99eede8c3f5f6b7e14bb66f275f01a30756fea3",
  "repo_slug": "linxule/deepthonk",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_linxule_deepthonk_348e3f0e/readme"
}