DeepThonk

DeepThonk

より深く考えて、より多く使わない。

DeepThonk は、OpenDeepThink アルゴリズム（Zhou ほか、2026年、arXiv:2605.15177）を、予算にやさしくプロバイダーに依存しない「深く考える／プロモード」ラッパーとして実装しており、DeepSeek を第一級にサポートしています。謝辞をご覧ください。

DeepThonk は、候補回答の集団に対して、ペアごとの判定、Bradley-Terry ランキング、批評に基づく変異、エリートの保持、最終的な高密度ランキングのパスを実行します。CLI と MCP サーバーは、どちらも同じ TypeScript コアエンジンを呼び出します。

エージェント向けに設計されています。 アルゴリズムのあらゆる次元（集団の形状（n、k、t、m）、正則化（lambda）、フェーズごとの温度、プロンプトスタイル、フェーズごとのプロンプトテンプレート）を、MCP 引数と CLI フラグから直接指定できます。CLI では --prompts でプロンプトファイルを、--prompts-json でインライン JSON を読み込めます。MCP では、構造化されたプロンプト引数をインラインで受け付けます。すべての中間成果物（設定、候補、集団、比較、スコア、呼び出しごとの使用量、ステータス）は MCP リソースとして公開されるため、エージェントは任意のステップを調べられます。エージェントと組み合わせて使える機能の全容については、カスタマイズをご覧ください。

幅広い検討と判断を組み合わせることで、単発の高コストな実行を上回れる、厳密に検証可能な推論、コーディング、計画、統合に使用してください。判定のばらつきが支配的になる、主観性の高いタスクには適していません。

クイックスタート

Node ≥ 22.13 が必要です。

インストールせずに実行するには：

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

または、グローバルにインストールします：

npm install -g deepthonk
deepthonk plan --profile paper

論文のプロファイルでは、285 回のモデル呼び出しと 8 回の逐次ラウンドが計画されます。有料モデルに接続する前に、予算とプロバイダーの料金を確認してください。短縮エイリアス dt は deepthonk とあわせてインストールされます。ソースから開発する場合は、開発をご覧ください。

DeepThonk は独立した TypeScript による再実装であり、実用的な統合レイヤーです。基盤となるのは公開されたアルゴリズムです。コストの保証は、プロバイダーの料金が設定に含まれていることを前提とします。Trace-v2 の再開では、クラッシュ後に検証済みの項目ごとのレシートを再利用できます。一方、古いトレースでは、不完全なフェーズ全体を再実行します。MCP HTTP トランスポートは引き続きループバックのみで使用できます。付属の受け入れスモークテストでは、決定論的なフェイクプロバイダーとおもちゃのタスクを使用します。これは CF-73 / HLE の再現ではありません。正規の論文と Python リファレンスについては、docs/ と謝辞をご覧ください。

セットアップ

再利用可能なローカル設定を作成します：

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

デフォルトでは、~/.config/deepthonk/config.yaml に書き込みます。--config が指定されていない場合、deepthonk run はこのファイルを自動的に読み込みます。--api-key を渡すと、セットアップはキーを ~/.config/deepthonk/env に保存します。指定しない場合は、シェルで指定された名前付き環境変数を使用します。

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 は、https://api.deepseek.com/v1 を使用する OpenAI 互換プロファイルとして実装されています。DeepThonk には、キャッシュヒット／キャッシュミス時の入力料金を含め、DeepSeek 公式料金ページに基づく deepseek-v4-flash と deepseek-v4-pro のデフォルトの米ドル料金が含まれています。モデル名と料金はどちらも変更される可能性があるため、引き続き設定から編集できます。

有料実行の前に、コストの内訳と解決済みの設定を確認してください：

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

まず --profile quick から始め、大規模な有料プロファイルを実行する前に、--max-concurrency、--max-calls、--max-input-tokens、--max-output-tokens、--max-usd、--request-timeout-ms を検討してください。max_calls はディスパッチ前に予約され、失敗した呼び出しや無効な JSON の再試行を含む、論理的なモデル呼び出しの数をカウントします。プロバイダー内部の HTTP 再試行は別途報告されます。トークン数と米ドルの合計が判明するのは応答後のみであり、アクティブな同時実行ウィンドウの分だけ超過する可能性があります。計画では、名目上の calls を、ファイナライザーと再試行のための余裕を含む worst_case_calls と分けて表示します。

