ultracode は Claude Code の /effort スライダーで effort レベルと並んで表示されますが、Claude Code のドキュメントでは別物として説明されています。Model configuration のページには「Ultracode is a Claude Code setting rather than a model effort level: with it on, Claude orchestrates dynamic workflows for substantive tasks, at whichever effort level the session runs at.」（ultracode はモデルの effort レベルではなく Claude Code の設定です。オンにすると、セッションがどの effort レベルで動いていても、Claude は実質的なタスクに対して動的ワークフローを組み立てます）とあります。
ultracode で有効になるもの
Dynamic workflows のページによると、動的ワークフローとは「a JavaScript script that orchestrates many subagents at once」（多数のサブエージェントを同時に動かす JavaScript のスクリプト）です。Claude がタスクに合わせてスクリプトを書き、ランタイムがバックグラウンドで実行するので、その間もセッションは操作できます。
ドキュメントによると、ultracode をオンにすると、Claude はユーザーに頼まれるのを待たずに、実質的なタスクごとにワークフローを計画し、ワークフローが必要かどうかも Claude が判断します。1 つのリクエストが、コードを理解する、変更を加える、検証するという複数のワークフローに続けて分かれることもあります。
ワークフローを始める方法は ultracode だけではありません。セッションの設定を変えずに 1 つのタスクだけをワークフローで実行したい場合は、プロンプトに ultracode というキーワードを入れるか、「use a workflow」のように自分の言葉で頼めばよいとドキュメントは説明しています。
オンにする方法
ドキュメントでは、次の方法が挙げられています。
- /effort ultracode を実行すると現在のセッションでオンになり、/effort ultracode off でオフになります。/effort スライダーでは Tab で Ultracode のトグルを切り替え、Enter で確定します。
- claude --effort ultracode で起動すると、effort が xhigh、ultracode がオンの状態でセッションが始まります。
- 設定ファイルに "ultracode": true を書くと、すべてのセッションがオンの状態で始まります。
--effort フラグに ultracode を渡すには Claude Code v2.1.203 以降が必要です。/effort ultracode off、スライダーのトグル、xhigh 以外のレベルで ultracode をオンのままにすることには v2.1.284 以降が必要です。ワークフローがオフになっている場合や、モデルが xhigh に対応していない場合、ultracode は使えません。
ultracode と xhigh、max の関係
Claude Code の effort レベルは low、medium、high、xhigh、max の 5 つです。ドキュメントは xhigh を「Deeper reasoning at higher token spend」（トークンを多く使ってより深く推論する）、max を「the deepest reasoning level」（最も深い推論レベル）と説明しています。ultracode も同じ表に載っていますが、説明は「A Claude Code setting rather than a level: plans a dynamic workflow for each substantive task at any effort level」（レベルではなく Claude Code の設定で、どの effort レベルでも実質的なタスクごとに動的ワークフローを計画する）です。つまり effort レベルと ultracode は別々に設定されます。/effort や ultracode 設定で ultracode をオン・オフしても effort レベルは変わらず、レベルを選んでも ultracode の状態はそのままです。effort を xhigh にも設定するのは、--effort ultracode フラグと Agent SDK の effortLevel: "ultracode" だけです。
ドキュメントによると、v2.1.284 より前は ultracode をオンにするとセッションが xhigh になり、別のレベルを選ぶとオフになっていました。effortLevel 設定と環境変数 CLAUDE_CODE_EFFORT_LEVEL には ultracode を指定できません。ドキュメントは別のキーワードとして ultrathink も説明しています。こちらはセッションの effort 設定を変えずに、その 1 ターンだけより深い推論を求めるもので、API に送られる effort レベルは変わりません。
使用量を多く消費する理由
Dynamic workflows のページには、コストについてはっきり書かれています。「This applies to every task in the session, so each request uses more tokens and takes longer than the same request without a workflow. On a subscription plan those tokens draw on your usage limits, so a session with ultracode on reaches a session or weekly limit sooner than the same work with it off.」（これはセッション内のすべてのタスクに当てはまるため、各リクエストはワークフローなしの同じリクエストより多くのトークンを使い、時間もかかります。サブスクリプションプランではそのトークンが使用量の上限から差し引かれるので、ultracode をオンにしたセッションは、オフで同じ作業をする場合より早くセッションや週の上限に達します）
トークンがどこで増えるのかは、ドキュメントのほかの記述からわかります。まず、多くのエージェントが同時に動きます。ワークフローは既定で最大 16 のエージェントを同時に実行し、Claude Code が使える CPU が少ない場合はそれより少なくなります。環境変数 CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS でこの上限を 1 から 256 の間で変えられ（v2.1.269 以降が必要）、1 回の実行で使えるエージェントは合計 1,000 までです。また、これらのエージェントはセッションのモデルを使います。ワークフローのエージェントにほかでモデルが割り当てられていない場合はセッションのモデルで動くため、大きなモデルのセッションでは、ワークフローのエージェントもそのモデルで動きます。
さらに、一部の確認が省かれます。ドキュメントによると、ultracode をオンにすることは「already opts you in to large runs」（大規模な実行にすでに同意している）ことになるため、オンの間は 3 つの確認が適用されません。通常はワークフローが 25 を超えるエージェントを予定したときや、予測トークン数が 150 万を超えたときに出る Large workflow の警告が表示されません。Agent ツールで起動されるサブエージェントには、セッションの同時サブエージェント数の上限が適用されません。auto の権限モードでは、最初のワークフロー起動の承認を求められません。なお、ドキュメントが挙げる省かれる確認の中に、ワークフローの同時実行 16 エージェントという上限は含まれていません。
使用量を抑えるには
ドキュメントは、通常の作業に戻るときには /effort ultracode off でオフにするか、セッション全体でオンにせず、1 つのタスクだけ ultracode キーワードを使うよう勧めています。大きな実行の前には /model を確認し、最も強いモデルが必要ない段階には小さいモデルを使うよう Claude に頼むことも挙げています。
また、まずリポジトリ全体ではなく 1 つのディレクトリなど、小さな範囲で試すことも勧めています。/workflows の画面には実行中の各エージェントのトークン使用量が表示され、そこで実行を止めることもできます。エージェント数を抑えたい場合は、size guideline で small を選べます。
