subtask

subtask

コーディングエージェント向けのローカルな委任スケジューラーです。1 つの MCP サーバー（および対になる CLI）で、Claude Code、Codex、Kimi Code、OpenCode から並行して作業を開始し、1 回の呼び出しで完了を待ち、証拠を添えた短い要約を読み取れます。依頼を引き受けられるエンジンを選び、プロセス間で予算と枠を安全に確保し、各実行の分離レベルを正直に伝えます。

start_many([{task: "Fix the flaky test in tests/test_sync.py", repo: "/src/app", verify: "pytest -q tests/test_sync.py"},
            {task: "List every caller of parse_date()", kind: "read", readonly: true, cwd: "/src/app"}])
  -> st-4f2a91 started · sonnet-api · branch subtask/st-4f2a91 · sandbox
     st-77c0de started · haiku-api · /src/app · readonly
wait(["st-4f2a91", "st-77c0de"])          # Claude Code shows: Subtask · 01:16 · 1/2 ended — st-4f2a91 running tests: pytest -q
  -> st-4f2a91 done · sonnet-api · 6m · 0.412$ · verified · ...
     ## Summary (≤10 lines: the answer, files, commits, tests, what is left)
result("st-4f2a91", evidence=True)        # JSON: base/head, changed files, observed commands, verify exit code, cost

理由

• 呼び出し元のコンテキストを節約します。 ワーカーの検索、テスト実行、行き詰まった経緯はワーカー自身のセッションに残り、呼び出し元が読むのは約 10 行です。
• ラウンドトリップを減らします。 start_many と 1 回の wait で、ポーリングループを置き換えます。
• 余裕のあるエンジンを使います。 engine="auto" は、要求された分離を適用でき、インストール済みで、予算内に収まり、クォータに余裕のあるエンジンを絞り込み、明示的な効用関数で順位付けします（subtask routing explain）。
• 予算管理を基本機能とします。 有料エンジンでは、作業を始める前に、枠とともに 1 つのロックの下で予算を確保し、すべての確保を必ず 1 回だけ精算します。
• 主張ではなく、証拠を示します。 verify="..." はワーカーが残したコミットに対してチェックを実行し、result(evidence=True) は subtask が確認した内容とワーカーが報告した内容を分けて示します。

インストール

配布パッケージは subtask-mcp です（PyPI の subtask という名前は別のプロジェクトです）。クライアントごとのネイティブコマンドを含む完全なガイドはこちらです：docs/install.md。

uv tool install "git+https://github.com/tedin7/[email protected]"   # or: uv tool install /path/to/checkout
subtask install --client all          # prints the plan for every detected client
subtask install --client all --yes    # applies it: MCP server + skill
subtask doctor --client all           # checks app, config entry and a real handshake

Claude Code プラグイン：claude plugin marketplace add tedin7/subtask の後に claude plugin install subtask@subtask を実行します。Codex：codex plugin marketplace add tedin7/subtask を実行します。API エンジンは ~/.config/subtask/env から ANTHROPIC_API_KEY を読み込みます（chmod 600）。

エンジン

エンジン	支払い方法	読み取り専用	適用できる分離
haiku-api、sonnet-api、opus-api	API キー、月間上限	はい	サンドボックス（Claude Code OS サンドボックス）
codex	Codex ログイン（ローカルのセッションファイルからクォータを取得）	はい	サンドボックス（workspace-write）、分離
opencode-go	opencode-go サブスクリプション	いいえ	worktree、分離
kimi	Kimi ログイン	いいえ	worktree、分離
dsh	DeepSeek キー、同じ上限（subtask-mcp[dsh]）	いいえ	worktree
opencode	OpenCode のデフォルトプロバイダー（手動のみ）	いいえ	worktree、分離

コアに手を加えずにエンジンを追加できます。EngineAdapter を subtask.engines エントリーポイントに登録します（CONTRIBUTING.md を参照）。

正直な分離レベル

