gitworthy

Gitworthy

コーディングエージェントが作業を始める前の判断レイヤー。

Gitworthy は、コーディングエージェントが実装に時間を費やす前に、ソフトウェア作業の候補を調査し、順位付けし、事前確認できるよう支援します。有望な候補を見つけ、作業がすでに対応済みか、またはブロックされているかを確認し、各対象について根拠に基づく ACT、VERIFY、または SKIP の判断を返します。

MCP の設定 · CLI · エージェントのワークフロー · 判定 · トラブルシューティング · 事例 · ロードマップ · コントリビューション

---

Gitworthy が必要な理由

コーディングエージェントによって実装のコストは下がります。しかし、誤ったタスクを選ぶと、依然として大きなコストがかかります。

イシューが未対応に見えても、次のような場合があります。

• 関連付けられていないブランチに、すでに修正が存在する。
• 別のコントリビューターが、進行中のプルリクエストを作成している。
• 変更は main に取り込まれているが、まだリリースされていない。
• リポジトリでは、作業を受け付ける前に割り当てが必要である。
• 重複した実装や放棄された実装に、すでに答えが含まれている。

Gitworthy は、人やエージェントが次の作業に取りかかる前に、この事前確認を行います。

エージェントによる Gitworthy の使用方法

ループを担うのはエージェントです。Gitworthy は、作業の調査と検証のためにエージェントが呼び出す MCP 判断エンジンです。

Contribution goal, repository, or organization
                      │
                      ▼
         Cursor / ChatGPT / Hermes / agent
                      │
                 Gitworthy MCP
                      │
                      ▼
        policy → scan → rank → preflight
                      │
             ┌────────┼────────┐
             ▼        ▼        ▼
            ACT     VERIFY    SKIP
          queue it   inspect   drop it
             │
             ▼
     optional `portfolio`
     (mode + dispatch, not a new verdict)
             │
             ▼
       Ranked candidate shortlist
             │
             ▼
         Select a candidate
             │
             ▼
   recheck → reproduce → implement → review

明確に分かれたレーンが 2 つあります。

• 調査レーン： 候補を発見、絞り込み、順位付け、事前確認し、候補リストを返します。
• 実行レーン： 対象を選択し、作業の意思を記録し、最新の状態を再確認し、再現、実装、レビューを行い、リポジトリで許可されているコントリビューション手順で提出します。

ACT は「検討する価値がある」という意味であり、「考えずにコーディングを始める」という意味ではありません。調査結果は古くなるため、エージェントが実際に対象を引き受けるとき、または着手するときに、Gitworthy を再実行する必要があります。

エージェントの完全なポリシー、ツール選択ガイド、調査から実行への引き継ぎについては、docs/AGENT_WORKFLOW.md を参照してください。

Cursor、ChatGPT、Hermes、または任意の MCP クライアントで使用する

ローカル stdio（デスクトップ／エージェント VM）

{
  "mcpServers": {
    "gitworthy": {
      "command": "npx",
      "args": ["-y", "gitworthy@latest", "mcp"],
      "env": {
        "GITHUB_TOKEN": "github_pat_..."
      }
    }
  }
}

Streamable HTTP（Cloud Agents／モバイル／iPad）

同じエンジンを HTTP 経由で実行またはデプロイし、クライアントに URL を指定します。

export GITWORTHY_MCP_TOKEN="$(openssl rand -hex 32)"
export GITHUB_TOKEN="github_pat_..."
npx -y gitworthy@latest mcp --http --host 127.0.0.1 --port 8787

{
  "mcpServers": {
    "gitworthy": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:GITWORTHY_MCP_TOKEN}"
      }
    }
  }
}

ループバック以外のアドレスにバインドするには、GITWORTHY_MCP_TOKEN が必要です。GITHUB_TOKEN はサーバー上で管理してください。デプロイの詳細と Cloud Agent に関する注意事項は、docs/HTTP_MCP.md を参照してください。ツールの説明、アノテーション、構造化された結果については、docs/MCP.md を参照してください。持ち運び可能な Agent Plugins のパッケージ化（スキル + MCP）については、docs/AGENT_PLUGINS.md を参照してください。

エージェントには、次のようなポリシーを指定してください。

