github-tools

github-tools

コーディングエージェント向けのGitHubツール：イシュー、プロジェクトボード、プルリクエスト、 リポジトリ、リリース、Actionsに対応しています。1つの実装を、それぞれの エージェントハーネスに最適な形で提供します。

Harness	Delivery	Pinned by
OpenCode V2	ネイティブプラグイン（npmパッケージ、スキル付き）	パッケージ内のバージョン
OpenCode V1	ネイティブプラグイン（npmパッケージ、スキルなし）	パッケージ内のバージョン
Claude Code	プラグイン：MCP サーバーとスキル	参照先としてリリースタグ
Codex	プラグイン：MCP サーバーとスキル	参照先としてリリースタグ
Grok Build	プラグイン：MCP サーバーとスキル	@refとしてのリリースタグ
Antigravity	プラグイン：MCP サーバーとスキル	リリースタグのツリーURL
Hermes Agent	ネイティブプラグイン（Python、コマンドラインを呼び出す）	SHAとしてのリリースコミット
other MCP host	npmのMCP サーバー	パッケージ内のバージョン

0.3.0でパッケージの場所がcraftsamo/agent-githubからcraft-agent/github-toolsに移り、名前も変更されました。npmでは@craftsamo/github-tools（以前は@craftsamo/agent-github。現在はnpmから削除済み）、プラグインとMCP サーバーはgithub-tools、プログラムはgithub-toolsとgithub-tools-cli、設定はGITHUB_TOOLS_*です。0.2.0向けに作成された許可ルール、プラグインのインストール、MCP設定は変更が必要ですが、ツールIDは変わりません。

このツールにはNode.js 24以降と、 あなたのアカウントで認証済みの GitHub CLIが必要です。 docs/conventions.mdでは、ツールの命名規則と 動作について説明しています。

インストール

デフォルトブランチではなく、必ずリリースからインストールしてください。リリースはビルド済みのdist/を含むコミットを指すタグですが、デフォルトブランチには含まれていません。以下のコマンドでは、<version>はリリースのバージョン（1.2.3）、<sha>はタグが指すコミットです：

gh api repos/craft-agent/github-tools/commits/v<version> --jq .sha

OpenCode

OpenCode V2では、opencode.jsonでパッケージとそのオプションを指定します：

{
  "plugins": [
    {
      "package": "@craftsamo/github-tools@<version>",
      "options": { "toolsets": ["issues", "pull_requests", "projects"] }
    }
  ],
  "permissions": [{ "action": "github_*", "resource": "*", "effect": "ask" }]
}

OpenCode V1では、パッケージを文字列として指定するか、オプションと組み合わせて指定します：

{
  "plugin": [["@craftsamo/github-tools@<version>", { "toolsets": ["issues", "pull_requests", "projects"] }]],
  "permission": { "github_*": "ask" }
}

OpenCodeでは、ルール名がないアクションはすべて許可されるため、ルールでaskを指定しない限り、プラグインのリクエストは通知なしで許可されます。読み取りツールは確認を求めないため、github_*グロブを安全に使えます。

