GitHub tools for AI agents

Use this skill when the user wants GitHub API access from an LLM via the @github-tools/sdk package: generateText / streamText, createGithubAgent, or durable createDurableGithubAgent with the Vercel Workflow SDK.

Official docs: https://github-tools.com, with paths such as /getting-started/installation, /getting-started/quick-start, /frameworks/ai-sdk, /frameworks/tanstack-ai, /frameworks/eve-extension, /deprecated/eve (deprecated direct import), /frameworks/vercel-workflow, /frameworks/chat-sdk, /guide/approval-control, /guide/tokens-and-auth, /api/reference. Copy-prompts for assistants are embedded on those pages.

When to use

• Build an agent (eve, recommended): "Add GitHub tools to an eve agent" / defineExtension / @github-tools/eve-extension; the direct @github-tools/sdk/eve / defineDynamic import is deprecated.
• Greenfield AI SDK app: "Add GitHub tools to my AI app" / "Wire Octokit-style ops for the model."
• Existing repo: "We already use the AI SDK, add repo/PR/issue tools."
• Reusable agent: "Use createGithubAgent with a preset" / custom system instructions.
• Durable: "Run the agent inside Vercel Workflow" / "use workflow" / crash-safe tool steps.
• Safety: "Gate merges / file writes with approval" / fine-grained PAT scopes.
• Narrow scope: Prefer a preset (code-review, issue-triage, repo-explorer, ci-ops, security-audit, release-manager, discussion-moderator, notification-inbox, pr-author, maintainer) or cherry-picked tool factories. For multi-role products, use a manager with preset-scoped sub-agents (/examples/manager-agent-with-subagents).

Install (required)

pnpm add @github-tools/sdk ai zod

Set GITHUB_TOKEN (fine-grained PAT recommended). The SDK reads process.env.GITHUB_TOKEN when token is omitted.

Quick integration patterns

Tools only

import { createGithubTools } from '@github-tools/sdk'
import { generateText } from 'ai'

await generateText({
  model,
  tools: createGithubTools({ preset: 'code-review' }),
  prompt: '…',
})

Reusable agent (ToolLoopAgent)

import { createGithubAgent } from '@github-tools/sdk'

const agent = createGithubAgent({
  model: 'anthropic/claude-opus-5.5',
  preset: 'code-review',
  context: { owner: 'vercel', repo: 'ai', pullNumber: 42 },
})
await agent.generate({ prompt: 'Review this PR' })

Durable agent (Vercel Workflow)

Requires optional peers: workflow, @ai-sdk/workflow. Import from @github-tools/sdk/workflow.

import { createDurableGithubAgent } from '@github-tools/sdk/workflow'
import { getWritable } from 'workflow'

export async function run(messages: ModelMessage[], token: string) {
  'use workflow'
  const agent = createDurableGithubAgent({ model, token, preset: 'maintainer' })
  const writable = getWritable<UIMessageChunk>()
  await agent.stream({ messages, writable })
}

Limitation: Durable agents require @ai-sdk/workflow and WorkflowChatTransport on the client for resumable streams. For predicate/once approval policies, use the eve extension.

TanStack AI

Use @github-tools/sdk/tanstack for native TanStack server-tool arrays, individual factories, and the prebuilt agent. Install @tanstack/ai alongside the SDK's ai and zod peers. Install @tanstack/ai-vercel-gateway for Gateway chat or default Jev evaluation:

pnpm add @github-tools/sdk @tanstack/ai@0.64 @tanstack/ai-vercel-gateway@0.3 ai zod

import { createGithubAgent } from '@github-tools/sdk/tanstack'
import { vercelGatewayText } from '@tanstack/ai-vercel-gateway'

const agent = createGithubAgent({
  adapter: vercelGatewayText('anthropic/claude-opus-5'),
  preset: 'auto',
  requireApproval: 'auto',
})
const text = await agent.generate({ prompt: 'List open PRs on vercel/ai.' })

generate() returns a string and throws on approval interrupts; stream() returns native TanStack events. Keep GITHUB_TOKEN and Gateway credentials on the server. TanStack auto modes use decide() with Gateway Jev; configure a custom evaluator with evaluation.adapter, not evaluation.model. Thresholds match the AI SDK integration. Gateway is optional with another chat adapter and custom evaluator.

For direct chat() use, pass the array from createGithubTools(). Auto approval additionally requires middleware: [createGithubApprovalMiddleware({ tools })] and interrupts: [githubToolApproval]. Import the interrupt from the browser-safe @github-tools/sdk/tanstack/interrupts entry point and register it on the client too. Resolve it with { approved: boolean } and preserve TanStack resume data and message history. The prebuilt agent installs the server middleware automatically. Auto-preset continuations skip routing and expose repo-explorer plus pending GitHub tools. Static boolean approvals use TanStack's native tool-approval flow. See /frameworks/tanstack-ai.

eve extension (recommended for eve agents)

Requires eve as a peer, declared * and checked through the extension's generated capability metadata (transitively ai v7); built against eve 0.64. Mount from @github-tools/eve-extension under agent/extensions/.

// agent/extensions/github.ts
import githubExtension from '@github-tools/eve-extension'

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

See ./references/eve-extension.md and /frameworks/eve-extension.

eve agent, direct import (deprecated)

Requires optional peers: eve, ai v7. Import from @github-tools/sdk/eve. Prefer the eve extension above for new agents.

// agent/tools/github.ts
import { createGithubTools } from '@github-tools/sdk/eve'

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

See ./references/eve-agents.md and /deprecated/eve.

Presets

