claude-task-worker

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

同梱の claude-task-worker 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 とスキルの対応

共通の挙動:

• 処理中は cc-in-progress を付与し、同一 Issue/PR の重複実行を防ぐ
• cc-need-human-check が付いた Issue は全ワーカーの対象外
• Issue 系ワーカーは -is:blocked 検索 qualifier で絞り込むため、未解決の blockedBy を持つ Issue は対象外
• 完了時にトリガーラベルを除去し、次のワーカーへ引き継ぐラベルを付与する
• create-ui-design / apply-ui-design は uiDesign.enabled が true のときだけ起動する（既定 false）

プラグインの構成

セットアップ

前提条件

CLI 本体に npm の実行時依存はない（esbuild で dist/index.js に単一バンドルされ、Node.js 標準モジュールのみで動作する）。

インストール

npx claude-task-worker install

マーケットプレイスの追加・プラグインのインストール・CLI 本体のグローバルインストール・CodeGraph CLI のインストールを一括で行う。いずれかが失敗しても処理は継続し、[install] プレフィックス付きでログ出力される（失敗時の終了コードは 1）。インストール後、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（ドキュメント）。

Pen CLI のログイン

.pen を扱うスキル（edit-pencil-design / inspect-pencil-node / resolve-pencil-conflict）は Pen CLI の認証を必要とする。未ログインだと .pen の読み書きが失敗するため、UIデザイン先行ワークフローを使うならインストール後に一度ログインしておく（.pen を触らないので claude-task-worker pencil ラッパー経由でなくてよい）。

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

セッショントークンは ~/.pencil/session-cli.json に保存され、以降のコマンドで再利用される。

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

export PEN_CLI_KEY=pencil_cli_...

詳細は Pen CLI のドキュメントを参照。

更新

claude-task-worker update

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

初期化

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

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

作成されるラベル:

作成されるファイル:

• .github/ISSUE_TEMPLATE/cc-triage-scope.yml — cc-triage-scope 付き Issue 作成用テンプレート
• .github/workflows/assign-creator-on-cc-triage-scope.yml — Issue 作成者の自動アサイン
• claude-task-worker.json — 設定ファイル。ワーカーごとの既定値は書き出さない（写経するとプラグイン更新で既定が変わっても古い値に固定されるため）。上書きしたいワーカーだけ手で追記する

CodeGraph のセットアップとして、グローバル gitignore（~/.config/git/ignore）へ .codegraph/ を冪等に追記し、codegraph init を実行する。CodeGraph 未インストールでも init 全体は失敗しない。

コマンド

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

pencil <args...>

@pen.dev/cli（pencil）にはアセットのベース URI を絶対 URI として解決できないバグがあり、.pen を開くと Base URI must be absolute! で失敗する。本コマンドはその修正を Node の loader hook（dist/pen-baseuri-fix.mjs）として NODE_OPTIONS 経由で注入したうえで pencil を実行するラッパー。

claude-task-worker pencil version
claude-task-worker pencil interactive -i designs/login.pen -o designs/login.pen <<'EOF'
...
EOF

引数・stdin・stdout・stderr・終了コードはすべて素通しするため、使い方は pencil と同じ。.pen を扱うスキル・エージェント（edit-pencil-design / inspect-pencil-node / resolve-pencil-conflict / pencil-design-updater など）はすべてこのラッパー経由で pencil を呼ぶ。

--epic <issue-number>

指定したエピック Issue のサブ Issue のみを処理対象に絞る。all / yolo と Issue 系ワーカーで有効。複数指定するといずれかのエピックを親に持つサブ Issue が対象になる（OR）。

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

epic-issue ワーカーだけはエピック Issue 自体が処理対象なので、指定番号は「エピック Issue 自身の番号」として照合される。

--label <label>

トリガーラベルに加えて指定ラベルが付いた Issue のみに絞る。複数指定すると全ラベルの AND。--epic と併用可能。ユーザーのスコープ指定なので、タスク完了時にワーカーが除去することはない。

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

--project <name>

