claude-task-worker

claude-task-worker

GitHub Issues/PRを定期ポーリングし、Claude Codeに処理を委譲するCLIツール。

同梱の Claude Code プラグイン（plugin/）と組み合わせることで、Issue の実装からPRのレビュー対応、Dependabot PR の対応までを自動化する。CLI 本体（npm パッケージ）とプラグイン（Claude Code マーケットプレイス）は同じリポジトリ・同じ名前で提供される。

アーキテクチャ

CLI が GitHub ラベルを検知してタスクを起動し、プラグインのスキルが実際の処理を担う。

   GitHub (Issue / PR + ラベル)
              │ poll
              ▼
     claude-task-worker
              │ invoke
              ▼
       Claude Code CLI
   + claude-task-worker plugin

Worker とスキルの対応

Worker	トリガー	呼び出すスキル	間隔
exec-issue	cc-exec-issue (Issue)	/claude-task-worker:exec-issue	1分
create-issue	cc-triage-scope (Issue)	/claude-task-worker:create-issue-from-issue-number	1分
update-issue	cc-update-issue	/claude-task-worker:update-issue	1分
answer-issue-questions	cc-answer-issue-questions	/claude-task-worker:answer-issue-questions	1分
triage-created-issue	cc-issue-created + cc-triage-scope (Issue)	/claude-task-worker:triage-created-issue	1分
epic-issue	cc-epic-issue (Issue, sub-issues が全て Close)	/claude-task-worker:create-epic-pr	5分
create-ui-design	cc-create-ui-design (Issue)	/claude-task-worker:create-ui-design	1分
apply-ui-design	cc-ui-design-pr-created (Issue)	/claude-task-worker:apply-ui-design	5分
fix-review-point	cc-fix-onetime (PR)	/claude-task-worker:fix-review-point	1分
triage-pr	cc-triage-scope (PR)	/claude-task-worker:triage-pr	1分
resolve-conflict	cc-resolve-conflict (PR)	/claude-task-worker:resolve-pr-conflict	1分
check-dependabot	dependencies (PR)	/claude-task-worker:check-dependabot	1時間
update-coding-guidelines	24時間経過	/claude-task-worker:update-coding-guidelines	1時間
update-requirement-rules	24時間経過	/claude-task-worker:update-requirement-rules	1時間
update-design-md	24時間経過	/claude-task-worker:update-design-md	1時間

共通の挙動:

• 処理中は cc-in-progress を付与し、同一 Issue/PR の重複実行を防ぐ
• cc-need-human-check が付いた Issue、未解決の blockedBy を持つ Issue は対象外
• 完了時にトリガーラベルを除去し、次のワーカーへ引き継ぐラベルを付与する
• 定期ワーカー3つ（update-*）はラベルではなく時刻を条件に24時間おきに1回動く。表の「間隔」は24時間経過したかを確認する頻度
• UIデザイン系3ワーカー（create-ui-design / apply-ui-design / update-design-md）は uiDesign.enabled が true のときだけ起動する（既定 false）

セットアップ

前提条件

名前	用途
Node.js >= 22.6.0	CLI の実行ランタイム
GitHub CLI (gh)	全 GitHub 操作（認証済みであること）
Claude Code (claude)	タスク実行エンジン
Git / jq	worktree 操作 / スキル内での JSON 加工
CodeGraph	コード探索用インデックス（任意。未導入ならテキスト検索に落ちる）
Pen CLI	.pen の編集・参照。UIデザイン先行ワークフロー使用時のみ（要ログイン）
Playwright のブラウザ	Playwright MCP でのブラウザ確認
DESIGN.md CLI	DESIGN.md の lint。update-design-md 使用時のみ（未導入でも動く）
herdr	--project / mode: "herdr" 使用時のみ（--cloud は herdr に依存しない）
GitHub MCP	GitHub アクセスの高速化・クラウド実行時のプロキシ制限回避（任意。Claude 側のコネクタで有効化）

CLI 本体に npm の実行時依存はない（Node.js 標準モジュールのみで動作する）。

インストール

npx claude-task-worker install

マーケットプレイス追加・プラグイン導入・CLI 本体のグローバルインストール・各種 CLI（CodeGraph / DESIGN.md / Pen）と Playwright ブラウザの取得を一括で行う。いずれかが失敗しても処理は継続する。インストール後、Claude Code のセッションを再起動するとプラグインが有効になる。

