Introduction

@github-tools/sdk is a typed tool layer that gives an AI agent GitHub access. The catalog is large on purpose — so you can build almost any GitHub agent — and presets (or manager + sub-agents for multi-role products) keep that catalog out of the context window. Mount it as an eve extension in one file for a complete, durable GitHub agent, or drop it into any AI SDK app.

The GitHub REST API isn't an agent tool layer on its own: 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 does all four: presets scope what an agent can touch, human approval gates every write by default, outputs are shaped and truncated for token economy, and every tool runs as a durable workflow step.

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. Wiring GitHub into an agent by hand (or through a generic tool bridge) means an input schema the model can fill reliably, output shaping so raw payloads don't blow up the context window, a safety gate before the model merges a PR, and a way to survive a crash mid-task. Multiply that by every operation the agent needs.

Concretely, the SDK gives you:

• Typed inputs: every tool ships a Zod schema with described fields, so models fill arguments correctly.
• Shaped outputs: responses are trimmed and truncated to what the model needs, not raw REST payloads.
• Write safety by default: all 24 write tools require human approval unless you opt out.
• Scoped capability: presets expose only the tools a workflow needs.
• Durable by design: every tool runs as a "use step" boundary, so calls are retryable workflow steps under Vercel Workflow.

A GitHub agent in 3 files

The fastest path from zero to a working GitHub agent is eve, Vercel's filesystem-first agent framework. One extension file registers every tool the agent needs:

You are a GitHub code-review assistant.

import { defineAgent } from 'eve'

export default defineAgent({
  model: 'anthropic/claude-sonnet-5',
})

import githubExtension from '@github-tools/eve-extension'

export default githubExtension({
  preset: 'code-review',
})

Run npx eve dev and you have a GitHub agent with durable human-in-the-loop approval on every write. Full walkthrough: Build a GitHub agent with the eve extension. For several roles in one product, see Manager agent with scoped sub-agents.

Works with your framework

The same tools plug into every major agent runtime. Pick the entry point that matches your stack:

The direct @github-tools/sdk/eve import is deprecated in favor of the eve extension above.

Explore the tools

The SDK covers repositories, branches, pull requests, issues, reactions, discussions, notifications, commits, releases, checks and statuses, code search, gists, and workflows: 75 tools in total. Each tool wraps a GitHub API operation (mostly REST; line-level blame and the discussion tools use GraphQL) and is fully typed with Zod schemas.

Browse the full list in the Tools Catalog.

Compose tools with presets

Instead of wiring tools individually, use a preset to get a curated subset for a specific workflow:

Presets compose as arrays: preset: ['code-review', 'issue-triage']. Multi-role products often work better as a manager with preset-scoped sub-agents. Learn more in Scope with Presets.

Safety is not an afterthought

Every write operation (merging a PR, pushing a file, closing an issue) is gated behind approval by default. You choose the policy:

createGithubTools({
  requireApproval: {
    mergePullRequest: true,   // always ask
    addIssueComment: false,   // never ask
  },
})

On the eve extension, approval goes further with 'once' (approve once per session) and input-dependent predicates. Combine with least-privilege token scopes for defense in depth. Details: Control Write Safety.

Why github-tools

Agent Skills

Install the github-tools-agents skill with npx skills add https://github-tools.com, or use the copy-paste prompts embedded on Installation, Quick Start, and the other guide pages. Details: Agent Skills.

External references

• AI SDK docs
• eve documentation
• GitHub REST API reference
• Octokit REST.js