外部リポジトリでの作業に時間を費やす前に、Gitworthy を使用してください。hunt を使って、順位付けされた短いキューを作成してください。各候補の worth_check を確認してください。hunt は全体で 1 つの判定を出すものではありません。ACT はキュー内の候補として扱い、VERIFY には指定された確認を実行し、SKIP の候補は除外してください。選択した対象を実装する前に、worth_check を再実行し、リポジトリのコントリビューションポリシーに従ってください。

トークンに必要なのは、公開リポジトリへの読み取りアクセスだけです。関連作業の検出精度を最大限に高めるには、クラシック PAT、または Issues: Read を付与したきめ細かなトークンを使用してください。これにより、Gitworthy がタイムラインの相互参照を確認できます。権限の弱いトークンでも動作しますが、参照できない情報は not_checked に報告されます。

30 秒で試す

環境の準備ができていることを確認します。

npx -y gitworthy@latest doctor --json

特定のイシューを評価します。

npx -y gitworthy@latest check owner/repo#123

保存済みの判断から、決定論的な引き継ぎブリーフを生成します。

npx -y gitworthy@latest brief decision_abc123 --format markdown --out brief.md

ブリーフの生成ではローカルストアを読み取るだけで、GitHub、npm、LLM への呼び出しは行いません。保存済みの判断は 24 時間経過すると古いものとみなされます。古いブリーフでは警告が表示され、recheck が推奨されます。

コントリビューション先の短いリストをスカウトし、事前チェックします。

npx -y gitworthy@latest hunt owner/repo --json
npx -y gitworthy@latest hunt openclaw --max-checks 3 --json

調査には @latest を使用します。再現可能なエージェントのワークフローや CI では、バージョンを固定してください。

hunt が実際に返すもの

hunt は範囲を限定した絞り込み処理であり、大量の結果に一括で判定を下すコマンドではありません。

contribution policy
        ↓
scan repository or organization
        ↓
rank issue quality and optional skill fit
        ↓
remove obvious land-only, assigned, weak, or known-SKIP rows
        ↓
run worth_check on only the best few candidates
        ↓
return candidates with individual verdicts and evidence

エージェントは各 hunt_candidate.worth_check を確認してください。Gitworthy は、広範なスキャンで返されたすべてのイシューに対して、コストの高いフル事前チェックを実行することを意図的に避けています。

ACT、VERIFY、または SKIP

判定	スカウト時の動作	実行時の動作
ACT	根拠を確認したうえで、優先順位付きキューに追加します。	着手を表明したり実装したりする前に再チェックします。最新の状態とポリシーで引き続き許可されている場合にのみ進めます。
VERIFY	未解決の確認事項を明示して提示します。	フォークしたり公開の場で表明したりする前に、それらの確認事項を解決します。
SKIP	キューから削除します。	並行作業を始めず、引用されている作業を確認するか、別の対象を選びます。

判定は雰囲気に基づくスコアではありません。Gitworthy は、構造化された根拠、完了したチェック、完了できなかったチェックを返します。

実際の事前チェック

block/buzz の対象イシューはオープンに見えましたが、ほぼ同じタイトルのプルリクエストですでに実装が行われていました。

Target: block/buzz#1659
Verdict: VERIFY
Disposition: review

Evidence:
- An implementation exists in PR #1675.
- The pull request is linked work, not a duplicate issue.

Next action:
Inspect the current implementation before starting parallel work.

このケースでは、重複検出における誤検出の経路も明らかになりました。GitHub のイシュー API にはプルリクエストも含まれます。この修正は回帰テストとキャリブレーションケースになりました。

その他の実際のコントリビューション事例は、CASE_STUDIES.md に記載されています。

仕組み

Gitworthy は、タスクへの着手が危険または無駄になる可能性のあるさまざまな要因を見極める、範囲を限定したチェックを組み合わせます。

チェック	防止する事態
関連作業	既存のプルリクエスト、割り当て、参照されているコミット、過去の試行
ブランチスキャン	関連付けられていないリモートブランチにすでに存在する作業
イシューと main の比較	イシューがオープンのまま、修正が取り込まれている事態
リリースとの差分	公開済みパッケージに含まれていない main 上の変更
コントリビューションポリシー	着手表明の要件、割り当てルール、プルリクエストを受け付けないリポジトリ
重複分析	関連するイシューや、以前に報告されたイシュー
スキャン／組織スキャン	優先順位の付いていないイシュートラッカーのノイズ
Hunt	コストの高い事前チェックの前に候補を絞り、無駄な広範囲チェックを防止

CLI と MCP サーバーは、同じ TypeScript コアを利用する薄いアダプターです。