OpenAI互換プロバイダー

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

ドライバーは POST {base_url}/chat/completions を呼び出し、対応している場合は比較時にJSONモードを要求します。プロバイダーが response_format または json に言及する本文とともに 400 または 422 を返した場合、ドライバーはJSONモードを使わずに再試行し、この機能の確認を同時実行中の呼び出し間で調整して、結果をプロセスの実行中は記憶します。YAMLで supports_json_mode: false を設定すると、最初からJSONモードを無効にできます。

プロバイダー名は柔軟に指定できます。カスタムのOpenAI互換エンドポイントでは、任意のプロバイダーラベルと --base-url、--api-key-env、役割ごとのモデルフラグを使用してください。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

複数のプロバイダーを組み合わせて実行するには、YAML設定を使用し、providers 以下で各役割を個別に上書きしてください。特に judge を指定します。

任意の finalizer_model / --finalizer-model を指定すると、順位付けされた勝者を後処理できます。順位付けされた生の回答を最終成果物にしたい場合は、設定しないでください。

MCP

MCP サーバーは、CLIが実行するものと同じエンジンを公開します。MCPホストに接続すると、ホストは予算を計画し、バックグラウンド実行を開始し、ステータスをポーリングし、勝者を取得し、構造化されたトレース成果物をストリーミングできます。これらすべてをMCPツール、リソース、プロンプトを通じて行えます。

DeepThonkは、v0.2.1以降、MCP Registryに io.github.linxule/deepthonk として登録されています。レジストリ名でインストールするホストでは、自動的に npx deepthonk serve-mcp が解決されます。対応していないホストでは、以下の明示的な設定を手動で行うと同じように利用できます。

プロバイダーのAPIキーはDeepThonkの設定だけでなく、ホストプロセスの環境変数から取得されます。環境変数の引き渡し方法はホストによって多少異なります。以下の具体例を参照してください。サーバーの起動にキーは必要ありません。サンプリングに対応したホストでは provider: "sampling" を実行でき、fake プロバイダーはネットワーク接続を必要としません。

接続先のホストがMCPサンプリング機能を提示している場合、MCP Samplingは provider: "sampling" としてサポートされます。ブロッキング方式の run、rank、mutate は、stdioとステートフルなStreamable HTTPで動作します。ネストされたサンプリングは開始要求に紐付けておく必要があるため、HTTPのバックグラウンド start ではSamplingを拒否します。stdioでのバックグラウンド実行と、直接プロバイダーを使うHTTPのバックグラウンド実行は引き続き利用できます。スタンドアロンのCLI実行ではSamplingを利用できません。

Claude Code

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

プロジェクトをまたいで適用するには -s user を使用し、登録を .claude/ に保存するには -s project を使用してください。claude mcp list で確認できます。正式なフラグ一覧は claude mcp --help を参照してください。

Claude Desktop

設定ファイルのパス：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）、%APPDATA%\Claude\claude_desktop_config.json（Windows）、~/.config/Claude/claude_desktop_config.json（Linux）。以下を追加してください：

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

編集後、Claude Desktopを再起動してください。

Cursor

プロジェクト単位の設定：ワークスペース内の .cursor/mcp.json。ユーザー全体の設定：~/.cursor/mcp.json。Claude Desktopと同じJSON形式です：

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

その他のMCPホスト（stdio）

MCP stdioに対応するホストでは、以下を起動します：

npx -y deepthonk serve-mcp --transport stdio

関連するプロバイダーの環境変数をプロセスに設定してください。グローバルにインストールする場合は、npm install -g deepthonk を実行してから、command: "deepthonk" を直接使用してください。設定形式については、ホストのMCP登録ドキュメントを参照してください。

Streamable HTTP

ローカルのWebホスト向け、またはstdioを利用できない場合：

deepthonk serve-mcp --transport http --port 3333 \
  --max-active-jobs 2 --max-queued-jobs 32

