@github-tools/sdk weekly downloads statistics

@github-tools/sdk

Give any agent GitHub access. A typed tool layer for GitHub AI agents, with presets, human approval, and durable execution. Works with eve, the AI SDK, TanStack AI, Vercel Workflow, and Chat SDK.

Docs: github-tools.com

Why not the GitHub MCP server, gh CLI, or raw Octokit?

They all reach the GitHub API, but none of them were built as an agent's tool layer. An agent still needs a schema it can fill reliably, a safety gate before it merges a PR, output shaped to fit a context window, and a way to survive a crash mid-task.

| | @github-tools/sdk | GitHub MCP server | gh CLI | Raw Octokit |

| Integration | Native AI SDK and TanStack AI tools | MCP wire protocol via a separate process | Shell-out from the agent | Hand-written per call | | Human approval | Built in, on by default | Host-dependent, inconsistent | None | You build it | | Durable / retryable | Workflow entry point uses "use step" | No | No | No | | Scoped by task | Presets (10 built-in) | Full server surface, or manual filtering | Full CLI surface | You build it | | Token-efficient output | Shaped and truncated by design | Raw API responses | Raw text, needs parsing | Raw API responses | | Native eve / Workflow / Chat SDK | Yes | No | No | No |

Pick your path

| What are you building | Start here |

| A standalone GitHub agent, fast: 3 files, durable approval | eve extension | | Scripts, chat backends, or an existing AI SDK app | Quick Start below | | A TanStack AI app | TanStack AI | | Production agents that must survive restarts and timeouts | Durable Agents | | A GitHub, Slack, or Discord bot | Chat SDK docs |

84 tools cover repositories, branches, pull requests, issues, reactions, discussions, notifications, commits, releases, checks and statuses, search, gists, and workflows. See the full Tools Catalog. Write operations support granular approval control out of the box.

Installation

ai and zod are peer dependencies (ai v6 or v7; the eve subpath requires v7):

Quick Start

Presets

Use preset to get only the tools relevant to a specific use case:

Presets are composable, pass an array to combine them:

| Preset | Tools included |

| code-review | getPullRequest, listPullRequests, listPullRequestFiles, listPullRequestReviews, listPullRequestReviewThreads, getPullRequestContext, getFileContent, listCommits, getCommit, getBlame, compareCommits, getRepository, listBranches, searchCode, listCheckRuns, getCombinedStatus, updatePullRequest, addPullRequestComment, updatePullRequestComment, deletePullRequestComment, createPullRequestReview, replyToReviewComment, resolveReviewThread, requestReviewers | | issue-triage | listIssues, getIssueContext, listIssueComments, createIssue, addIssueComment, updateIssueComment, deleteIssueComment, closeIssue, updateIssue, addLabels, removeLabel, createLabel, updateLabel, deleteLabel, addAssignees, removeAssignees, listIssueReactions, addIssueReaction, listCommentReactions, addCommentReaction, getRepository, searchRepositories, searchCode, searchIssues | | repo-explorer | All read-only tools including discussions, gists, workflows, checks/statuses, and releases (no write operations) | | ci-ops | listWorkflows, listWorkflowRuns, getWorkflowRun, listWorkflowJobs, getWorkflowJobLogs, listCheckRuns, getCombinedStatus, getCiFailureContext, triggerWorkflow, cancelWorkflowRun, rerunWorkflowRun, getRepository, listBranches, listCommits, getCommit | | security-audit | Read-only exploration (getFileContent, getRepositoryTree, searchCode, listCommits, getCommit, getBlame, compareCommits), PR and CI visibility (including getWorkflowJobLogs), plus createIssue, addIssueComment, addLabels to report findings (no destructive writes) | | release-manager | listReleases, getLatestRelease, getRelease, getReleaseContext, createRelease, updateRelease, deleteRelease, compareCommits, listCommits, getCommit, listWorkflowRuns, getWorkflowRun, listPullRequests, getPullRequest, getRepository, listBranches | | discussion-moderator | listDiscussions, getDiscussion, addDiscussionComment, getRepository, searchIssues, getIssueContext, addIssueComment | | notification-inbox | listNotifications, markNotificationRead, getIssue, getPullRequest, getRepository (requires a Notifications PAT) | | pr-author | getRepository, listBranches, getFileContent, createBranch, deleteBranch, createOrUpdateFile, createPullRequest, updatePullRequest, getPullRequest, listPullRequestFiles, listPullRequestReviewThreads, replyToReviewComment, resolveReviewThread, compareCommits, getCommit | | maintainer | All 84 tools |

Start with the smallest preset that fits. Use maintainer or omit preset when you need the full catalog. Full breakdown: Tools Catalog.

For an agent that handles open-ended requests, createGithubAgent({ model, preset: 'auto' }) picks presets per call from the latest user message. It narrows the tools the model sees to at most two presets and uses the matching system prompt. When no preset clearly matches, it uses the most likely one, and read-only repo-explorer when nothing stands out, so the full catalog is never exposed. This needs ai 7.0.105 or later.

Cherry-Picking Tools

You can also import individual tool factories for full control:

Each tool factory accepts a token string. Tools use named module-level step functions with "use step" internally, ensuring proper step registration and full Node.js access when running inside a Vercel Workflow sandbox. See Durable Agents.

Approval Control

Write operations (creating issues, merging PRs, pushing files, …) require user approval by default. This is designed for human-in-the-loop agent workflows.…

Description from the npm listing.