信頼モデル

Gitworthy は、確認していないことまで把握しているかのように装うことなく、役立つように設計されています。

• ヒューリスティックな根拠だけで、単独でハードな SKIP を下すことはできません。
• ハードな SKIP には決定的な根拠が必要です。
• 必須チェックに失敗した場合、結果は VERIFY が上限になります。
• すべての実際の結果に、意味のある checked フィールドと not_checked フィールドが含まれます。
• 判定の決定に、人が読む文章を解析することはありません。
• 対象のリポジトリとパッケージは、信頼できない入力として扱われます。
• テレメトリーはデフォルトでオフです。MCP の経路ではテレメトリーを送信しません。
• スカウトの結果は恒久的なものとはみなされません。実行には最新の再検証が必要です。

ACT は「何も考えずにコーディングを始める」という意味ではありません。作業に取りかかる前に、根拠、処置、理由、関連作業、リポジトリのポリシーを確認してください。

エージェント向けの出力

すべてのコア結果には、構造化されたエンベロープが含まれます。

{
  "verdict_summary": "one sentence",
  "evidence": [],
  "signals": [],
  "checked": [],
  "not_checked": [],
  "cached": false,
  "fetched_at": "2026-01-01T00:00:00.000Z"
}

signals は、判定ポリシーを支える重要な入力です。checked と not_checked は結果の一部であり、脚注ではありません。

よく使うコマンド

gitworthy check owner/repo#123 [--npm-package name] [--json]
gitworthy hunt owner/repo [--manifest path] [--max-checks 3] [--json]
gitworthy portfolio owner/repo [--max-items 10] [--json]
gitworthy prs owner/repo [--json]
gitworthy ci-triage --head-check test:failure --base-check test:success [--json]
gitworthy history owner/repo --path src/core/hunt.ts [--json]
gitworthy opportunity-ingest --source hermes-eval --id case-9 [--json]
gitworthy scan owner/repo [--label "help wanted"] [--json]
gitworthy org owner [--manifest path] [--max-repos 8] [--json]
gitworthy policy owner/repo [--json]
gitworthy init [--user] [--repo] [--json]
gitworthy config validate [--path path] [--manifest path] [--json]
gitworthy config show --effective [--json]
gitworthy profile show [--json]
gitworthy related owner/repo [issue] [--json]
gitworthy ledger show owner/repo#123 [--json]
gitworthy doctor [--json]
gitworthy mcp
gitworthy mcp --http [--host 127.0.0.1] [--port 8787] [--stateless]

check の終了コード：

• 0 — ACT
• 10 — VERIFY
• 20 — SKIP
• 1 — エラー

厳格なコントリビューションのゲートについては SKILL.md を、ワークフローの解説については docs/AGENT_WORKFLOW.md を参照してください。

ドキュメント

ドキュメント	トピック
docs/AGENT_WORKFLOW.md	調査と実行の違い、ツールの選択
docs/VERDICTS.md	ACT／VERIFY／SKIP と判定
docs/CLI.md	CLI リファレンスと終了コード
docs/MCP.md	MCP ツール、アノテーション、構造化された結果
docs/AGENT_PLUGINS.md	Agent Plugins v1 のパッケージング（スキル＋MCP）
docs/HTTP_MCP.md	Streamable HTTP MCP
docs/CONFIG.md	設定、マニフェスト、プロファイル
docs/DATA.md	ローカルストア、結果、キャプチャ
docs/EVALS.md	固定／ライブ／プライベート評価
docs/CORPUS.md	コーパスの分類（合格率と適合率）
docs/CORPUS_CONTRIB.md	Track O と Track F の拡充方法
docs/TRACK_O.md	結果のキャリブレーション（Track O。リリースゲートではありません）
docs/BETA.md	デザインパートナー向けベータ版（GW-034）
docs/SECURITY_MODEL.md	信頼境界
docs/TROUBLESHOOTING.md	Doctor による修復
docs/COMPATIBILITY.md	1.0 未満の契約ポリシー
docs/PERFORMANCE.md	カウンターと予算
docs/RANKING.md	ランキングの契約
docs/RELEASE_1.0.md	1.0 ゲートのチェックリスト

設定