指定したプロジェクト（またはグループ、all）へ herdr 経由でコマンドをディスパッチする。指定するとCLIはワーカーを直接実行せず、対象プロジェクトごとに独立した herdr ワークスペースを作ってそこでコマンドを実行する。

claude-task-worker all --project all
claude-task-worker all --project frontend
claude-task-worker exec-issue --project app-a --epic 100 --label priority-high

プロジェクト名・グループ名は $XDG_CONFIG_HOME/claude-task-worker/config.json（未設定なら ~/.config/claude-task-worker/config.json）で定義する。all は全プロジェクトを指す予約語。

{
  "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"]
  }
}

ディスパッチャーの機能:

• 一斉起動: プロジェクトごとに ctw:<プロジェクト名> ラベルのワークスペースを作り、そこで（--project を除いた）同じコマンドを実行する。ワーカーが実際に起動したかを確認し、起動しなければ再送・失敗判定する
• 稼働一覧: プロジェクト名・ワークスペースID・ペインID・ステータス・稼働時間をステータステーブルに描画する
• 一括停止: SIGTERM/SIGINT で全セッションへ ctrl-c を送り、終了を待ってワークスペースを閉じる。もう一度送ると強制終了

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

設定ファイル

グローバル設定は config.json（上記）、リポジトリ設定は実行ディレクトリ直下の claude-task-worker.json。

config.json（グローバル）

mode（タスクの実行形態）

全ワーカー・全プロジェクトに一括適用される（個別指定は不可）。

"herdr" では、worktree 作成後に ctw:<プロジェクト名>:#<番号> ラベルのタブを作り、そのルートペインで claude を TUI 起動する。agent ステータスを監視して完了を検知し、セッション transcript から最終レポートを回収して通知に使う。blocked（claude が入力待ち）になっても自動失敗にせず待機し、ステータステーブルに running:blocked と表示するので herdr のタブを開いて直接対応できる。herdr が未インストール・未起動なら起動時にエラー終了する（"default" へフォールバックしない）。

ℹ️ タスク完了時の通知音はワーカー側から止められない（音を鳴らすのは herdr サーバープロセスで、HERDR_DISABLE_SOUND もそのプロセスの環境変数として読まれるため）。無音にするには ~/.config/herdr/config.toml に [ui.sound] enabled = false を書いて herdr server reload-config する。ただし herdr サーバー全体に効くため、対話セッションの完了音も鳴らなくなる。

advisor（アドバイザーモデル）

true にすると、タスク起動時に Claude CLI へ --advisor <model> を渡す。渡すモデルは claude-task-worker.json の workers.<名前>.advisorModel。mode と同じくトップレベル一括で、プロジェクト単位・ワーカー単位のオン/オフはできない。空文字が指定されたワーカーには渡さない。

advisor は main モデル以上の能力が必要（Claude CLI の制約）。全ワーカーの既定 model が opus なので、advisorModel の既定値はすべて空文字（advisor なし）。model を sonnet 等へ下げたワーカーには advisorModel: "opus" を指定できる。

permission（権限モード）

タスク起動時に Claude CLI へ渡す権限モード。mode / advisor と同じくトップレベル一括で、プロジェクト単位・ワーカー単位の指定はできない。

値は Claude CLI の --permission-mode にそのまま渡される（choices と同じ綴り）。ワーカーには承認するユーザーがいないため、bypassPermissions / dontAsk 以外ではタスクが承認待ちで止まりうる（mode: "herdr" なら herdr のタブを開いて手動で承認できる）。

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

ワーカーごとの設定

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

既定値（skill は「Worker とスキルの対応」を参照。effort は全て high、cooldownSeconds は 0、maxConcurrentTasks は 1）:

設定例:

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

ワークフロー

Epic（親Issue）連携

親 Issue（Issue Dependencies の Parent）を持つサブ Issue を処理する場合、ワーカーはデフォルトブランチではなく cc-epic-<親Issue番号> ブランチから worktree を作成する。エピック単位でブランチをまとめることで、サブ Issue ごとのPRを単一の統合ブランチへ集約できる。エピックブランチが remote に無ければデフォルトブランチから自動派生して push される。

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

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

