claude-task-worker入門 — Issue/PRポーリングCLIを動かす

はじめに

Claude Codeを使ったGitHub運用の自動化は、多くのプロジェクトが独自スクリプトで組んでいる。Issueを定期的にポーリングし、ラベルで状態を管理し、Claude Codeにタスクを委譲する——この構成をnpmパッケージとして切り出したのが claude-task-worker である。

npmレジストリで確認したところ、記事執筆時点での最新版0.32.0は公開から1時間以内だった。依存パッケージはゼロ、MIT ライセンスの単一CLIで、実際にインストールして動かせる規模である。

この記事で学べること

• claude-task-worker が何をポーリングし、何をClaude Codeに委譲するか
• init コマンドが生成する設定ファイル・ラベル・GitHub Actionsの実物
• install と init の実行順序を間違えると何が起きるか

対象読者

• Claude CodeでGitHub Issue/PR運用を自動化している、または検討している開発者
• ラベル駆動のワーカー構成に関心がある人

前提環境

クラウド実行環境（Node.js・npm・gh CLI導入済み）で npx claude-task-worker@0.32.0 を実行して検証した。

TL;DR

• claude-task-worker はGitHub Issue/PRを定期ポーリングし、ラベルに応じてClaude Codeへ /exec-issue 等のスキルを委譲するCLI
• 個別ワーカーは exec-issue・fix-review-point・check-dependabot など10種類。all で主要ワーカーを、yolo で全ワーカーを一括起動できる
• init は12種類の cc-* ラベル・Issueテンプレート・GitHub Actions・設定ファイルを生成する
• init を install より先に実行すると、CodeGraph（コード検索用インデックス）のセットアップだけ失敗する。ただしエラーメッセージ自体が対処法を示す

claude-task-workerが解決すること

GitHub上でClaude Codeにタスクを委譲する構成を自前で組むと、ポーリング間隔の管理・ラベルによる状態遷移・同時実行数の制御・Slack通知など、Issue処理そのものより周辺の配線に手間がかかる。claude-task-worker はこの配線をCLI一本にまとめている。

--help は存在せず、引数なしで実行するとコマンド一覧が表示される仕様だった。

$ npx claude-task-worker@0.32.0
Usage: claude-task-worker <command> [--project <name>] [--epic <issue-number>] [--label <label-name>]

Commands:
  init [--force]    Create required GitHub labels and config file (use --force to overwrite existing files)
  install           Add the claude-task-worker marketplace, install the plugin, and install/update the CLI
  update            Update the claude-task-worker plugin/marketplace and the CLI itself
  usage             Notify current usage to Slack
  version           Print the installed claude-task-worker CLI version (aliases: --version, -v)

Workers:
  exec-issue        Poll issues and run /exec-issue
  fix-review-point  Poll PRs and run /fix-review-point
  create-issue      Poll issues and run /create-issue
  update-issue      Poll issues and run update command
  answer-issue-questions  Poll issues and run /answer-issue-questions
  triage-created-issue  Poll cc-issue-created + cc-triage-scope issues and run /triage-created-issue
  triage-pr         Poll and triage PRs every 5 minutes
  resolve-conflict  Poll cc-resolve-conflict PRs and run /resolve-conflict
  check-dependabot  Poll dependabot PRs every 1 hour
  epic-issue        Poll cc-epic-issue issues and create epic PR when all sub-issues are closed
  all               Poll all workers except triage-created-issue, triage-pr, check-dependabot
  yolo              Poll all workers including triage-created-issue, triage-pr, check-dependabot

コマンドは大きく2系統に分かれる。init・install・update・usage・version の5つが環境構築・管理コマンド、残り10種類が個別ワーカーで、all と yolo はその一括起動コマンドという位置づけである。個別ワーカーのうち代表的なものを抜き出すと以下の通り。

コマンド	役割
exec-issue	Issueをポーリングし /exec-issue を実行
fix-review-point	PRをポーリングし /fix-review-point を実行
create-issue	Issueをポーリングし /create-issue を実行
answer-issue-questions	Issueをポーリングし /answer-issue-questions を実行
triage-pr	PRを5分間隔でトリアージ
resolve-conflict	cc-resolve-conflict ラベルのPRのコンフリクトを解消
check-dependabot	Dependabot PRを1時間間隔でチェック
epic-issue	サブIssueが全てクローズしたらEpic PRを作成
all	triage-created-issue・triage-pr・check-dependabot を除く主要ワーカーを一括ポーリング
yolo	全ワーカーを一括ポーリング（トリアージ系・Dependabotチェックも含む）

実際にinitを実行してみる

GitHubリポジトリの外（git 管理下にない /tmp 配下）かつ gh 認証が無効なクラウド実行環境で init を実行し、生成物を確認した。

npx claude-task-worker@0.32.0 init

出力は以下の通りだった。