個別にやる場合:

npm install -g claude-task-worker
claude plugin marketplace add getty104/claude-task-worker
claude plugin install claude-task-worker@claude-task-worker

herdr は curl -fsSL https://herdr.dev/install.sh | sh または brew install herdr（ドキュメント）。

更新

claude-task-worker update

マーケットプレイス・プラグイン・CLI 本体・各種 CLI をまとめて更新する。プラグインの反映にはセッション再起動が必要。

初期化

対象リポジトリで実行すると、GitHub ラベル・Issue テンプレート・GitHub Actions ワークフロー・設定ファイル（claude-task-worker.json）が作成され、CodeGraph のインデックスが構築される。

claude-task-worker init           # 既存ファイルは保護
claude-task-worker init --force   # 強制上書き

作成されるラベル:

ラベル	用途
cc-triage-scope	トリアージ対象マーク（Issue/PR）＝ワーカーのキュー合流口
cc-issue-request	人が Issue テンプレートから作成を依頼した印。起票者を assignee に自動設定するワークフローの発火条件（cc-triage-scope と役割を分けてあり、ワーカーの自動起票では付かない）
cc-issue-created	create-issue 由来の Issue マーク
cc-update-issue / cc-answer-issue-questions / cc-exec-issue	Issue の更新 / 確認事項回答 / 実行トリガー
cc-fix-onetime / cc-resolve-conflict	PR の修正 / コンフリクト解消トリガー
cc-in-progress	処理中ステータス
cc-need-human-check	人間の確認が必要（付与中はワーカーの対象外）
cc-pr-created	PR 作成完了マーク
cc-epic-issue	エピックマーク（Issue: サブ全 Close で epic-issue 起動 / PR: リリースゲート対象）
cc-release-ready	エピックPRがリリース可能と判定されたマーク（マージは人間が実施）
cc-create-ui-design / cc-ui-design-pr-created / cc-ui-design-ready	UIデザイン先行ワークフローの各段階
cc-ui-design	デザインPRのマーカー
cc-cloud-done	クラウド実行タスクの完了マーク（セッションが付与し、ワーカーが検知して除去する。手動付与で張り付いたタスクを救済できる）

コマンド

claude-task-worker <command> [--epic <issue-number>]... [--label <label>]... [--project <name>]... [--cloud] [--debug]

コマンド	内容
各ワーカー名	単一ワーカーを起動（exec-issue / triage-pr など）
all	通常ワーカー9つ + 定期ワーカー3つ（triage-created-issue / triage-pr / check-dependabot を除く）
yolo	全ワーカーを同時にポーリング
init	ラベル・テンプレート・設定ファイルの作成と CodeGraph セットアップ
install / update	上記「セットアップ」を参照
cloud-setup [--force]	クラウド VM 側の準備（下記「--cloud」を参照）
usage	Claude API 使用状況（5時間/7日間の利用率とリセット時刻）を表示し、Slack にも通知
version	CLI のバージョンを表示（--version / -v も可）

--epic <issue-number>

指定したエピック Issue のサブ Issue のみを処理対象に絞る。複数指定は OR。

claude-task-worker all --epic 100 --epic 200

epic-issue ワーカーではエピック Issue 自身の番号として照合される。

--label <label>

トリガーラベルに加えて指定ラベルが付いた Issue のみに絞る。複数指定は AND。--epic と併用可能。

claude-task-worker all --label priority-high --label needs-design

--project <name>

指定したプロジェクト（またはグループ、all）へ herdr 経由でコマンドをディスパッチする。CLI はワーカーを直接実行せず、プロジェクトごとに独立した herdr ワークスペースを作ってそこでコマンドを実行し、稼働状況をステータステーブルに表示する。SIGTERM/SIGINT で全セッションを一括停止する。

claude-task-worker all --project all
claude-task-worker exec-issue --project app-a --epic 100

プロジェクト名・グループ名は config.json で定義する（下記「設定ファイル」）。all は全プロジェクトを指す予約語。

--project と併用できないコマンド: init / install / update / usage / version

--cloud

タスクを Claude Code on the web（クラウド VM）で実行する。プロセス単位のフラグで既定は無効。

claude-task-worker exec-issue --cloud
claude-task-worker all --cloud