V1はスキルを登録しません。パッケージを展開し、skills/*フォルダーを~/.config/opencode/skills/にコピーします：

npm pack @craftsamo/github-tools@<version>
tar -xzf craftsamo-github-tools-<version>.tgz
mkdir -p ~/.config/opencode/skills
cp -r package/skills/* ~/.config/opencode/skills/
rm -rf package craftsamo-github-tools-<version>.tgz

Claude Code

claude plugin marketplace add craft-agent/github-tools#v<version>
claude plugin install github-tools@craft-agent

Codex

codex plugin marketplace add craft-agent/github-tools --ref v<version>
codex plugin add github-tools@craft-agent

Codexはサーバー名の-を_に変換するため、ツールは mcp__github_tools__github_issue_*として表示されます。MCP サーバーはプラグインのインストールディレクトリで起動するため、イシューはowner/repo#Nの形式で指定するか、repoを渡してください（単なる数値では失敗し、その旨を示すメッセージが表示されます）。

Grok Build

grok plugin install craft-agent/github-tools@v<version> --trust

Grokはセッションの作業ディレクトリでMCP サーバーを起動するため、クローン内では、単なるイシュー番号でそのリポジトリのイシューを指定できます。

Antigravity

デフォルトブランチにはビルド済みのdist/がないため、必ずリリースタグのツリーからインストールしてください。Antigravityはタグを~/.gemini/config/plugins/github-toolsにクローンします。

agy plugin install https://github.com/craft-agent/github-tools/tree/v<version>

Hermes Agent

Hermesはタグではなくコミットをインストールし、プラグインは無効の状態でインストールされます：

hermes plugins install craft-agent/github-tools --ref <sha>
hermes plugins enable github-tools

Hermesゲートウェイがすでに実行中の場合は、再起動してプラグインを読み込みます（hermes gateway restart）。

その他のMCPホスト

ホストのMCP設定にサーバーを追加します。フラグはargsに指定します：

{
  "mcpServers": {
    "github-tools": {
      "command": "npx",
      "args": ["-y", "@craftsamo/github-tools@<version>", "--toolsets", "issues,pull_requests,projects"]
    }
  }
}

ツールとスキル

各ツールセットには、エージェントにツールの使い方を伝えるスキルが付属します。ツールがまだないツールセットは何も登録しません（現時点でツールがあるのはissuesだけです）。

Issues（issues）

ツール	内容	分類
github_issue_read	1 つの issue の全体を view するか、リポジトリの issue または親 issue の sub-issue を list します	読み取り
github_issue_create	種類、ラベル、担当者、マイルストーン、親 issue、ブロック元の issue を指定して issue を作成します	追加
github_issue_edit	タイトル、本文（追記も可能）、種類、ラベル、担当者、マイルストーンを変更します	上書き
github_issue_comment	issue にコメントします	追加
github_issue_close	理由（completed、not_planned、duplicate）を指定して issue をクローズします	上書き
github_issue_reopen	クローズ済みの issue を再オープンします	上書き
github_issue_relate	親 issue、sub-issue、ブロック元およびブロック先の issue を、差分のみ送信して設定します	冪等
github_issue_develop	issue に関連付けられたブランチを GitHub 上に作成するか、すでに関連付けられているブランチを返します	冪等

スキルは github-issues です。Claude Code では github-tools:github-issues、Hermes では github-tools:issues として表示されます。 組織で同名の Issue Type が定義されている場合、issue の種類にはそれが使われます。 定義されていない場合は、type:<kind> ラベルが使われます。

読み取りと書き込み

すべての読み取りツールの名前は github_<domain>_read です。読み取りは確認なしで実行でき、書き込みはハーネスによって確認されます。

ハーネス	確認なしでの読み取り
OpenCode	常に実行できます。プラグインが確認するのは書き込みの前だけです
Claude Code	~/.claude/settings.json またはプロジェクトの permissions.allow にあるルール mcp__plugin_github-tools_github-tools__*_read
Codex	常に実行できます。Codex は読み取りツールと同様に、readOnlyHint を宣言したツールを確認なしで実行します
Grok Build	grok --allow 'MCPTool(github-tools__*_read)'
Antigravity	~/.gemini/antigravity-cli/settings.json の permissions.allow にあるルール mcp(github-tools_github-tools/github_issue_read)。読み取りツールごとに 1 つ
Hermes	常に実行できます。プラグインが確認するのは書き込みの前だけです

書き込みの確認を求める場合と、求めない場合：

• OpenCode はルール名の指定がなければどの操作も許可するため、ルールで求めない限り書き込みは確認なしで実行されます。OpenCode にある github_* ルールを追加してください。
• Codex の codex exec と Grok Build の grok -p は、事前に許可されていない書き込みについて確認できない場合、実行を拒否します。
• Antigravity は、ルールで許可されていない MCP ツールについて、読み取りを含めて実行前に確認を求めます。プラグインのサーバー名は github-tools_github-tools です（プラグイン名、続いてサーバー名）。agy -p は確認できないツールの実行を拒否します。--dangerously-skip-permissions はすべてのツールを確認なしで実行します。
• Hermes の hermes chat -q は、確認できない書き込みの実行を拒否します。hermes -z と --yolo は承認を省略するため、その場合、書き込みは確認なしで実行されます。

設定

すべてのエントリーポイントで同じ設定を使用します。フラグは環境変数より優先され、オプションまたは設定も環境変数より優先されます。

設定	フラグ	変数	意味
toolsets	--toolsets	GITHUB_TOOLS_TOOLSETS	issues、pull_requests、projects、repos、releases、actions、または all。デフォルトは issues と pull_requests です
read_only	--read-only	GITHUB_TOOLS_READ_ONLY	書き込みを行うツールを登録しません。他のすべての設定より優先されます
tools	--tools	GITHUB_TOOLS_TOOLS	ツールセットに関係なく、IDを指定して個別のツールを追加します
exclude_tools	--exclude-tools	GITHUB_TOOLS_EXCLUDE_TOOLS	IDを指定して個別のツールを除外します。tools と toolsets より優先されます
confirm	--confirm	GITHUB_TOOLS_CONFIRM	MCP サーバーのみ：docs/conventions.md の説明にある harness（デフォルト）または elicitation

フラグまたは変数のリストはカンマ区切りです。GitHub Actions では、シークレットや設定変数の名前に GITHUB_* を使用できないため、ワークフローでは別の名前のシークレットから env: を通じて値を渡してください。例：GITHUB_TOOLS_READ_ONLY: ${{ secrets.TOOLS_READ_ONLY }}（env: でこのような環境変数を設定することは許可されています）。各ハーネスでの読み込み方法は次のとおりです。

• OpenCode では、上記のプラグイン options を使用します。リストは配列、read_only はブール値です。

• Hermes では、config.yaml の plugins.entries.github-tools.settings を使用します。

  plugins:
    entries:
      github-tools:
        settings:
          toolsets: [issues, pull_requests, projects]
          read_only: false
          exclude_tools: [github_pr_merge]
  

• Claude Code と Antigravity では、フラグなしでプラグインのサーバーを起動し、クライアントの環境を渡します。そのため、ハーネスの実行環境で変数を設定してください。

• Codex と Grok Build では、プラグインの MCP サーバーに環境変数を渡さないため、GITHUB_TOOLS_* 変数は効果がありません。Codex で設定を変更するには、プラグインを使用する代わりに、その他の MCP ホスト のように、Codex の設定にある [mcp_servers] の下で args にフラグを指定してサーバーを追加してください。

構成

• src/core/ — ハーネスに依存しないツールです。
• src/mcp/ — MCP サーバーです。dist/mcp.js にビルドされ、github-tools で実行されます。
• src/opencode/ — OpenCode プラグインです。dist/opencode.js にビルドされます。
• src/cli/ — Hermes プラグインが呼び出すコマンドラインです。dist/cli.js にビルドされ、github-tools-cli で実行されます。
• src/hermes/、plugin.yaml、__init__.py — Hermes プラグインです。
• skills/ — ツールセットごとに1つのスキルを配置します。skills/<name>/SKILL.md にあり、スキルを使用するすべてのハーネスがパッケージまたはプラグインのルートから読み込みます。
• plugin.json、mcp.json、.mcp.json、.claude-plugin/、.agents/plugins/、.antigravity-plugin/、mcp_config.json — その他のハーネスのプラグインマニフェストです。ルートの .mcp.json は Grok Build が読み込む設定です（Grok Build と Claude Code の両方が展開する変数 ${CLAUDE_PLUGIN_ROOT} を使用します）。Claude Code でこのリポジトリを作業する際は、このファイルから提示されるプロジェクトの MCP サーバーを拒否してください。

リリースの作成方法については、RELEASING.md を参照してください。

ライセンス

MIT