[init] Creating labels...
[init] Failed to create label: cc-update-issue
[init] Failed to create label: cc-answer-issue-questions
[init] Failed to create label: cc-exec-issue
[init] Failed to create label: cc-fix-onetime
[init] Failed to create label: cc-in-progress
[init] Failed to create label: cc-need-human-check
[init] Failed to create label: cc-issue-created
[init] Failed to create label: cc-pr-created
[init] Failed to create label: cc-triage-scope
[init] Failed to create label: cc-resolve-conflict
[init] Failed to create label: cc-epic-issue
[init] Failed to create label: cc-release-ready
[init] Creating issue template...
[init] Created: .github/ISSUE_TEMPLATE/cc-triage-scope.yml
[init] Creating GitHub Actions workflow...
[init] Created: .github/workflows/assign-creator-on-cc-triage-scope.yml
[init] Creating config file...
[init] Created: claude-task-worker.json
[init] Setting up CodeGraph...
[init] Failed to run codegraph init (install it with `claude-task-worker install`): spawn codegraph ENOENT
[init] Done.

12種類の cc-* ラベル作成は全て失敗した。原因は gh のトークンがこの検証環境では無効だったことと、対象ディレクトリがGitリポジトリではなかったことの2つで、実在のGitHubリポジトリかつ gh auth login 済みの環境であれば通常は成功する処理と考えられる（本検証ではラベル作成の成否ではなく、生成されるファイル・エラーメッセージの実物を確認する目的で実行した）。

一方、CodeGraph（コード検索用インデックスを構築する別ツール）のセットアップ失敗は環境要因ではない。init は codegraph コマンドの存在を前提にしているが、codegraph 自体は install コマンドで別途導入する設計になっている。コマンド一覧には install が init より先に列挙されているものの、実行順を間違えても致命的なエラーにはならず、spawn codegraph ENOENT というエラー文自体が「claude-task-worker install を実行しろ」と対処法を含んでいた。

生成された設定ファイルの中身

claude-task-worker.json には、ワーカーごとにモデル・reasoning effort・ポーリング間隔・最大同時実行数が個別設定された状態で書き出される。10種類のワーカーのうち3つを抜粋する。

{
  "workers": {
    "answer-issue-questions": {
      "skill": "/claude-task-worker:answer-issue-questions",
      "model": "opus",
      "effort": "xhigh",
      "pollingIntervalSeconds": 60
    },
    "exec-issue": {
      "skill": "/claude-task-worker:exec-issue",
      "model": "sonnet",
      "effort": "high",
      "pollingIntervalSeconds": 60
    },
    "check-dependabot": {
      "skill": "/claude-task-worker:check-dependabot",
      "model": "sonnet",
      "effort": "high",
      "pollingIntervalSeconds": 3600
    }
  }
}

質問応答（answer-issue-questions）だけOpus・xhigh effortが既定値になっており、他の実行系ワーカーはSonnet・highが既定になっていた。ポーリング間隔もワーカーごとに異なり、exec-issue は60秒、check-dependabot は3600秒（1時間）と、処理の重さと必要な即時性に応じて初期値が分かれている。コマンド一覧の説明文でも triage-pr が5分間隔・check-dependabot が1時間間隔と明記されており、設定ファイルの数値と一致する。

GitHub Actionsも1本生成される。cc-triage-scope ラベルが付いたIssueが開かれたタイミングで、Issue作成者を自動アサインするだけの小さなワークフローで、ポーリング側のワーカーが処理する前に担当者を明示しておく役割を持つ。

著者視点の発見ポイント

設定ファイルの構造を見ると、ワーカーごとにモデルとeffortを使い分ける設計は、Claude Codeを使った自動化パイプラインで共通して行き着く判断であることが分かる。質問応答のように一発の精度が重要なタスクにOpus・xhighを、定型的な実行タスクにSonnet・highを割り当てる配分は、コストと精度のトレードオフを個別チューニングせず初期値として埋め込んでいる点が実装として参考になる。

まとめ

claude-task-worker は、GitHub Issue/PRのポーリングとClaude Codeへの委譲という、自動化プロジェクトが個別に組みがちな配線をCLI一本に切り出したツールだった。init だけを先に実行してもラベル・テンプレート・設定ファイルの生成自体は問題なく完了し、codegraph のセットアップだけが install を後回しにした場合の未完了ステップとして残る。ワーカーごとのモデル・effort・ポーリング間隔の初期値は、実際にGitHub運用へ組み込む前の設計リファレンスとしても読む価値がある。

関連記事

• Claude Opus 4.7 開発者ツールガイド — task budgets・/ultrareviewの実装
• ant CLI入門 — AnthropicのClaude API専用CLIツールをマスターする
• Claude Code 2.1.200「Manual化」、中身は1行も変わっていなかった

参考リンク

• claude-task-worker (npm)
• claude-task-worker (GitHub)