# DeepThonk: OpenDeepThink for Agents

URL: https://research-memex.org/docs/toolkit/deepthonk
Description: A TypeScript CLI and MCP server that wraps hard tasks in OpenDeepThink-style candidate generation, pairwise judging, mutation, and ranking.



*When one answer is too brittle, make the model argue with alternatives.*

DeepThonk implements the OpenDeepThink algorithm as a provider-neutral CLI and MCP server. It runs a population of candidate answers through pairwise judging, Bradley-Terry ranking, critique-guided mutation, elite preservation, and a final dense ranking pass. The point is not speed. It is spending controlled test-time compute on tasks where breadth plus judgment can beat one expensive single shot.

<ToolMeta slug="deepthonk" runtime="TypeScript / Node.js" note="Controlled test-time compute through candidate generation and judgment" />

The package is [`deepthonk`](https://www.npmjs.com/package/deepthonk) on npm, with `dt` as the short CLI alias. Current source version: [0.3.0](https://github.com/linxule/deepthonk). It requires Node.js 22.13 or newer. Algorithm source: OpenDeepThink, Zhou et al. ([arXiv:2605.15177](https://arxiv.org/abs/2605.15177)).

## Why it matters [#why-it-matters]

<Ledger
  caption="When DeepThonk earns its compute budget"
  sides="[
  {
    label: 'Use for',
    items: [
      'Hard reasoning tasks where a single response collapses too early.',
      'Coding and debugging plans that benefit from multiple candidate approaches before implementation.',
      'Literature synthesis where you want alternative framings ranked against an explicit rubric.',
      'Methodology design where critique-guided mutation can surface better versions of an initial design.',
    ],
  },
  {
    label: 'Avoid',
    items: [
      'Tiny questions.',
      'Subjective taste calls.',
      'Tasks where judge noise is likely to dominate.',
    ],
  },
]"
/>

DeepThonk spends many model calls by design; plan the budget before running.

## Tools [#tools]

The MCP server is intentionally inspectable. An agent can:

<KeyTable>
  | Surface                                                                                                     | Purpose                                                                                     |
  | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
  | `deepthonk.plan`                                                                                            | Estimate calls and rounds before spending money                                             |
  | `deepthonk.start` / `deepthonk.status` / `deepthonk.result`                                                 | Run long jobs asynchronously                                                                |
  | `deepthonk.run`                                                                                             | Blocking convenience for shorter jobs                                                       |
  | `deepthonk.rank`                                                                                            | Rank your own candidate set without generation                                              |
  | `deepthonk.mutate`                                                                                          | Improve one candidate with critique                                                         |
  | `deepthonk.resume`                                                                                          | Inspect resumability; with `continue: true`, recover from validated trace state             |
  | `deepthonk.export`                                                                                          | Export run summaries or full traces                                                         |
  | `deepthonk.profile_list` / `deepthonk.profile_show` / `deepthonk.profile_save` / `deepthonk.profile_delete` | Manage reusable named profile bundles                                                       |
  | `deepthonk://runs/...` resources                                                                            | Inspect config, candidates, comparisons, scores, usage, status, winner, and final artifacts |
  | `deepthonk://jobs/...` resources                                                                            | Fetch job-scoped artifacts when an async run returns a `job_id`                             |
</KeyTable>

<Aside label="WHY IT MATTERS">
  If a synthesis improves, you can inspect the candidates and judgments that produced it instead of treating the final answer as unexplained.
</Aside>

The resume path is conservative: it validates manifests, provider and model identity, artifacts, usage, receipts, and phase commits. Trace-v2 can reuse valid per-call output and usage receipts from an interrupted phase without another provider call, restoring their accounting exactly once. Trace-v1 replays the whole incomplete phase.

## Host support [#host-support]

DeepThonk exposes the same engine through a shell CLI and an MCP server. Use the CLI when you want a visible run directory. Use MCP when you want an agent to plan, start, poll, inspect, and export runs from inside its own workspace.

<HostSupport
  rows="[
{ host: 'Claude Code (CLI / Desktop)', status: 'full', note: 'claude mcp add deepthonk -- npx -y deepthonk serve-mcp --transport stdio' },
{ host: 'Codex CLI / Codex Desktop', status: 'full', note: 'codex mcp add deepthonk -- npx -y deepthonk serve-mcp --transport stdio' },
{ host: 'Claude Desktop (chat)', status: 'full', note: 'Add an npx -y deepthonk serve-mcp --transport stdio server to claude_desktop_config.json' },
{ host: 'Cursor / VS Code / Windsurf', status: 'full', note: 'Standard MCP stdio config' },
{ host: 'Any shell', status: 'full', note: 'npx -y deepthonk ... or npm install -g deepthonk' },
]"
/>

Provider API keys come from the host process environment. DeepSeek is first-class; OpenAI-compatible endpoints, OpenRouter, and host-provided MCP Sampling are also configurable.

Sampling carries three constraints:

* It needs a client that advertises the capability. Standalone CLI runs and mixed Sampling/direct routes are unsupported.
* Blocking `run`, `rank`, and `mutate` work over stdio or stateful Streamable HTTP; HTTP background `start` rejects Sampling, which must stay attached to the request that initiated it.
* Call caps still apply. Token and USD caps do not, because clients do not report standardized usage.

## Install [#install]

DeepThonk is published in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.linxule/deepthonk`. Registry-aware hosts resolve that entry to the npm package. Manual MCP configuration must include the `serve-mcp` argument: the bare `deepthonk` binary has no default action and exits after printing help.

Run without installing:

```bash
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
```

For paid providers, configure a reusable profile first:

```bash
deepthonk setup \
  --provider deepseek \
  --api-key-env DEEPSEEK_API_KEY \
  --fast-model deepseek-v4-flash \
  --judge-model deepseek-v4-pro
```

Then plan before you run:

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

DeepThonk separates phase concurrency from a process-shared provider ceiling. Direct-provider routes start at eight concurrent calls and Sampling starts at four. A provider `429` halves the live ceiling; successful calls restore it gradually, while queued calls remain FIFO and cancellation-aware. Phase and provider concurrency inputs are capped at 1,024.

Every model call also carries an output cap: 4,096 tokens by default for generation, mutation, and finalization, and 1,024 for judging. Final `all-pairs` ranking schedules above 100 judge calls require an explicit sufficient rank cap; invalid schedules fail before generation spends calls.

For MCP hosts, prefer `deepthonk.start` plus `deepthonk.status`/`deepthonk.result` for long jobs. `deepthonk.run` is the blocking convenience path. If you need HTTP transport for a local tool bridge, use `deepthonk serve-mcp --transport http --port 3333`. It binds loopback only and rejects non-loopback request origins. It has no bearer-auth boundary. Do not expose it through a proxy without re-evaluating that trust model.

## Part of Research Memex [#part-of-research-memex]

DeepThonk sits next to [Sequential Thinking](/docs/toolkit/sequential-thinking-mcp), not underneath it. Sequential Thinking gives a single model a structured scratchpad. DeepThonk creates and ranks many attempts. Use Sequential Thinking when you want one transparent reasoning chain; use DeepThonk when you want search, mutation, judging, and a trace of alternatives.

It also pairs naturally with [Vox](/docs/toolkit/vox-mcp). Vox gives you access to many models. DeepThonk gives you a repeatable protocol for spending more compute on a hard task.

Carrel status: Carrel does not install DeepThonk today. Add it manually when a project needs OpenDeepThink-style test-time compute.