サーバーは 127.0.0.1:3333 のみにバインドし、http://127.0.0.1:3333/mcp でステートフルな POST、GET、DELETE を公開します。セッションには暗号論的に安全なIDが割り当てられ、リクエストが処理中でない状態で30分間アイドル状態が続くと期限切れになり、最大64セッションまでです。DNSリバインディング対策が有効です（CVE-2025-66414）。Host ヘッダーが 127.0.0.1:3333 または localhost:3333 以外のリクエストは拒否されます。また、ラッパーは本文を読み取る前に、JSON以外のPOST、ループバック以外の Origin ヘッダー、Sec-Fetch-Site: cross-site を拒否します。ベアラー認証はありません。この信頼境界を見直さずに、このポートをリバースプロキシ経由で公開しないでください。

ツール

ツール	目的
deepthonk.plan	プロファイルの呼び出し回数と逐次ラウンド数を推定します（モデル呼び出しは行いません）。有料実行の前に使用します。
deepthonk.start	バックグラウンドで実行を開始し、run_dir、job_id、ジョブスコープのアーティファクトリソースを返します。
deepthonk.status	run_dir からジョブの状態をポーリングします。
deepthonk.result	ジョブ完了後、最終的な概要と勝者を返します。
deepthonk.cancel	実行ディレクトリに cancel.json を書き込んで、キャンセルをリクエストします。
deepthonk.lock_inspect / deepthonk.lock_reclaim	ロックの所有者を確認し、完全一致するフィンガープリントに限り明示的に再取得します。
deepthonk.repair_budget	旧形式の [redacted] 数値予算フィールドを、明示された元の値に置き換えます。
deepthonk.run	ブロッキング方式の簡易実行です。1 回の呼び出しで開始から完了待ちまで行います。実行時間の長いジョブには start とポーリングを推奨します。
deepthonk.rank	生成をスキップし、ペアワイズ判定と Bradley-Terry を使用して、ユーザー指定の候補セットを順位付けします。
deepthonk.mutate	批評を用いて、指定された候補を 1 つ変異させます（1 回限り）。
deepthonk.resume	実行を再開できるかどうかを検出します。continue: true を指定すると、最後に検証されたフェーズ境界から再実行します。
deepthonk.export	実行の概要または完全なトレースを JSON または Markdown でエクスポートします。
deepthonk.profile_list	保存済みの名前付きプロファイルバンドルを一覧表示します。
deepthonk.profile_show	保存済みのプロファイルを 1 つ表示します。手動編集されたシークレット形式の値は、読み込み時に拒否されます。
deepthonk.profile_save	再利用可能な名前付きプロファイルバンドルを保存します。
deepthonk.profile_delete	保存済みの名前付きプロファイルバンドルを削除します。

すべてのツールは、インラインのプロバイダー／モデルフィールド、または DeepThonk YAML 設定を指す config_path を受け付けます。

リソース

• deepthonk://runs — runs/ 内のすべての実行の JSON インデックスです。
• deepthonk://runs/{run_id}/summary — 実行の概要（JSON）です。
• deepthonk://runs/{run_id}/config — 機密情報を削除した実行設定（JSON）です。
• deepthonk://runs/{run_id}/{candidates|comparisons|scores|usage|trace} — フェーズごと、呼び出しごとの NDJSON です。
• deepthonk://runs/{run_id}/population/{generation} — 世代の個体群スナップショット（JSON）です。
• deepthonk://runs/{run_id}/{winner|final} — テキストアーティファクトです。
• deepthonk://runs/{run_id}/status — 実行状態（JSON）です。
• deepthonk://runs/{run_id}/prompts/{sha256} — 検証済みのコンテンツアドレス方式で保存されたレンダリング済みプロンプト（JSON）です。
• deepthonk://runs/{run_id}/trace-v2 — 上限付きフェーズインデックスです。すべてのレシートを確認するには、そのマニフェスト、コミット、チェックポイントインデックス、チェックポイント URI をたどってください。
• deepthonk://jobs/{job_id}/{status|result|config|candidates|comparisons|scores|usage|trace|final|winner}?run_dir=... — ジョブスコープの検索です。run_dir クエリパラメーターは必須です。
• deepthonk://jobs/{job_id}/population/{generation}?run_dir=... — 完了前または完了後の、ジョブスコープの個体群スナップショットです。
• ジョブの結果には、ジョブスコープで同等のリソースを取得するための prompt_template と trace_v2_template も含まれます。
• deepthonk://runs/{run_id}/{resource}/page/{cursor} およびジョブ用の同等の URI — 不透明な上限付きページです。全体の読み取りは 1 MiB に制限され、ページあたり最大 1,000 件、1 MiB です。

