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, <version> is a release's version (1.2.3) and <sha> 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@<version>",      "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@<version>", { "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-<version>.tgzmkdir -p ~/.config/opencode/skillscp -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 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@<version>", "--toolsets", "issues,pull_requests,projects"]    }  }}

Tools and skills

Each toolset comes with a skill that tells an agent how to use its 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:<kind> label. Issue fields (Priority, Effort, Start date, Target date and any others) are the organization's own, so only an organization's repositories have them; list filters by one with field.<name>:<value> in query.

Pull requests and stacks (pull_requests)

The skill is github-pull-requests, shown as github-tools:github-pull-requests in Claude Code and github-tools:pull-requests in Hermes. The tools do not push: push the branch first and pass the commit it pushed as head_sha, so a pull request opens, is reviewed or merges on exactly that commit. Closing issues are kept as Closes #N lines in the body, since GitHub has no other way to link them. Stacks use GitHub's REST stack endpoints, so the gh stack extension is not needed. Attachments need gh 2.99 or newer.

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. A column that mirrors an organization's issue field is read like any other, but its value is the issue's own: the board tools refuse to set or clear it, and github_issue_edit does both. github_project_field_ensure with issue_field: true adds such a column, and github_project_create with dates: "issue_fields" uses the issue fields Start date and Target date as an organization board's dates.

Repositories (repos)

The toolset is off by default: add repos to toolsets. The skill is github-repos, shown as github-tools:github-repos in Claude Code and github-tools:repos in Hermes. Most settings changes need admin permission on the repository, and rulesets on a private repository need a paid plan. Deleting, renaming, transferring or forking a repository is left to the user.

Releases (releases)

The toolset is off by default: add releases to toolsets. The skill is github-releases, shown as github-tools:github-releases in Claude Code and github-tools:releases in Hermes. A new release is always a draft; assets are not covered yet.

Actions (actions)

The toolset is off by default: add actions to toolsets. The skill is github-actions, shown as github-tools:github-actions in Claude Code and github-tools:actions in Hermes. Every Actions write asks each time, since a workflow can deploy or publish whatever its name says. Enabling or disabling a workflow, deleting a run and downloading artifacts are not covered yet.

Reads and writes

Every read tool is named github_<domain>_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 takes the same settings. A flag wins over its environment variable, and an option or setting wins over the variable too.

Lists are comma-separated in a flag or a variable. GitHub Actions does not let a secret or configuration variable be named GITHUB_*, so in a workflow pass a value through env: from a secret of another name, e.g. GITHUB_TOOLS_READ_ONLY: ${{ secrets.TOOLS_READ_ONLY }} (setting such an environment variable in env: is allowed). Where each harness reads them:

• OpenCode takes the plugin options shown above, with lists as arrays and read_only as a boolean, and falls back to the variables. V2 runs plugins in its background service, which keeps the environment it started with: a variable set where opencode run starts has no effect until the service is restarted in that environment (opencode service restart). V1 runs plugins in its own process.

• Hermes takes plugins.entries.github-tools.settings in config.yaml:

  yaml

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

  The plugin passes its own environment to the command line it runs, so the variables work too. A running gateway keeps the environment it started with; restart it (hermes gateway restart) after changing one.

• Claude Code, Grok Build and Antigravity start the plugin's server without flags and pass it the client's environment, so set the variables in the environment the harness runs in.

• Codex passes a plugin's MCP server only a few basic variables (such as PATH and HOME) and those the plugin's manifest names, which are the variables above: set them in the environment Codex runs in. To pass flags, or to give the server another variable it needs, add the server under [mcp_servers] in Codex's config.toml instead of using the plugin: flags go in args, env_vars names the variables to forward from Codex's environment, and env sets fixed values.

  toml

  [mcp_servers.github-tools]command = "npx"args = ["-y", "@craftsamo/github-tools@<version>", "--toolsets", "issues,pull_requests,projects"]env_vars = ["GITHUB_TOOLS_READ_ONLY"]

Layout

• src/core/ — the tools, free of any harness.
• src/mcp/ — the MCP server, built to dist/mcp.js and run by github-tools.
• src/opencode/ — the OpenCode plugin, built to dist/opencode.js.
• src/cli/ — the command line the Hermes plugin calls, built to dist/cli.js and run by github-tools-cli.
• src/hermes/, plugin.yaml and __init__.py — the Hermes plugin.
• skills/ — one skill per toolset, skills/<name>/SKILL.md, which every harness that takes skills loads from the package or plugin root.
• .claude-plugin/, .codex-plugin/, .agents/plugins/, .mcp.json, .antigravity-plugin/ and mcp_config.json — the plugin manifests of the other harnesses. Codex reads .codex-plugin/plugin.json; a root plugin.json would make it load the plugin as an Agent Plugin, whose tool budget hides tools past a fixed size. The root .mcp.json is the configuration Grok Build reads (with ${CLAUDE_PLUGIN_ROOT}, the variable both Grok Build and Claude Code expand); when working on this repository in Claude Code, decline the project MCP server it offers from that file.

How a release is made is in RELEASING.md.

License

MIT