クラウドで実行されるのは exec-issue と fix-review-point の2ワーカーだけで、それ以外は --cloud を付けてもローカル実行のまま残る（all / yolo にそのまま付けられる）。どのワーカーがクラウドで走るかは起動時にログへ出る。

前提条件:

前提	備考
script コマンドが使える環境（macOS / Linux）	クラウドセッションの作成には TTY が必要で、それを script コマンドの疑似 pty で供給する。platform が darwin/linux でない、または script が PATH に無い場合はタスクを1件も起動せずエラー終了する（フォールバックしない）
claude.ai アカウントでのサインイン	API キー認証・第三者プロバイダ（Bedrock / Vertex）構成では利用不可。--cloud 指定時のみ検査される
対象リポジトリの GitHub App 連携	クラウド VM から push / PR 作成を行うため
claude.ai の「プルリクエストを自動的に作成する」「プルリクエストの自動修正」が OFF	下記
VM 側のセットアップスクリプト	下記
PEN_CLI_KEY 環境変数	UIデザイン先行ワークフローを使う場合のみ（下記「Pen CLI のログイン」）

claude.ai の設定にある 「プルリクエストを自動的に作成する」「プルリクエストの自動修正」は必ず OFF にする。どちらもタスクワーカーの制御と競合する。前者はスキルの create-pr（Closes #<N>・ベースブランチ・ラベル付与）とは別に PR を作るため PR が重複し、後者はセッションが PR 作成後に終了せずレビューを待って修正を続けるため、cc-cloud-done による完了検知が 4 時間のタイムアウトまで効かない。

claude.ai の環境設定（セットアップスクリプト欄）に次の2行を記載しておく。

npx claude-task-worker install
npx claude-task-worker cloud-setup

cloud-setup は VM 側の ~/.claude/settings.json に権限モード・出力スタイル・言語を書き込み、グローバル gitignore へ .codegraph/ を登録する。クラウドセッションは起動フラグの --permission-mode を反映しないため、この設定ファイルが権限モードを指定する唯一の経路になる。書き込みはキー単位のマージで既存の設定を消さない（--force で上書き）。

補足:

• クラウド実行のタスクは worktree を作らない（VM が自前でリポジトリを持つため）
• 完了は cc-cloud-done ラベルで検知する。4時間で応答がなければ打ち切り、cc-need-human-check を付けて失敗通知する
• --project と併用した場合、--cloud は各プロジェクトへそのまま転送される
• --cloud と併用できないコマンド: init / install / update / usage / version
• --cloud は mode（default / herdr）に依存しない。クラウドセッションの作成は script コマンドの疑似 pty で完結し、herdr のペインを使わないため、どちらの mode でも同じ経路を通る

詳細は docs/prd-cloud-worker-execution.md を参照。

--debug

各タスクの最終報告を対象 Issue/PR へコメントとして残す。ローカル実行（default / herdr）でもクラウド実行（--cloud）でも使える。

claude-task-worker exec-issue --debug
claude-task-worker exec-issue --cloud --debug

既定（--debug なし）では最終報告は Slack 通知にのみ載り、Issue/PR にはコメントされない。毎タスク投稿すると Issue/PR がワーカーの実行ログで埋まるため。

投稿の担当は実行形態で違う。ローカルはワーカーが報告そのもの（claude -p の stdout / transcript）を持っているのでワーカーが投稿し、クラウドはワーカーに報告が届かないのでセッション自身に投稿させる（ワーカーはそれを回収して Slack へ載せる）。定期ワーカー（update-*）の投稿先は実行記録PR（ctw-last-run-<ワーカー名>）。クラウド実行の完了検知（cc-cloud-done）はフラグの有無に関わらず従来どおり動く。

Pen CLI のログイン

.pen を扱うスキルは Pen CLI の認証を必要とする。UIデザイン先行ワークフローを使うなら一度ログインしておく。

pencil login    # メールアドレス + パスワード、またはメールアドレス + OTP コード
pencil status   # 認証状態の確認

CI やクラウド VM など対話ログインできない環境では、環境変数 PEN_CLI_KEY（pen.dev の組織設定 > Developer Keys で発行）を使う。保存済みトークンより優先される。

設定ファイル

グローバル設定は $XDG_CONFIG_HOME/claude-task-worker/config.json（未設定なら ~/.config/claude-task-worker/config.json）、リポジトリ設定は実行ディレクトリ直下の claude-task-worker.json。