プロンプト

4 つのテンプレートはコアループに対応しています。deepthonk/generate、deepthonk/compare、deepthonk/mutate、deepthonk/finalize です。ホストはこれらを直接レンダリングして、ツールのインターフェースを呼び出さずにアルゴリズムを手動で実行できます。

制限事項

deepthonk.resume はデフォルトでトレースの状態を報告します。continue: true を指定すると、フェーズの順序、アーティファクト、実行／プロバイダー／モデルの識別情報、スコア、使用状況、決定的なペアのスケジュール、trace-v2 レシート、フェーズコミットを検証します。有効な未完了フェーズのレシートは、プロバイダーを再度呼び出さずに再利用されます。MCP Sampling のモデルヒントは優先設定であり、トークン使用量を取得できない場合があります。共有の適応型リミッターは 4 から開始し、直接プロバイダーは 8 から開始します。

カスタマイズ

アルゴリズムの各次元は、MCP の引数と CLI フラグから指定できます。

• 母集団の形状：n、k、t、m — プロファイルの既定値をインラインで上書きします。
• アルゴリズム定数：lambda、sample_temperature、mutate_temperature、judge_temperature。
• プロンプトのスタイル：general または paper-programming。
• フェーズごとのプロンプトテンプレート：カスタムのシステム／ユーザーテンプレートと変数置換（{task}、{rubric}、{candidate}、{candidateA}、{candidateB}、{critique}）を使って、generate、compare、mutate、finalize を上書きします。CLI では --prompts <yaml> と --prompts-json <json>、MCP ではインラインの prompts を使用できます。不明な変数があると、実行開始時に即時エラーが発生します。
• 並行性：generate、judge、mutate のフェーズごとの上限。
• プロバイダーのバックプレッシャー：provider_max_concurrency は、共有される適応型プロバイダールートリミッターの回復上限を設定します。
• 呼び出しごとの出力上限：生成、変異、判定、最終処理のトークン上限を個別に設定します。
• 最終ランキングのスケジュール：シード付きの all-pairs または k-regular と、明示的な論理呼び出し上限。
• 批評の上限：決定論的な重複排除と、変異の前に適用する設定可能な合計文字数上限。

エージェント呼び出しの例（MCP）。YAML ファイルは不要です。

{
  "task": "Draft a concise non-solicitation clause for a senior sales employee.",
  "profile": "balanced",
  "n": 6, "t": 1,
  "provider": "deepseek",
  "judge_model": "deepseek-v4-pro",
  "prompts": {
    "generate": { "system": "You are an experienced employment-law attorney." },
    "compare":  { "system": "Prefer enforceable clauses under California law. Return strict JSON only." }
  }
}

CLI でも同じ設定項目を利用できます。再利用可能なプロンプトファイルには --prompts <yaml> を、単回のインライン上書きには --prompts-json <json> を使用します。MCP と CLI はどちらも、--config／config_path の YAML 既定値に設定をマージします。

再利用可能な設定一式は、~/.config/deepthonk/profiles/<name>.yaml に名前付きプロファイルとして保存し、--profile-name <name>（CLI）または profile_name: "<name>"（MCP）で読み込みます。名前付きプロファイルは、その実行においてメインの設定ファイルに代わる独立した設定一式です。CLI フラグと MCP のインライン引数では、引き続きその中のフィールドを上書きできます。形式については examples/profiles/legal-drafting.yaml を参照してください。カスタマイズガイドでは、CLI と MCP の両方から名前付きプロファイルを一覧表示、確認、保存、削除する方法を説明しています。

変数の仕様、compare フェーズの JSON 安全性ルール、名前付きプロファイルのスキーマ、3 つの実例については、カスタマイズガイドを参照してください。ロールごとのプロバイダールーティング（providers.judge.provider = openrouter）とモデルごとの料金設定は YAML のみで指定できます。これらはネストされた構造化設定であり、インライン指定には適していません。