UI実装 Issue について、実装の前に Pencil（.pen）でデザインを作り、独立したPRとしてマージしてから実装へ進むフロー。デザインを実装PRとは別に単体でレビュー・合意でき、合意済みデザインがリポジトリに永続化される。

uiDesign.enabled によるオプトインで、既定（false）では2つのワーカーが起動しないため、Pencil を使っていないリポジトリの挙動は本機能の追加前と完全に一致する。

cc-issue-created + triage-created-issue（ルーティング）
  ├─ UI実装タスクでない → cc-exec-issue（従来どおり）
  └─ UI実装タスク       → cc-create-ui-design
        → create-ui-design ワーカー
           ・.pen を作成/更新 + snapshots/ に PNG 出力
           ・ブランチ cc-ui-design-<N> を push しデザインPRを作成（Refs #N。closing keyword は使わない）
           ・PR に cc-ui-design、Issue に cc-ui-design-pr-created を付与
        → yolo: true  → triage-pr / fix-review-point / resolve-conflict（既存フローでレビュー・マージ）
           yolo: false → 人がデザインPRをレビュー・マージ
        → apply-ui-design ワーカー
           ・デザインPRが MERGED になるまで skip
           ・Issue description に「## UIデザイン」セクションを追記
           ・cc-ui-design-ready + cc-exec-issue を付与
        → exec-issue（デザインを参照元として実装）

triage-pr は cc-ui-design 付きPRをコードレビューではなくデザイン向けの観点（差分が .pen とPNGに限定されているか、スナップショットからデザイン意図が読み取れるか、Issue 要件を満たしているか）で評価する。

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

Slack通知

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

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

通知には Claude API の使用状況（5時間/7日間の利用率とリセット時刻）も含まれる。使用状況の取得は macOS では security（Keychain）、それ以外では ~/.claude/.credentials.json を使う。あわせて RunCat Neo 用のスナップショットを ~/.claude/runcat-usage.json（RUNCAT_OUT_FILE で変更可）へ原子的に書き出す（Webhook 未設定でも更新される）。取得結果は360秒キャッシュされるため、値は最大6分古くなりうる。

プロセス管理

実行中のタスクはリアルタイムのステータステーブルで表示される。

• タスクID・タイトル・ステータス（running/completed/failed）・開始時刻・経過時間を表示
• mode: "herdr" では実行中の行に agent ステータスが併記される（running:working / running:blocked）
• 同一 Issue/PR の重複実行を自動防止
• SIGTERM/SIGINT で全子プロセスを graceful shutdown（もう一度送ると強制終了し、ラベル・worktree の後片付けを試みる）
• 前回の異常終了で残った worktree はワーカー起動時に自動回収される（実行中タスク・対話セッションが掴んでいるものは保護される）

タスク実行のガード

ワーカーは応答するユーザーがいない状態でスキルを起動するため、処理が未完のままセッションが終了してラベルだけ進む事故を防ぐガードを持つ。

• バックグラウンド実行の無効化: CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 を全タスクへ注入し、Bash の run_in_background やサブエージェントの自動バックグラウンド化を止める
• ツールの無効化: --disallowedTools で Monitor / ScheduleWakeup / AskUserQuestion / EnterPlanMode / Cron* / RemoteTrigger / EnterWorktree を無効化する
• 自律実行原則の注入: --append-system-prompt で「ユーザーに質問しない・全ステップを完遂してから終了する・曖昧なら安全側を選ぶ・サブエージェントの完了報告を検証する」および CodeGraph 優先のコード探索方針を注入する
• 完了検証: exec-issue / epic-issue は PR の実在（または Issue のクローズ）を確認できるまで cc-pr-created を付けず、確認できなければ cc-need-human-check を付けて Issue にコメントを残す
• 空振り検知: 正常終了しても出力が空のセッションは失敗として分類し、失敗通知（stderr の末尾を含む）を送る
• 起動プロセスの後片付け: スキル終了時に Stop フックが docker compose down と、worktree を作業ディレクトリに持つ残留プロセスの SIGTERM をベストエフォートで実行する（worktree はスキル完了直後に削除されるため、残留プロセスが削除の妨げになるのを防ぐ）

開発

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

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

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

ライセンス

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