config.json（グローバル）

{
  "mode": "default",
  "advisor": false,
  "permission": "bypassPermissions",
  "projects": {
    "app-a": "/Users/me/repos/app-a",
    "app-b": "/Users/me/repos/app-b"
  },
  "projectGroups": {
    "frontend": ["app-a", "app-b"]
  }
}

キー	既定	説明
projects	-	プロジェクト名 → 絶対パス
projectGroups	{}	グループ名 → プロジェクト名配列
mode	"default"	"default": claude -p の子プロセスとして実行 / "herdr": herdr のタブ内で TUI 起動し、実行中の様子を覗ける（--project はこちらが必要）
advisor	false	true で --advisor <model> を渡す。モデルは claude-task-worker.json の advisorModel
permission	"bypassPermissions"	Claude CLI の権限モード（bypassPermissions / dontAsk / auto / acceptEdits / manual / plan）

いずれもトップレベル一括で、プロジェクト単位・ワーカー単位の指定はできない。permission はワーカーに承認するユーザーがいないため、bypassPermissions / dontAsk 以外ではタスクが承認待ちで止まりうる。

ℹ️ mode: "herdr" の完了通知音はワーカー側から止められない。無音にするには ~/.config/herdr/config.toml に [ui.sound] enabled = false を書いて herdr server reload-config する（herdr サーバー全体に効く）。

claude-task-worker.json（リポジトリ）

キー	型	既定	説明
fixReviewPointCallbackCommentMessage	string	-	fix-review-point 完了時に PR へ投稿するコメント（未設定なら投稿しない）
remoteEnvId	string | null	null	クラウド実行（--cloud）時に --environment へ渡すクラウド環境ID。null なら渡さず claude 側の既定解決に任せる（下記）
uiDesign	object	{ "enabled": false, "designDir": "designs", "yolo": false }	UIデザイン先行ワークフロー（下記）
workers	object	{}	ワーカーごとの上書き設定（下記）
lastRun	object	{}	定期ワーカーの最終実行時刻。ワーカーが自動更新するため手で編集しない

claude-task-worker.local.json（ローカル上書き）

同じディレクトリに claude-task-worker.local.json を置くと、claude-task-worker.json と同じキーを書けて同じキーはローカル側が勝つ。マージはネストしたオブジェクトのキー単位（workers.<name>.model だけを差し替えられる。配列・スカラーは丸ごと置き換え）。

コミットしない前提のファイルで、claude-task-worker init が .gitignore へ登録する。remoteEnvId のように各自の環境で値が違う設定を置く。

クラウド環境の指定（remoteEnvId）

--cloud 実行時に claude --environment <id> へ渡す環境ID。指定しない場合の選択は claude CLI に任せる（~/.claude/settings.json の remote.defaultEnvironmentId → アカウントの最初の anthropic_cloud 環境 → 無ければ自動作成）。ID は claude.ai の環境設定、または /remote-env で確認できる。自己ホスト環境（ccpool_...）も同じキーに書ける。

{ "remoteEnvId": "env_xxxxxxxx" }

ワーカーごとの設定

未指定のワーカー・フィールドは既定値にフォールバックする。

フィールド	説明
skill	Claude CLI の -p に渡すスラッシュコマンド（"<skill> <番号>" の形で起動）
model	--model の値（sonnet / opus / haiku）
advisorModel	--advisor の値。空文字なら advisor なし。config.json の advisor: true のときだけ参照される
effort	--effort の値（high / medium / low）
pollingIntervalSeconds	ポーリング間隔（秒）
cooldownSeconds	タスク完了後にポーリングを止める時間（秒）。既定 0
maxConcurrentTasks	同時実行できるタスクの最大数。既定 1

既定値:

ワーカー	model	effort	pollingIntervalSeconds
exec-issue / fix-review-point / answer-issue-questions / create-issue / create-ui-design / triage-pr	opus	high	60
update-issue / triage-created-issue / resolve-conflict	sonnet	high	60
epic-issue / apply-ui-design	sonnet	medium	300
check-dependabot	sonnet	high	3600
update-coding-guidelines / update-requirement-rules / update-design-md	opus	high	3600
（未知のワーカー名）	opus	high	60

