GitHub Tools

github-tools

GitHub tools for coding agents: issues, project boards, pull requests, repositories, releases and Actions. One implementation, delivered to each agent harness in the form that suits it best.

0.3.0 moved the package from craftsamo/agent-github to craft-agent/github-tools and renamed it: npm @craftsamo/github-tools (was @craftsamo/agent-github, now removed from npm), plugin and MCP server github-tools, programs github-tools and github-tools-cli, settings GITHUB_TOOLS_*. Allow rules, plugin installs and MCP configurations written for 0.2.0 change; the tool IDs do not.

The tools need Node.js 24 or later and the GitHub CLI, authenticated as you. docs/conventions.md describes how the tools are named and how they behave.

Install

Install from a release, never from the default branch: a release is a tag whose commit carries the built dist/, and the default branch does not. In the commands below, is a release's version (1.2.3) and is the commit its tag names:

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

OpenCode

OpenCode V2 takes the package and its options in opencode.json:

{

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

OpenCode V1 takes the package as a string, or as a pair with its options:

{

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

OpenCode allows any action no rule names, so the plugin's request is granted silently unless a rule says ask. Read tools never ask, so the github_* glob is safe.

V1 registers no skills. Unpack the package and copy its skills/* folders into ~/.config/opencode/skills/:

npm pack @craftsamo/github-tools@<version>

tar -xzf craftsamo-github-tools- .tgz mkdir -p ~/.config/opencode/skills cp -r package/skills/* ~/.config/opencode/skills/ rm -rf package craftsamo-github-tools- .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 turns - into _ in server names, so it shows the tools as mcp__github_tools__github_issue_*. It starts the MCP server in the plugin's install directory, so name issues as owner/repo#N or pass repo (a bare number fails there with a message saying so).

Grok Build

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

Grok starts the MCP server in the session's working directory, so inside a clone a bare issue number names an issue of that repository.

Antigravity

Install from the tree of the release tag, never from the default branch, which has no built dist/; Antigravity clones the tag into ~/.gemini/config/plugins/github-tools.

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

Hermes Agent

Hermes installs a commit, not a tag, and the plugin installs disabled:

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

hermes plugins enable github-tools

If a Hermes gateway is already running, restart it (hermes gateway restart) to load the plugin.

Any other MCP host

Add the server to the host's MCP configuration. Flags go in args:

{

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

Tools and skills

Each toolset comes with a skill that tells an agent how to use its tools. A toolset with no tools yet registers none (so far issues and projects have tools).

Issues (issues)

The skill is github-issues, shown as github-tools:github-issues in Claude Code and github-tools:issues in Hermes. An issue's kind is the organization's Issue Type of that name when it defines one, otherwise a type: label.

Project boards (projects)

The skill is github-projects, shown as github-tools:github-projects in Claude Code and github-tools:projects in Hermes. A board is named by its number, owner/N, URL or title (Roadmap when none is given), and found among the boards linked to the repository, then its organization's, then the viewer's. The token needs the project scope (gh auth refresh -s project). No API sets a roadmap view's date fields, so after github_project_create set the Roadmap view's "Date fields" to Start and Target in the web UI.

Reads and writes

Every read tool is named github_ _read. Reads can run unasked; writes are confirmed by the harness.

Where a write is asked about, and where it is not:

• OpenCode grants any action no rule names, so a write runs unasked unless a rule asks for it: add the github_* rule shown under OpenCode.
• Codex under codex exec, and Grok Build under grok -p, refuse a write they cannot ask about, unless it is allowed beforehand.
• Grok Build calls the plugin's tools through its use_tool tool, and the agent often names a tool without its server first (github_project_read). Grok checks the rules against the name as given, so the server-qualified rule alone does not match that first call, and grok -p refuses it and stops instead of letting the agent retry with github-tools__github_project_read. The second rule matches the short name; a write still matches neither.
• Antigravity asks before any MCP tool no rule allows, reads included, and names the plugin's server github-tools_github-tools (plugin, then server). agy -p refuses a tool it cannot ask about; --dangerously-skip-permissions runs every tool unasked.
• Hermes hermes chat -q refuses a write it cannot ask about; hermes -z and --yolo skip approval, so writes then run unasked.

Settings

Every entry point