Preset	Purpose
code-review	PRs, commits, files, review comments, review threads (list/reply/resolve)
issue-triage	Issues via getIssueContext, comments, reactions, create/close, assignees
repo-explorer	Read-only + search + discussions/gists/workflows reads
ci-ops	Actions workflows, runs, job logs, trigger/cancel/rerun
security-audit	Vulnerability scanning, risk reporting
release-manager	Changelog generation, release cutting
discussion-moderator	Discussions list/get/comment plus light issue context
notification-inbox	User notification triage (needs Notifications PAT)
pr-author	Branches (create/delete), file edits, open/update PRs, respond to review threads
maintainer	All 84 tools

Array presets merge: preset: ['code-review', 'issue-triage']. Start with the smallest preset that fits; use maintainer when you need the full catalog. Multi-role: manager + sub-agents each with one preset.

For an agent that takes open-ended requests, createGithubAgent({ preset: 'auto' }) picks presets per call from the latest user message, narrows the active tools, and uses the matching system prompt. It combines at most two presets; when none clearly matches it uses the most likely one (read-only repo-explorer when nothing stands out). It never exposes the full catalog. The AI SDK integration needs ai >= 7.0.105; TanStack uses its own evaluation API. Not on the durable agent.

Working context

Pass context: { owner, repo, pullNumber?, issueNumber?, ref? } to createGithubTools / createGithubAgent / createDurableGithubAgent to default those fields on tool inputs and inject them into the agent system prompt. Prefer composite tools (getPullRequestContext, getIssueContext, getReleaseContext, getCiFailureContext) for multi-part reads — call follow-up reads in the same step when possible. Diff patches are omitted by default — set includePatch: true (optionally with filenames) when you need specific diffs. Bodies are truncated by default (detail: 'summary'). getIssueContext returns labelNames (strings) rather than full label objects. Prefer getFileContent with startLine/endLine or maxLines for large files. getWorkflowJobLogs returns the last 200 log lines with timestamps stripped — raise maxLines (up to 2000) only when needed. listPullRequestReviewThreads returns unresolved threads only by default with truncated comment bodies. REST list tools return { items, hasMore, page, nextPage } (or add those fields next to checkRuns / runs); when hasMore, call with nextPage or raise maxPages — never the same page. Filter listCommits with path / author / since / until. Prefer a path prefix on getRepositoryTree over recursive: true. Object-shaped execute results include rateLimit (remaining / limit / reset / resource); it is stripped from the model-facing output. On 403/429 the error text includes remaining/reset.

Classifiable failures are structured evlog catalog errors (githubToolsErrors, codes prefixed github_tools.) with why/fix fields: 401 UNAUTHORIZED, 403 FORBIDDEN, 403/429 RATE_LIMITED, 404 NOT_FOUND (also thrown when the token cannot see a private resource — GitHub masks no-access as 404), 422 VALIDATION_FAILED, plus auth/Connect codes (TOKEN_REQUIRED, OIDC_TOKEN_EXPIRED, CONNECT_USER_NOT_CONNECTED, …). In eve, tool failures return { error: { code, message, why, fix, link } }; with generateText/streamText the message alone is forwarded and is self-sufficient — use evlog's parseError for the full structure.

Write safety

• Default: writes go through approval (AI SDK tool approval flow) unless requireApproval: false or per-tool overrides.
• For interactive agents, prefer requireApproval: 'auto': low-risk writes (labels, assignees, reactions, comments, review replies, reviewer requests, notification reads, workflow re-runs) run without a prompt when an evaluation model rates them low-risk and asked for by the user; everything else still asks. Per tool: { updateIssue: 'auto', mergePullRequest: true }. Tune with evaluation: { maxRisk, minIntent, model } for AI SDK/eve, or adapter instead of model for TanStack. The AI SDK integration needs ai >= 7.0.105; TanStack uses its own evaluation API. Not on the durable agent. If the evaluation model fails (not enabled on AI Gateway, no credits, outage), 'auto' approval asks and preset: 'auto' uses repo-explorer, each logging a github_tools.EVALUATION_FAILED warning.
• Map token scopes to tools (Actions, Contents, Issues, Pull requests, Discussions, Gists, …). Reactions fall under Issues. Gist and notification tools need account-level PAT permissions and do not work with a Vercel Connect installation token.
• Prefer addIssueReaction / addCommentReaction over a comment when only acknowledging a thread.

Durable steps

Each AI SDK tool wrapper uses a named module-level "use step" function so individual GitHub calls register as workflow steps when running under the Workflow SDK. See ./references/durable-workflows.md.

Reference Documentation

Each reference file includes YAML frontmatter with name, description, and tags for searchability. Use the search script available in scripts/search_references.py to quickly find relevant references by tag or keyword.

• Durable Workflows: Best practices for using GitHub tools within Vercel Workflow, including step directives and streaming responses.
• eve Extension: Recommended way to add GitHub tools to an eve agent, mount as an extension via defineExtension, approval policies, and the examples/eve starter.
• eve Agents (deprecated): Register GitHub tools in eve via the deprecated direct defineDynamic import.
• Existing Project Integration: How to integrate GitHub tools into an existing codebase, including environment variable management and framework-specific hooks.
• Tokens and Approval: Guidance on mapping GitHub token scopes to specific tools and configuring approval flows for safe write operations.

Searching References

# List all references with metadata
python scripts/search_references.py --list

# Search by tag (exact match)
python scripts/search_references.py --tag <tag>

# Search by keyword (across name, description, tags, and content)
python scripts/search_references.py --search <query>

Scripts

• scripts/search_references.py: Search reference files by tag, keyword, or list all with metadata