advisorModel の既定は全ワーカー空文字（advisor なし）。

設定例:

{
  "workers": {
    "exec-issue":       { "model": "opus", "cooldownSeconds": 600, "maxConcurrentTasks": 3 },
    "fix-review-point": { "model": "sonnet", "advisorModel": "opus", "maxConcurrentTasks": 2 },
    "triage-pr":        { "effort": "medium", "pollingIntervalSeconds": 120 }
  }
}

ワークフロー

Epic（親Issue）連携

親 Issue を持つサブ Issue は、デフォルトブランチではなく cc-epic-<親Issue番号> ブランチから worktree を作って処理される。サブ Issue ごとのPRを単一の統合ブランチへ集約するため。エピックブランチが remote に無ければ自動で派生・push される。

サブ Issue がすべて Close されると epic-issue ワーカーがエピックブランチからまとめてPRを作る。エピックPRは triage-pr がマージ可能と判定してもマージせず cc-release-ready を付けるだけで、実際のマージ（リリース）は人間に委ねられる。

UIデザイン先行ワークフロー

UI実装 Issue について、実装の前に Pencil（.pen）でデザインを作り、独立したPRとしてマージしてから実装へ進むフロー。uiDesign.enabled によるオプトインで、既定（false）では関連ワーカーが起動しない。

キー	既定	意味
uiDesign.enabled	false	有効化
uiDesign.designDir	"designs"	.pen とスナップショットの配置先（リポジトリルートからの相対パス）
uiDesign.yolo	false	true でデザインPRに cc-triage-scope を付け、既存フローで自動レビュー・自動マージへ流す

triage-created-issue（ルーティング）
  ├─ UI実装タスクでない → cc-exec-issue
  └─ UI実装タスク       → cc-create-ui-design
        → create-ui-design: .pen + snapshots を作り、デザインPR（cc-ui-design）を作成
        → yolo: true なら自動レビュー・マージ / false なら人がレビュー・マージ
        → apply-ui-design: マージ後に Issue description へ「## UIデザイン」を追記し cc-exec-issue を付与
        → exec-issue: デザインを参照元として実装

デザインが不要と判明した場合は create-ui-design が理由をコメントして実装へ復帰する。Pencil が使えない環境やデザインPRが却下された場合は cc-need-human-check で停止する。

Slack通知

環境変数 CLAUDE_TASK_WORKER_SLACK_WEBHOOK_URL に Incoming Webhook URL を設定すると、タスクの完了時・失敗時に通知が送られる。未設定なら送信されない。

export CLAUDE_TASK_WORKER_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxx/yyy/zzz
claude-task-worker all

通知には Claude API の使用状況も含まれる。あわせて RunCat Neo 用のスナップショットを ~/.claude/runcat-usage.json（RUNCAT_OUT_FILE で変更可）へ書き出す。クラウド実行のタスクは通知の先頭行にセッションURLが入る。

プロセス管理

実行中のタスクはリアルタイムのステータステーブルで表示される（タスクID・タイトル・ステータス・開始時刻・経過時間）。SIGTERM/SIGINT で graceful shutdown し、もう一度送ると強制終了してラベル・worktree の後片付けを試みる。前回の異常終了で残った worktree はワーカー起動時に自動回収される。

ワーカーは応答するユーザーがいない状態でスキルを起動するため、処理が未完のままラベルだけ進む事故を防ぐガードを持つ（バックグラウンド実行と対話系ツールの無効化、自律実行原則のシステムプロンプト注入、PR 実在の完了検証、空出力セッションの失敗扱い、Stop フックによる残留プロセスの停止）。

開発

npm install
npm run build         # 型チェック + esbuild で dist/index.js にバンドル
npm run dev           # 型チェックの watch モード
npm test              # ユニットテスト
npm run lint          # ESLint（--fix で自動修正）
npm run format        # Prettier で整形

開発版をローカルから使う場合は npm install && npm run build && npm link。

コントリビューションを歓迎します。開発環境のセットアップ・PRの出し方は CONTRIBUTING.md、バグ報告・機能要望は Issue テンプレート から。セキュリティ上の脆弱性は公開Issueではなく SECURITY.md の手順で報告してください。参加にあたっては CODE_OF_CONDUCT.md（Contributor Covenant）を遵守してください。

ライセンス

MIT License. 詳細は LICENSE を参照してください。