• worktree（デフォルト）：書き込みジョブごとに git worktree とブランチを作成します。競合を防ぎますが、ホストのサンドボックスではありません。
• sandbox：エンジン独自のサンドボックスです。同じユーザーのもとで動作するため、保護策として機能します。
• isolated：bubblewrap を使用します。システムは読み取り専用で、書き込み可能なのは worktree と git ディレクトリのみです。HOME は分離され、エンジン独自の状態だけが格納されます。bwrap が必要です。
• untrusted：サンドボックス以上の分離を適用し、ワーカーのコマンドではネットワークを使用できません。

要求されたポリシーを適用できないジョブは、ポリシーを引き下げずに拒否します。出力は保存または表示する前に、一般的なシークレット形式を対象としてマスキングされます。マスキングは追加の保護層であり、保証ではありません。SECURITY.md を参照してください。

ツール（MCP）と CLI

ツール	機能
start(task, kind, repo, cwd, files, readonly, engine, max_usd, effort, base, max_turns, policy, verify, isolation, max_retries, adversarial, context_refs, auto_repomap, tier, invariants, allowed_paths, symbol_scope, oracle_cmd)	ジョブを1つ開始します（以下を参照）
start_many(tasks)	複数のジョブを開始します。部分的に成功した場合は項目ごとに一覧表示されます。id と depends_on を持つ項目はグループ（grp-…）を形成し、追加のターンなしでDAGとして実行されます。foreach=<parent id> を指定すると、親の .subtask/fanout.json の各項目につき1つ（最大8つ）のコピーが作成され、依存ジョブはすべてのコピーが完了するまで待機します。after="any" を指定すると、親のいずれか1つが成功した時点で開始します
integrate(ids, action="apply", auto_resolve=False)	worktree ジョブを戻します。diff、apply（すべて適用するか、何も適用しないか。未コミット）、discard を指定できます。競合時に auto_resolve を指定すると、調整ジョブを開始します
consensus(prompt, engines, verify_cmd, isolation="worktree")	2〜4個のエンジンがそれぞれ独自の worktree で、互いの結果を知らずに問題を解決します。その後、1つのジョブが匿名のパッチとして差分を比較して解決策を1つ作成し、verify_cmd と不変条件で検証します。グループIDを返します
bisect(good_ref, bad_ref, test_cmd, parallelism=4, auto_fix=False)	test_cmd が失敗するようになる最初のコミットを特定します。一時 worktree でラウンドごとに最大 parallelism（最大8）のコミットをテストします。コミット、作成者、差分を返します。auto_fix を指定すると、検証済みの修正ジョブを開始します
map_reduce(glob_pattern, prompt_template, batch_size=5, concurrency=3, verify_cmd, isolation="worktree")	ファイルのバッチごとに1つのジョブを実行します（テンプレート内の {{files}}）。同時に実行するジョブは最大 concurrency 個です。グループIDを返します
wait(ids, timeout=300, mode="all", since=None, stall_timeout=None)	ジョブが終了するまで待機します（any：最初のジョブ、first_success：完了して検証された最初のジョブ。他のジョブは停止されます）。ジョブが停滞すると早期に戻ります。待機中は進捗通知が届きます。since は進捗通知に対応していないクライアント向けのカーソルです
steer(id, action, instruction=None)	hint（キューに追加し、試行終了時に返信として送信）、abort、retry（指示を付けて新しいジョブを開始）
inspect(id, tail=80, grep=None)	要約では不十分な場合に限り、生のログ行を返します
status(id) / result(id, full, evidence)	1行のステータス／要約、全文、またはJSONエンベロープを返します
reply(id, message) / stop(id) / cleanup(id)	続行／作業を停止／クリーンな worktree を削除（ブランチは保持）
engines()	各エンジンのソース、鮮度、信頼度を含む処理能力と、使用額を返します
step(title, path, how, decisions)	独立した低コストのモデルが、リポジトリの実際の状態に基づいて手順を説明します

start のオプション：

