Agent Github

agent-github

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.2.0 renamed the MCP server from github to agent-github, so allow rules and MCP configurations written for 0.1.0 change.

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/craftsamo/agent-github/commits/v<version> --jq .sha

OpenCode

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

{  "plugins": [    {      "package": "@craftsamo/agent-github@<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/agent-github@<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/agent-github@<version>tar -xzf craftsamo-agent-github-<version>.tgzmkdir -p ~/.config/opencode/skillscp -r package/skills/* ~/.config/opencode/skills/rm -rf package craftsamo-agent-github-<version>.tgz

Claude Code

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

Codex

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

Codex 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 craftsamo/agent-github@v<version> --trust

Antigravity

Install from the tree of the release tag, never from the default branch, which has no built dist/. The pinning and the install command are not yet verified on a real install.

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

Hermes Agent

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

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

Any other MCP host

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

{  "mcpServers": {    "agent-github": {      "command": "npx",      "args": ["-y", "@craftsamo/agent-github@<version>", "--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 (0.2.0 ships the issues tools).

Issues (issues)

The skill is github-issues. An issue's kind is the organization's Issue Type of that name when it defines one, otherwise a type:<kind> label.

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.
• 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. Where each harness reads them:

• OpenCode takes the plugin options shown above, with lists as arrays and read_only as a boolean.

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

  yaml

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

• Claude Code and Antigravity start the plugin's server without flags; Claude Code passes the client's environment, so set the variables in the environment the harness runs in.

• Codex and Grok Build pass no environment to a plugin's MCP server, so the AGENT_GITHUB_* variables have no effect there. To change settings in Codex, add the server under [mcp_servers] in Codex's config with flags in args (as in Any other MCP host) instead of using the plugin.

Layout

• src/core/ — the tools, free of any harness.
• src/mcp/ — the MCP server, built to dist/mcp.js and run by agent-github.
• 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 agent-github-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.
• plugin.json, mcp.json, .mcp.json, .claude-plugin/, .agents/plugins/, .antigravity-plugin/ and mcp_config.json — the plugin manifests of the other harnesses. 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