トレースファイル

実行が正常に完了すると、次のファイルが書き込まれます。

runs/{run_id}/
  config.json
  events.jsonl
  candidates.jsonl
  comparisons.jsonl
  scores.jsonl
  usage.jsonl
  population-0.json
  population-{generation}.json
  manifests/*.json
  checkpoints/*/*.json
  commits/*.json
  summary.json
  artifacts/winner.txt
  artifacts/final.txt
  artifacts/prompts/<sha256>.json  # only when prompt capture is enabled

status.json は、MCP の deepthonk.start から実行を開始した場合に書き込まれます（非同期クライアントがポーリングできるようにするためです）。cancel.json は、キャンセルが要求された場合にのみ書き込まれます。実行中は run.lock ファイルが保持されます。

トレース行は単一のライターを介してバッチ追加され、ライフサイクルの境界に達する前にフラッシュされます。項目ごとの出力と使用量のレシートは、フェーズのコミット前にアトミックに書き込まれます。トーナメントの途中で実行が強制終了された場合、trace-v2 による再開では、完了済みのレシートを検証して再利用し、その JSONL 行を再生成します。また、不足している作業や無効な作業に対してのみプロバイダーを呼び出します。

usage.jsonl には、フェーズ、ロール、プロバイダー、モデル、トークン、USD、レイテンシー、再試行の情報とともに、プロバイダー呼び出し（生成、判定、変異、最終処理）ごとに 1 行が記録されます。プロンプトの内容は含まれません。実行コストをロール別に集計するには、usage.jsonl に対して jq を使うのが最も簡単です。

プロンプトとモデルの生出力は、既定では保存されません。プロンプトのキャプチャを有効にすると、候補／比較行に promptRef が含まれ、同一のレンダリング済みプロンプトは artifacts/prompts/ 以下にコンテンツアドレス方式のブロブとして 1 つだけ保存されます。すべての JSONL 行やレシートに完全なプロンプトが繰り返し記録されることはありません。API キーが書き込まれることはありません。候補の回答、批評、スコア、最終成果物はトレースデータであり、設計上保存・エクスポートされるため、それを許容できない場合は、機密性の高いタスクに共有の実行ディレクトリを使用しないでください。

開発

pnpm install
pnpm run build
pnpm test
pnpm run lint

このリポジトリにはソースコードのみが含まれています。生成された実行トレース、論文のメモ、ビルド出力、カバレッジ、ログ、node_modules は意図的に無視されます。

リリースの公開は、タグをトリガーとして npm Trusted Publishing 経由で行われます。バージョンを更新したり、v* タグをプッシュしたりする前に、docs/release.md をご覧ください。

このリリースにおける既知の制限事項：

• Trace-v1 で再開すると、中断されたフェーズ全体が再実行されます。項目ごとの再利用には、DeepThonk v0.2 で作成された trace-v2 の実行が必要です。
• HTTP Sampling はブロッキング処理のみです。バックグラウンドで deepthonk.start を実行するには、stdio または直接プロバイダーを使用してください。
• maxUsd の使用には、既知のモデル価格が必要です。カスタムプロバイダーやモデル ID には、YAML で価格を明示的に追加してください。オプションのフィールド longContextThresholdTokens、inputUsdPerMillionLong、outputUsdPerMillionLong を使用すると、長いコンテキストに追加料金がかかるモデル（例：入力トークン数が 200K の場合の Gemini）で、段階的な価格設定が有効になります。キャッシュのヒット率とミス率は一律です。

謝辞

DeepThonk は、OpenDeepThink アルゴリズムを独自に TypeScript で再実装したものです。フォークではなく、参照実装のソースコードは一切同梱していません。アルゴリズム、ベンチマーク手法、実証結果の功績は、論文の著者に帰属します。

• 論文：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
• 参照用 Python 実装：https://github.com/ZhouShang0817/open-deep-think（MIT）。これは著者によるコード公開であり、論文の結果（CF-73、HLE）を再現するための標準実装です。

DeepThonk の貢献は統合レイヤーにあります。プロバイダーに依存しない TypeScript コア、MCP サーバー、CLI、構造化トレース成果物、予算の適用を提供します。アルゴリズム自体は著者によるものです。