• isolation="worktree"：独自の worktree とブランチ（repo=と同様）、さらにSUBTASK_PORT（18100 から）、SUBTASK_ID、専用のTMPDIRを使用します。結果にはfiles_modifiedとdiff_statが一覧表示されます。
• verify + max_retries：チェックに失敗すると、その出力を使ってジョブを再開します。すべての再試行に失敗した場合、worktree は最善の試行結果（「N 件成功 / N 件失敗」に基づいて評価）に戻ります。
• adversarial=True：Breaker ジョブが仕様のみを基にエッジケースのテストを作成します。テストは Builder の worktree にコピーされ、verifyで実行されます。
• context_refs：file:PATH[:A-B]、git:diff[:REF]、subtask:ID:summary|diffを指定し、開始前に解決します。auto_repomap=Trueを指定すると、追跡対象ファイルとそのトップレベルのシンボルが追加されます（HEAD ごとにキャッシュ）。
• invariants（デフォルトは["no_test_deletion", "no_suppression"]。[]を指定すると無効化）：verifyのカウント前に、テスト関数の数を減らすこと、新しい skip/xfail マーカーを追加すること、新しい# type: ignore、# noqa、# pragma: no coverを追加することはできません。違反は理由付きのチェック失敗として扱われるため、再試行時にも確認できます。
• allowed_paths：指定したパス以外で変更されたファイルは元に戻され、復元がコミットされます。
• symbol_scope=["path.py::name", ...]：そのファイル内で変更できるのは、指定されたトップレベルの関数またはクラスのみです。integrateは複数のジョブによる1つの Python ファイルへの編集をシンボル単位でマージします。編集箇所の重複、インポートまたは定数の変更、対象シンボルの並行変更は競合として扱われ、推測による処理は行いません。
• oracle_cmd：verifyの成功後、ジョブのベースと結果に対してコマンドを同時に実行し、終了コードと標準出力が一致するかどうかに加え、duration_ms_before、duration_ms_after、speedup_pctを報告します。
• tier：fast（処理負荷が低い）、deep（処理負荷が高く、種類は hard）、free_only。月間上限の 75% を超えると、autoとbalancedは無料エンジンに切り替わり、応答にbudget_warningが含まれます。

メモリ：チェックに失敗して再試行で修正された場合、subtask はそのリポジトリ向けの短い教訓を$SUBTASK_HOME/engrams/に保存します（最大 50 件。最も長く使われていないものから削除）。同じパスを対象とするジョブには、上位 3 件が渡されます。グループには共有メモ用の blackboard ファイルがあり、新しいメモはwait(since=...)で確認できます。

CLI のみ：subtask board [--json]（OpenCode プラグインが表示するビュー）、subtask doctor、gc [--apply]、du、roi、routing explain|calibrate、watch ID...、install、uninstall、開始時に指定する--model、--no-sandbox、--untrusted。

チャットでの進捗表示

クライアント	wait中の表示
Claude Code 2.1（TUI）	ツール呼び出しの下にライブ表示。検証済み
OpenCode 2.0	通知は受信するものの表示されません：wait(since=...)を使用してください
Kimi Code 2.1	クライアントが進捗を要求しません：wait(since=...)
Codex 0.162	未検証（アカウントが利用上限に達しています）

詳細とエビデンス：docs/progress-matrix.md。

設定

変数	デフォルト
SUBTASK_HOME	~/.local/share/subtask（ジョブ、worktree、台帳、テレメトリ）
SUBTASK_ENV_FILE	~/.config/subtask/env
SUBTASK_MONTHLY_CAP_USD / SUBTASK_DEFAULT_MAX_USD / SUBTASK_MAX_JOB_USD	180 / 2 / 20
SUBTASK_MAX_RUNNING	4（全プロセスで共通）
SUBTASK_ROUTING	~/.config/subtask/routing.json（重み、"mode": "legacy"）
SUBTASK_JOB_RETENTION_DAYS / SUBTASK_TELEMETRY_DAYS	30 / 90
SUBTASK_PROGRESS_MIN_S / SUBTASK_PROGRESS_HEARTBEAT_S	2 / 10

API エンジンのコストは SDK の推定値に基づきます。実際のコストが不明な実行には、予約額の全額が請求されます。テレメトリはこのマシン内に保持されます。

プラットフォーム

Linux：対応しています。macOS：一部機能が制限されます（プロセスの生存確認に/procの開始時刻を利用できず、bwrap もないため、isolatedは拒否されます）。Windows：非対応（fcntl）。

ドキュメント

アーキテクチャ · 要件マトリックス · メリットと測定結果 · ベンチマークの手順 · インストール · リリース · コントリビューション

ライセンス

MIT