github-tools-agents

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/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-sonnet-4.6',
  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.

eve extension (recommended for eve agents)

Requires eve >=0.44 (transitively ai v7). 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

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.

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.
• 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 packaged tool 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