• GITHUB_TOKEN／GH_TOKEN を設定すると、認証済みの GitHub REST チェックが有効になります。
• 設定ファイルはデータのみを含む JSON です。Gitworthy はユーザー設定を ~/.gitworthy/config.json から、リポジトリローカルの設定を .gitworthy/config.json から読み込みます。
• 優先順位は CLI／MCP の入力、GITWORTHY_* 環境変数、リポジトリ設定、ユーザー設定、組み込みのデフォルト値の順です。gitworthy config show --effective --json には、有効な各値の出所が含まれます。
• gitworthy init --repo または gitworthy init --user で、シークレットを含まないひな形を作成できます。gitworthy config validate で検証します。
• スキルプロファイル（設定内の profile または --skill-profile）には、languages、topics、preferred_ecosystems、および回避リストを指定できます。これらが影響するのはスキャン／探索のランキング入力だけで、判定ポリシーには影響しません。
• ターゲットマニフェスト（--manifest path または設定内の manifest_path）には、リポジトリ／組織、対象に含める／除外するフィルター、リポジトリごとの npm パッケージマッピング、ターゲット固有のオーバーライドを指定できます。あいまいな npm パッケージマッピングは拒否されます。対象に含める／除外するフィルターは検証され、GW-019 ではマニフェストメタデータとして保持されます。フィルターの完全な適用は GW-027 まで延期されています。
• トークンや認証情報が設定ファイルやマニフェストに保存されることはありません。GITHUB_TOKEN／GH_TOKEN などの環境変数を使用してください。
• GITWORTHY_MCP_TOKEN は Streamable HTTP MCP 用のベアラーシークレットです（ループバック以外にバインドする場合は必須です）。
• GITWORTHY_CACHE_DIR を設定すると、~/.gitworthy/cache のキャッシュを上書きします。
• GITWORTHY_LEDGER_DIR を設定すると、~/.gitworthy/ledger のローカル調査履歴を上書きします。
• GITWORTHY_TELEMETRY=on と GITWORTHY_POSTHOG_KEY を設定すると、任意のテレメトリが要求されます。

任意の PostHog テレメトリを使うには、ユーザーがインストールした posthog-node パッケージも必要です。パッケージが見つからない場合、Gitworthy は一度だけ警告し、テレメトリを無効にして処理を続行します。

GitHub トークンがない場合、GitHub REST を必要とするチェックは構造化エラーまたは明示的な not_checked エントリーを返します。公開 git または npm エンドポイントを利用できるチェックは引き続き実行されます。

現在の状況

Gitworthy は 1.0 未満であり、判定契約、悪意ある入力への対応、ローカルでの結果、評価コーパス、導入手順の強化を積極的に進めています。

1.0 の目標は、信頼できるローカルファーストの CLI および MCP 判定エンジンです。ホスト型 SaaS でも、別のコーディングエージェントでもありません。

リリースの段階については ROADMAP.md を参照してください。

今後の展望

Gitworthy は、タスクの発見から実装までをつなぐ、エージェントネイティブな準備状況レイヤーへと進化しています。

1. 候補となる作業を発見する；
2. 有望な対象を順位付けする；
3. それぞれが実際に着手可能か判断する；
4. 機械で実行可能な次のステップを返す；
5. 選択した作業を実行前に再検証する；
6. 実際に起きたことを記録する；
7. 実際の結果から、今後の判断を改善する。

オープンソースの意思決定エンジンは、ローカルファーストで MIT ライセンスのまま維持されます。1.0 以降に追加される可能性のあるレイヤーには、共有の結果履歴、スケジュールされた調査、プライベートリポジトリの連携、エージェントへのディスパッチ用 API などがあります。

貢献

Gitworthy は、一見着手可能に見える作業が、すでに対応済みだったり、阻害されていたり、安全に開始できなかったりした実例をもとに開発されています。

特に価値の高い貢献は次のとおりです。

• Gitworthy が誤った判断をした事例；
• 正しく調査できないリポジトリやエコシステム；
• Cursor、ChatGPT、Claude Code、Codex、OpenClaw、Hermes、その他のエージェントとの連携；
• エビデンスの品質や失敗の報告の改善；
• 新たな固定評価ケース；
• 他の人がすばやく有用な結果を得るのに役立つドキュメント。

開発環境のセットアップと信頼要件については、CONTRIBUTING.md を参照してください。

要件

• Node.js 22 以降
• 実際の調査では GitHub トークンの使用を強く推奨します

セキュリティ

脆弱性は SECURITY.md を利用するか、[email protected] までメールで非公開に報告してください。

ライセンス

MIT